AskUserQuestionTool：向用户提问

很多人第一次看到 AskUserQuestionTool，会觉得它不就是“向用户提问”吗？
但在 Claude Code 里，它其实解决的是一个更深的问题：

当模型执行到一半需要补信息时，如何把“提问”做成正式、结构化、可交互的系统能力，而不是随手打一句自然语言。

这对于 Agent 产品特别重要，因为它关系到：

• 需求澄清
• 多选决策
• 方案比较
• 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(),
})

而单个问题本身也有非常完整的结构：

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

这说明它不是普通聊天，而是一个正式的表单式交互工具。

tools/AskUserQuestionTool/prompt.ts 里专门定义了 preview 机制：

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

这很有意思，因为它意味着这个工具并不只是问选择题，而是已经能支持：

• 方案 A / 方案 B 对比
• UI 草图对比
• 配置示例对比
• 代码实现对比

也就是说，Anthropic 把“互动式澄清”做成了一个产品层能力。

模型执行中遇到歧义 > AskUserQuestionTool > 生成结构化问题与选项 > 前端渲染交互卡片 > 用户选择/填写 > 答案结构化回流 > 模型继续执行

prompt 文件里有一段非常关键：

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.

• 在 Plan Mode 里，如果你还缺需求信息，先用这个工具补齐
• 但如果你已经写完计划，想问“计划行不行”，那不该再用它
• 这时应该交给 ExitPlanModeTool

这段 prompt 很有代表性，因为它说明：

AskUserQuestionTool 不只是问问题，它还承担工具职责边界的一部分

源码里还有一个很重要的唯一性校验：

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

也就是说，Claude Code 不允许它胡乱生成重复问题、重复选项。
这和随便输出一段聊天文本完全不同。

Anthropic 很明显是把这类提问当成“正式用户交互”，而不是附属对话。

比如 Claude 在实现功能时发现有两个方案都成立：

1. 它不应该自己拍脑袋决定
2. 它会用 AskUserQuestionTool 把选项列出来
3. 用户选完后，答案会回流到主线程
4. Claude 再按选中的方向继续执行

这条路径和普通聊天最大的不同是：

• 结果可结构化
• 选项可解释
• 还能附带 preview

也就是说：

• AskUserQuestionTool：我还缺信息，继续问
• ExitPlanModeTool：计划已经完成，请你审批

这两个工具不能混用。

如果没有这个工具，模型在遇到歧义时只有两个糟糕选择：

1. 自己瞎猜
2. 在自然语言里随便问一句

而 Claude Code 的做法是第三种：

把提问做成正式交互协议

这会让系统在几个方面明显更稳定：

• 提问更简洁
• 用户选择更清晰
• 后续执行更可控
• 统计与产品迭代更容易

不是。
它实际上是 Claude Code 的“用户协同接口”。

也不对。
计划审批、权限申请、某些系统确认有其他专门机制。

并不是。
它支持多问题、多选、注释、preview。

如果你想抓住它的本质，可以记这句话：

AskUserQuestionTool 把“执行中的需求澄清”做成了结构化的产品交互能力，它不是普通聊天问句，而是 Claude Code 主循环中的正式协作接口。