shipper_get_groom_session
shipper_get_groom_session
Section titled “shipper_get_groom_session”List actionable paused grooming question sessions, or retrieve the complete current question batch for exactly one issue or session ID. This local-only read reports ownership and direct MCP answerability without resuming, changing, or taking over a session. Optional repository_path selects an existing local git checkout for this call only; omit repository_path to use the active repository. Target preparation uses that checkout’s local identity and settings without changing active server state, and successful result payloads are unchanged.
When to use
Section titled “When to use”Use no selector to list every actionable grooming session paused on a non-empty current question batch in the selected repository; this successful list is unpaginated and may be empty. Supply exactly one issue or exact session_id to retrieve detail containing the current worker message and every stable answer ID, question, analysis, optional recommendation/header, option, and multiSelect value required by shipper_answer_question. Summaries never contain questions. Both modes exclude prior answers, transcripts, grooming notes, saved stages, storage metadata, fingerprints, and pull-request overlap evidence. MCP-, Desktop-, terminal-owned, and legacy unowned sessions are equally visible. mcp_can_answer reports current direct routing authority only; reading never resumes, discards, takes over, transfers ownership, or changes answer authority. Current workflow_state is independently enriched from read-only issue state; a healthy session remains visible without it and receives a content-free recovery diagnostic when enrichment is unavailable. Invalid peers are omitted from discovery with safe diagnostics, while a targeted invalid record is unavailable. Duplicate session IDs are ambiguous and require retrying with issue; an issue with no pending batch is not paused. Optional repository_path targets one existing local checkout for this call only and does not change the active repository or process state.
Behavior hints
Section titled “Behavior hints”- readOnlyHint: true — The tool reads local durable session and issue-state records without changing sessions, ownership, or repository state.
- idempotentHint: true — Repeated calls are side-effect free; results change only when another workflow operation changes local state.
- openWorldHint: false — The tool is local-only and never consults GitHub or another remote service.
Input schema
Section titled “Input schema”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| issue | integer | string | no | - | Shipper issue reference. S# |
| session_id | string | no | - | Optional exact, byte-for-byte grooming session ID. Do not trim the value. |
| repository_path | string | no | - | Optional repository path to an existing local git checkout to select for this read only. Omit it to read the active repository. |
Output schema
Section titled “Output schema”{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {}, "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "listed" }, "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id", "github_issue_number", "display_ref", "title"], "additionalProperties": false }, "session_id": { "type": "string" }, "owner": { "type": "string", "enum": ["mcp", "desktop", "terminal", "unowned"] }, "mcp_can_answer": { "type": "boolean" }, "stage": { "type": "string", "const": "groom" }, "condition": { "type": "string", "const": "awaiting_answers" }, "answered_rounds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workflow_state": { "anyOf": [ { "type": "string", "enum": [ "shipper:new", "shipper:groomed", "shipper:designed", "shipper:planned", "shipper:pr-open", "shipper:rework", "shipper:ready" ] }, { "type": "string", "const": "shipper:failed" } ] } }, "required": [ "repository", "issue", "session_id", "owner", "mcp_can_answer", "stage", "condition", "answered_rounds", "created_at", "updated_at" ], "additionalProperties": false } }, "diagnostics": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "record_unreadable", "invalid_json", "unsupported_schema", "unsupported_compact_format", "invalid_record", "filename_identity_mismatch", "repository_mismatch", "workflow_state_unavailable", "issue_reference_ambiguous", "invalid_issue_reference", "issue_store_read_failed", "issue_store_operation_pending" ] }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id"], "additionalProperties": false }, "session_id": { "type": "string" }, "message": { "type": "string" }, "guidance": { "type": "string" } }, "required": ["code", "message", "guidance"], "additionalProperties": false } } }, "required": ["status", "repository", "sessions", "diagnostics"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "available" }, "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id", "github_issue_number", "display_ref", "title"], "additionalProperties": false }, "session_id": { "type": "string" }, "owner": { "type": "string", "enum": ["mcp", "desktop", "terminal", "unowned"] }, "mcp_can_answer": { "type": "boolean" }, "stage": { "type": "string", "const": "groom" }, "condition": { "type": "string", "const": "awaiting_answers" }, "answered_rounds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "workflow_state": { "anyOf": [ { "type": "string", "enum": [ "shipper:new", "shipper:groomed", "shipper:designed", "shipper:planned", "shipper:pr-open", "shipper:rework", "shipper:ready" ] }, { "type": "string", "const": "shipper:failed" } ] }, "worker_message": { "type": "string" }, "questions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "analysis": { "type": "string" }, "recommendation": { "type": "string" }, "header": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": "string" } }, "required": ["label"], "additionalProperties": false } }, "multiSelect": { "type": "boolean" } }, "required": ["id", "question", "analysis", "options", "multiSelect"], "additionalProperties": false } }, "diagnostics": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "record_unreadable", "invalid_json", "unsupported_schema", "unsupported_compact_format", "invalid_record", "filename_identity_mismatch", "repository_mismatch", "workflow_state_unavailable", "issue_reference_ambiguous", "invalid_issue_reference", "issue_store_read_failed", "issue_store_operation_pending" ] }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id"], "additionalProperties": false }, "session_id": { "type": "string" }, "message": { "type": "string" }, "guidance": { "type": "string" } }, "required": ["code", "message", "guidance"], "additionalProperties": false } } }, "required": [ "status", "repository", "issue", "session_id", "owner", "mcp_can_answer", "stage", "condition", "answered_rounds", "created_at", "updated_at", "worker_message", "questions", "diagnostics" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "ambiguous" }, "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "matches": { "type": "array", "items": { "type": "object", "properties": { "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id"], "additionalProperties": false }, "session_id": { "type": "string" } }, "required": ["issue", "session_id"], "additionalProperties": false } }, "guidance": { "type": "string" } }, "required": ["status", "repository", "matches", "guidance"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "not_found" }, "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "session_id": { "type": "string" }, "guidance": { "type": "string" } }, "required": ["status", "repository", "session_id", "guidance"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "not_paused" }, "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "requested_issue": { "type": "string" }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id"], "additionalProperties": false }, "session_id": { "type": "string" }, "guidance": { "type": "string" } }, "required": ["status", "repository", "guidance"], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable" }, "repository": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["named", "lineage"] }, "repo": { "type": "string" } }, "required": ["kind", "repo"], "additionalProperties": false }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id"], "additionalProperties": false }, "session_id": { "type": "string" }, "diagnostics": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "record_unreadable", "invalid_json", "unsupported_schema", "unsupported_compact_format", "invalid_record", "filename_identity_mismatch", "repository_mismatch", "workflow_state_unavailable", "issue_reference_ambiguous", "invalid_issue_reference", "issue_store_read_failed", "issue_store_operation_pending" ] }, "issue": { "type": "object", "properties": { "local_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "github_issue_number": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "display_ref": { "type": "string" }, "title": { "type": "string" } }, "required": ["local_id"], "additionalProperties": false }, "session_id": { "type": "string" }, "message": { "type": "string" }, "guidance": { "type": "string" } }, "required": ["code", "message", "guidance"], "additionalProperties": false } }, "guidance": { "type": "string" } }, "required": ["status", "repository", "diagnostics", "guidance"], "additionalProperties": false } ], "x-shipper-expanded-docs": true}Example call
Section titled “Example call”{ "issue": "S#42"}Example result
Section titled “Example result”{ "status": "available", "repository": { "kind": "named", "repo": "owner/repo" }, "issue": { "local_id": 42, "github_issue_number": 123, "display_ref": "S#42 (GitHub #123)", "title": "Choose rollout mode" }, "session_id": "groom-session-42", "owner": "mcp", "mcp_can_answer": true, "stage": "groom", "condition": "awaiting_answers", "answered_rounds": 1, "created_at": "2026-09-04T12:00:00.000Z", "updated_at": "2026-09-04T12:05:00.000Z", "workflow_state": "shipper:new", "worker_message": "Choose the rollout boundary.", "questions": [ { "id": "rollout", "question": "Which audience?", "analysis": "This controls exposure.", "options": [{ "label": "Internal" }], "multiSelect": false } ], "diagnostics": []}Error modes
Section titled “Error modes”- Selector conflict: Provide either issue or session_id, not both.
- Session ID not found or ambiguous: An exact ID miss returns not_found; duplicate IDs return only safe matching identities and guidance to retry with issue.
- Issue not paused: A missing issue session or a valid session without a current pending batch returns not_paused.
- Saved record unavailable: Unreadable, invalid, unsupported, mismatched, or ambiguous records return content-free diagnostics and recovery guidance without question content.