AskUserQuestionTool: Ask the user a question

Many people see AskUserQuestionTool for the first time and think: Isn't it just "asking the user a question"?
But in Claude Code, it actually solves a much deeper problem:

When the model needs additional information mid-execution, how do we make "asking a question" a formal, structured, interactive system capability instead of just casually typing out natural language. This is particularly important for Agent products because it relates to:

• Requirement clarification
• Multi-choice decision-making
• Solution comparison
• Information supplementation in Plan Mode

tools/AskUserQuestionTool/AskUserQuestionTool.tsx:

const inputSchema = z.strictObject({
  questions: z.array(questionSchema()).min(1).max(4),
  answers: z.record(z.string(), z.string()).optional(),
  annotations: annotationsSchema(),
  metadata: z.object({ source: z.string().optional() }).optional(),
})

And a single question itself also has a very complete structure:

const questionSchema = z.object({
  question: z.string(),
  header: z.string(),
  options: z.array(questionOptionSchema()).min(2).max(4),
  multiSelect: z.boolean().default(false),
})

This shows that it is not ordinary chat, but a formal form-style interaction tool.

tools/AskUserQuestionTool/prompt.ts specially defines a preview mechanism:

Use the optional `preview` field on options when presenting concrete artifacts that users need to visually compare:
- ASCII mockups of UI layouts or components
- Code snippets showing different implementations
- Diagram variations

This is interesting because it means this tool doesn't just ask multiple-choice questions; it can already support:

• Solution A vs. Solution B comparison
• UI sketch comparison
• Configuration example comparison
• Code implementation comparison In other words, Anthropic has made "interactive clarification" a product-level capability.

Ambiguity encountered during model execution > AskUserQuestionTool > Generate structured questions and options > Front-end renders interactive card > User selects/fills in > Structured answers flow back > Model continues execution

The prompt file contains a very critical note:

Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan.
Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ExitPlanMode for plan approval.

• In Plan Mode, if you are still missing requirement information, use this tool to fill that in first.
• But if you have already finished writing the plan and want to ask "Is the plan good?", you should no longer use it.
• Instead, hand it over to ExitPlanModeTool at this point. This prompt is highly representative because it shows:

AskUserQuestionTool isn't just for asking questions—it also handles part of the operational boundaries between tools.

The source code also contains an important uniqueness validation:

const UNIQUENESS_REFINE = {
  message: 'Question texts must be unique, option labels must be unique within each question'
}

This means Claude Code does not allow it to randomly generate duplicate questions or options.
It is completely different from casually outputting a chunk of chat text. Anthropic clearly treats this type of questioning as "formal user interaction," rather than casual conversational filler.

For example, when Claude is implementing a feature and finds that two approaches are both valid:

1. It should not just guess/make up a decision on its own
2. It will use AskUserQuestionTool to list out the options
3. After the user selects one, the answer flows back to the main thread
4. Claude then continues execution along the chosen direction The biggest difference between this path and ordinary chat is:

• Results can be structured
• Options are explainerable
• Can include previews

In other words:

• AskUserQuestionTool: I'm missing information, need to ask more.
• ExitPlanModeTool: The plan is complete, please approve it. These two tools cannot be used interchangeably.

Without this tool, the model has only two poor choices when encountering ambiguity:

1. Blindly guess on its own
2. Casually ask a question in natural language Claude Code's approach takes the third path:

Make questioning a formal interaction protocol. This makes the system significantly more stable in several ways:

• Questions are more concise
• User selections are clearer
• Subsequent execution is more controllable
• Metrics tracking and product iteration are easier

False.
It is actually Claude Code's "user collaboration interface."

Not exactly.
Plan approval, permission requests, and certain system confirmations have their own dedicated mechanisms.

Quite the opposite.
It supports multiple questions, multi-select options, annotations, and previews.

If you want to grasp its essence, remember this:

AskUserQuestionTool turns "requirement clarification during execution" into a structured product interaction capability—it is not an ordinary chat question, but a formal collaboration interface within Claude Code’s main loop.