question-policy

Question policy

Claude Code removes AskUserQuestion from every subagent. Only the main session can ask. So every agent in a pipeline emits questions as data, and the orchestrator in the main session decides whether to ask, using the mode resolved by ship_config.py.

Modes

Mode	Agent behavior	Orchestrator behavior
auto (default)	pick recommended, append to decisions.md, continue; a question with no recommended is guarded (below)	copy decisions.md into the PR body under "Decisions made autonomously"
raise	stop and return NEEDS_INPUT with the questions	ask at once, write answers.json, resume the same agent

Escalation guard

escalate lists question properties that are never auto-decided. The default is ["irreversible"]; "external" adds questions whose impact is external. A question with no recommended option is always guarded, whatever escalate says: a recommendation exists only with an evidence-backed lean, and a coin flip logged as a decision would misrepresent itself.

A guarded question is handled as in raise mode, whatever the mode. Headless, where nothing can be asked, the orchestrator marks the story blocked with the question in its status rather than guessing.

Set --escalate=none to drop the irreversible guard.

What is not a question

A permission denial, a missing tool, a command that will not run, or a path that does not exist is an operational block, not a fork in the work. An agent that hits one returns FAILED with the blocker in summary and does not dress it up as a question; the orchestrator marks the story blocked and names the blocker, because the remedy is in the environment, not in an answer. The code-reviewer without the Agent tool is not blocked: it reviews in a single pass and says so.

Question contract

Agents return questions inside their envelope. references/question.schema.json is the normative schema. The shape mirrors the house rules every interactive command in this marketplace already follows, so a question renders faithfully through AskUserQuestion: