[DOCS] Hooks reference missing AskUserQuestion PreToolUse answer flow

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

PreToolUse tool input and decision-control reference, with a related cross-reference from the headless (claude -p) docs

Current Documentation

The docs currently say:

In the hooks reference: Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: Bash, Edit, Write, Read, Glob, Grep, Agent, WebFetch, WebSearch, and any MCP tool names`.

Later on the same page: PreToolUse hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level decision field, PreToolUse returns its decision inside a hookSpecificOutput object. This gives it richer control: three outcomes (allow, deny, or ask) plus the ability to modify tool input before execution. | permissionDecision | "allow" skips the permission prompt. "deny" prevents the tool call. "ask" prompts the user to confirm. | | updatedInput | Modifies the tool's input parameters before execution. Combine with "allow" to auto-approve, or "ask" to show the modified input to the user |

The tools reference separately says: | AskUserQuestion | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

The headless page says: This page covers using the Agent SDK via the CLI (claude -p). For the Python and TypeScript SDK packages with structured outputs, tool approval callbacks, and native message objects, see the full Agent SDK documentation.

No code.claude.com page currently explains how AskUserQuestion can be satisfied through PreToolUse in a headless integration.

What's Wrong or Missing?

Changelog v2.1.85 says:

PreToolUse hooks can now satisfy AskUserQuestion by returning updatedInput alongside permissionDecision: "allow", enabling headless integrations that collect answers via their own UI

A. The hooks reference does not tell users that AskUserQuestion now reaches PreToolUse

The current PreToolUse section lists several tool names, but not AskUserQuestion. Users reading the hooks docs cannot tell that this tool can now be intercepted and answered programmatically.

B. The required answer payload is undocumented on code.claude.com

The hooks docs explain updatedInput generically, but they never show the AskUserQuestion-specific shape: the original questions array plus an answers object mapping each question text to the selected label or labels.

C. The headless docs do not explain the non-interactive clarifying-question flow

The claude -p page points readers to the Agent SDK docs in general, but it does not say that clarifying questions can now be satisfied programmatically in headless runs instead of requiring an interactive Claude Code prompt.

Suggested Improvement

Add a short AskUserQuestion subsection to the hooks reference and cross-link it from the headless docs.

Suggested content:

AskUserQuestion can also trigger PreToolUse. To satisfy it programmatically, return hookSpecificOutput.permissionDecision: "allow" together with updatedInput containing the original questions array and an answers object. Each answers key is the question text and each value is the selected option label (or comma-separated labels for multi-select questions). This lets claude -p integrations collect answers in their own UI and continue without an interactive prompt.

Also add a minimal JSON example showing the required questions pass-through and answers mapping.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | PreToolUse input and decision-control docs omit AskUserQuestion matching and the required answer payload |
| https://code.claude.com/docs/en/headless | Headless integration docs do not mention programmatically satisfying AskUserQuestion in -p flows |
| https://code.claude.com/docs/en/tools-reference | AskUserQuestion is listed as a tool, but there is no cross-reference to hook-based handling for headless use |
| https://platform.claude.com/docs/en/agent-sdk/user-input | Agent SDK cross-reference already documents the question/answer structure, which the code-site hook docs should align with |

Total scope: 4 pages affected

Source: Changelog v2.1.85

Exact changelog entry:

PreToolUse hooks can now satisfy AskUserQuestion by returning updatedInput alongside permissionDecision: "allow", enabling headless integrations that collect answers via their own UI