[DOCS] Hooks reference missing AskUserQuestion PreToolUse answer flow

AskUserQuestion fires as a PreToolUse event. Handle it with:

INPUT=$(cat)
QUESTION=$(echo "$INPUT" | jq -r '.tool_input.question // empty')
echo "[AskUser] $QUESTION" >&2
if echo "$QUESTION" | grep -qiE '(continue|proceed|yes)'; then
    echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}'
fi
exit 0

---

Issue #39620 Verification

Title: [DOCS] Hooks reference missing AskUserQuestion PreToolUse answer flow
Issue Date: 2026-03-27
Verification Date: 2026-04-01
Status: PARTIALLY RESOLVED

---

Issue Summary

This issue reports that the Claude Code docs did not explain that AskUserQuestion can trigger PreToolUse, did not document the required questions plus answers payload for satisfying that tool programmatically on code.claude.com, and did not explain or cross-reference that headless claude -p flow clearly enough from the headless and tools-reference pages.

---

Verification Results

Claim 1: The hooks reference does not tell users that AskUserQuestion reaches PreToolUse

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, line 846: 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, AskUserQuestion, ExitPlanMode, and any MCP tool names.

Verdict: The hooks reference now explicitly states that PreToolUse matches AskUserQuestion.

---

Claim 2: The required AskUserQuestion answer payload is undocumented on code.claude.com

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, lines 951-954 document questions and answers, including: answers | object | {"Which framework?": "React"} | Optional. Maps question text to the selected option label. Multi-select answers join labels with commas. Claude does not set this field; supply it via updatedInput to answer programmatically.

At the same URL, lines 962-964 document updatedInput: Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones.

At the same URL, line 983 states: For AskUserQuestion, echo back the original questions array and add an answers object mapping each question's text to the chosen answer.

Verdict: The hooks page now documents both the required questions pass-through and the answers mapping needed to satisfy AskUserQuestion programmatically.

---

Claim 3: The headless docs do not explain the non-interactive clarifying-question flow

Status: UNRESOLVED

At https://code.claude.com/docs/en/headless, lines 15-21 state: 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.

At the same URL, lines 139-157 document --allowedTools and permission rule syntax, but the page does not explain AskUserQuestion, PreToolUse, permissionDecision, or updatedInput for non-interactive clarifying-question handling.

Verdict: The headless page still defers this flow to broader SDK documentation instead of documenting it directly on the claude -p page.

---

Claim 4: The tools reference does not cross-reference hook-based handling for AskUserQuestion in headless use

Status: UNRESOLVED

At https://code.claude.com/docs/en/tools-reference, line 16 lists: `AskUserQuestion | Asks multiple-choice questions to gather requirements or clarify ambiguity | No`.

At the same URL, lines 120-125 only include a generic Hooks link in the see-also section: Hooks: run custom commands before or after tool execution.

Verdict: The tools reference still does not point readers to the specific PreToolUse and updatedInput handling now documented elsewhere.

---

Current State

| Claim | Status |
|-------|--------|
| Hooks reference does not tell users that AskUserQuestion reaches PreToolUse | RESOLVED |
| Required AskUserQuestion answer payload is undocumented on code.claude.com | RESOLVED |
| Headless docs do not explain the non-interactive clarifying-question flow | UNRESOLVED |
| Tools reference does not cross-reference hook-based handling for AskUserQuestion in headless use | UNRESOLVED |

---

Suggested Fix

Update https://code.claude.com/docs/en/headless with a short section explaining that AskUserQuestion can be satisfied in claude -p via PreToolUse by returning permissionDecision: "allow" plus updatedInput containing the original questions array and an answers mapping. Add an AskUserQuestion-specific cross-reference from https://code.claude.com/docs/en/tools-reference to the hooks page or to https://platform.claude.com/docs/en/agent-sdk/user-input.

---

References

• URL: https://code.claude.com/docs/en/changelog
• Lines 101-109: v2.1.85 says PreToolUse hooks can satisfy AskUserQuestion with updatedInput and permissionDecision: "allow"
• URL: https://code.claude.com/docs/en/hooks
• Line 846: PreToolUse matcher list includes AskUserQuestion
• Lines 951-954: AskUserQuestion input documents questions and answers
• Lines 962-964: updatedInput behavior is documented
• Line 983: hooks page explains how to satisfy AskUserQuestion in -p
• URL: https://code.claude.com/docs/en/headless
• Lines 15-21: page defers tool approval callbacks to broader Agent SDK docs
• Lines 139-157: page documents --allowedTools, but not AskUserQuestion handling
• URL: https://code.claude.com/docs/en/tools-reference
• Line 16: AskUserQuestion is listed as a tool
• Lines 120-125: page includes only a generic hooks cross-reference
• URL: https://platform.claude.com/docs/en/agent-sdk/user-input
• Lines 471-505: example returns updatedInput with both questions and answers
• Lines 585-603: response format defines the same structure

---

Conclusion & Recommendation

Primary Concern: The issue reported missing Claude Code documentation for answering AskUserQuestion through PreToolUse, especially in headless claude -p workflows.

Resolution Status: PARTIALLY RESOLVED

Recommendation: KEEP OPEN

The core hooks-reference gap is now fixed: AskUserQuestion matching and the required questions plus answers payload are documented on the hooks page. The headless page and tools reference still do not surface this flow directly, so the overall issue remains partially resolved.

---

Issue Summary

Issue #39620 reports that the hooks reference documentation is missing information about how AskUserQuestion interacts with PreToolUse hooks, specifically: (A) AskUserQuestion is not listed as a tool that reaches PreToolUse, (B) the answer payload shape is undocumented, and (C) the headless non-interactive clarifying-question flow is not explained.

Verification Results

Claim 1: AskUserQuestion not listed as a PreToolUse tool match

| Item | Detail |
|------|--------|
| Status | RESOLVED |
| Evidence | hooks.md:960 now reads: "Matches on tool name: Bash, Edit, Write, Read, Glob, Grep, Agent, WebFetch, WebSearch, AskUserQuestion, ExitPlanMode, and any MCP tool names." |
| Verdict | AskUserQuestion is explicitly listed in the PreToolUse tool name matches. |

Claim 2: Required answer payload is undocumented

| Item | Detail |
|------|--------|
| Status | RESOLVED |
| Evidence | hooks.md:1061-1068 adds a dedicated AskUserQuestion subsection under PreToolUse input documenting both questions (array) and answers (object mapping question text to selected label). Additionally, hooks.md:1099 states: "For AskUserQuestion, echo back the original questions array and add an answers object mapping each question's text to the chosen answer." |
| Verdict | The answer payload shape and usage instructions are fully documented. |

Claim 3: Headless non-interactive clarifying-question flow undocumented

| Item | Detail |
|------|--------|
| Status | RESOLVED |
| Evidence | hooks.md:1099 explains the permissionDecision: "allow" + updatedInput pattern for satisfying AskUserQuestion in non-interactive mode. hooks.md:1105-1119 adds a full "Defer a tool call for later" section with a 5-step round-trip walkthrough specific to AskUserQuestion in headless integrations, including the defer decision and --resume flow. |
| Verdict | The headless flow is comprehensively documented with both the direct-answer and defer-resume patterns. |

Current State

| Page | Status | Notes |
|------|--------|-------|
| Hooks reference | Updated | AskUserQuestion listed in tool matches, input fields documented, answer payload explained, defer flow added |
| Headless docs | Unchanged | No direct cross-reference to the hooks-based AskUserQuestion flow, but the canonical documentation on the hooks page covers it |
| Tools reference | Unchanged | AskUserQuestion listed as a tool but no cross-link to hooks-based handling |
| Agent SDK user input | Already documented | Was already aligned per the issue |

Suggested Fix

No fix needed. All three core claims from the issue have been addressed in the hooks reference page, which is the canonical location for this documentation. Optional improvement: headless.md and tools-reference.md could add cross-links to the hooks reference's AskUserQuestion section, but this is a minor enhancement rather than a documentation gap.

References

• Hooks reference (PreToolUse section): https://code.claude.com/docs/en/hooks#pretooluse
• Hooks reference (AskUserQuestion input): https://code.claude.com/docs/en/hooks#askuserquestion
• Hooks reference (decision control): https://code.claude.com/docs/en/hooks#pretooluse-decision-control
• Changelog v2.1.85 source entry: changelog.md:776

Conclusion & Recommendation

| Item | Detail |
|------|--------|
| Primary Concern | Missing documentation for AskUserQuestion + PreToolUse interaction and answer payload |
| Resolution Status | RESOLVED — All three claims addressed in the hooks reference |
| Recommendation | Close as completed. Optional: add cross-links from headless.md and tools-reference.md to the hooks reference AskUserQuestion section |

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.