shipper_answer_question

Provide answers to a paused headless worker that asked questions. The worker resumes with the supplied answers and continues until it either defers again (returning another awaiting_answer payload) or completes.

When to use

Use this only after shipper_groom or shipper_advance returns an awaiting-answer session id. If the MCP process restarts, an MCP-owned durable session with the same id and a pending batch is reconstructed and answered without rerunning a completed round. Foreign and unowned sessions refuse with content-free ownership detail; ambiguous ids refuse, and a matching MCP-owned session without a pending batch directs the caller to shipper_groom. answers must contain exactly the question ids of the current batch; question text is never accepted as a key. The call accepts only session_id and answers: any other top-level field, including the removed confirm_unvetoed batch action, is rejected as an unsupported format. A saved session that still holds the removed compact-confirmation format is reported as discarded with a plain explanation that grooming must restart. Any missing answer, unrecognized identifier, or unsupported field rejects the response atomically: none of its supplied values are forwarded or retained, the session stays paused on the unchanged current batch, and the diagnostics are followed by the same full worker message and complete question batch so the caller can retry with answers for the entire batch. If more batches are already pending from the same worker turn, the result is another single-batch awaiting_answer payload to answer before the worker can resume fully. The configured agentTimeoutMinutes limit applies independently to each agent attempt; MCP adds no stage-wide deadline, so ordinary retries, corrections, cleanup, projection, run recording, and finalization remain child-owned. Time paused awaiting product-owner answers consumes no agent-running timeout. A terminal timeout returns only after authoritative local agent_timeout history, failed workflow state, terminal MCP-attributed run status, and ownership-safe release of that run’s issue lock. In mirror-on mode, projection debt never rolls back the local failure or retains the lock and is explicitly repairable with shipper issue reconcile --repair. The timeout report identifies the stage, per-attempt limit, attempt count, available session log, discarded staged/unstaged/untracked work, and exact same-stage reset command. When commits survived, that matching reset preserves only the recorded unchanged workflow branch revision—not the physical worktree—and the next groom or scaffold run continues from it; a missing or moved ref invalidates continuation.

Behavior hints

openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
session_id	string	yes	-	Paused shipper worker session id returned by an awaiting_answer response.
answers	object	yes	-	Complete map from displayed zero-based string question ids to the answers to send back to the paused worker.

Example call

{
  "session_id": "sess-abc123",
  "answers": {
    "0": "Preserve the current response shape and add the new behavior explicitly."
  }
}

Example result

Resolved issue: S#42 (GitHub #123): Generate MCP tool reference pages
Status: awaiting_answer
Session: sess-abc123

The headless worker asked a batch of questions and is paused awaiting answers from the orchestrator.

Worker message:
The first answer resolved compatibility; this follow-up decides rollout scope and ownership.

The worker's analysis and recommendation are reasoning to weigh, not answers to ratify.
Verify them against the codebase and your own product judgment before answering.
Reply with `shipper_answer_question` providing { session_id, answers } where answers is a map
from every displayed zero-based string `id` -> your answer (free text). Use each question's `id`
field, not its question text, and submit the complete batch. Candidate options are informational;
answer in free text rather than selecting an option.

Questions (JSON):
[
  {
    "id": "0",
    "question": "Which rollout scopes should be supported?",
    "analysis": "Supporting both repository and organization scopes increases testing and ownership complexity.",
    "header": "Scope",
    "options": [
      {
        "label": "Repository",
        "description": "Configure each repository independently."
      },
      {
        "label": "Organization",
        "description": "Share configuration across repositories."
      }
    ],
    "multiSelect": true
  }
]

Error modes

Missing pending session: No live or saved grooming question session has id “<session_id>”. The worker may have already completed.
Ambiguous saved session id: Multiple saved grooming question sessions use id “<session_id>”. Resume the intended issue with shipper_groom before answering.
Unsupported compact-confirmation format: A submission carrying the removed confirm_unvetoed batch action, or any other unrecognized top-level field, is rejected whole as an unsupported format. No part of it is adopted and the unchanged pending batch remains available for a clean retry.
Saved session uses the removed compact format: Saved grooming question session “<session_id>” for S# uses the removed compact-confirmation format. Shipper discarded that saved session; restart grooming for S#.
Saved session not MCP-owned: The content-free refusal names the owner or unowned and reports saved time, answered-round count, and pending-batch presence without question or answer text.
Saved session has no pending batch: Saved MCP grooming session “<session_id>” has no pending question batch. Resume it with shipper_groom.
Restart reconstruction mismatch: The resumed MCP groom did not defer with the same session id, so no supplied answer is submitted.
Completed before answer: Cannot submit an answer: shipper child already completed.

Current-batch identifier mismatch:

Answers do not match the current question batch. Missing answers: id 1 (header Scope). Unrecognized answer identifiers: "Scope?". Session "<session_id>" is still paused; retry the same question batch with a complete answer map.

Status: awaiting_answer
Session: <session_id>

The headless worker asked a batch of questions and is paused awaiting answers from the orchestrator.

Worker message:
The unchanged batch still needs both compatibility and rollout decisions.

The worker's analysis and recommendation are reasoning to weigh, not answers to ratify.
Verify them against the codebase and your own product judgment before answering.
Reply with `shipper_answer_question` providing { session_id, answers } where answers is a map
from every displayed zero-based string `id` -> your answer (free text). Use each question's `id`
field, not its question text, and submit the complete batch. Candidate options are informational;
answer in free text rather than selecting an option.

Questions (JSON):
[
  {
    "id": "0",
    "question": "Which compatibility behavior should be preserved?",
    "analysis": "Existing clients rely on the current response shape.",
    "recommendation": "Preserve the current shape by default.",
    "header": "Compatibility",
    "options": [
      {
        "label": "Preserve default",
        "description": "Keep existing clients unchanged."
      }
    ],
    "multiSelect": false
  },
  {
    "id": "1",
    "question": "Which rollout scope should be supported?",
    "analysis": "The scope determines ownership and configuration storage.",
    "header": "Scope",
    "options": [
      {
        "label": "Repository",
        "description": "Configure each repository independently."
      }
    ],
    "multiSelect": false
  }
]

Unavailable stdin: shipper child stdin is unavailable; cannot submit answer.
No more events: Shipper child has already completed; no more events.
Enriched completion summary unavailable: After the resumed worker completes, a post-completion label, session, or linked-PR lookup can fail. The tool returns the plain observed worker result, any locally resolved final message and session log, plus Enriched completion summary unavailable. and Reason: <underlying error>; an exit-0 worker remains successful.
Worker command failure: spawn shipper ENOENT

shipper_answer_question

shipper_answer_question

When to use

Behavior hints

Input schema

Example call

Example result

Error modes

Related tools