[DOCS] AskUserQuestion tool lacks documentation in Claude Code docs; conflicts with Agent SDK docs

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude - https://docs.anthropic.com/en/docs/claude-code/common-workflows#use-plan-mode-for-safe-code-analysis - https://docs.anthropic.com/en/docs/claude-code/best-practices#let-claude-interview-you - https://docs.anthropic.com/en/docs/claude-code/sub-agents#run-subagents-in-foreground-or-background

Section/Topic

The AskUserQuestion tool documentation across Claude Code docs, and its relationship to the more comprehensive Agent SDK documentation.

Current Documentation

In settings.md (Tools table):
| Tool | Description | Permission Required |
| :--- | :---------- | :------------------ |
| AskUserQuestion | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

In common-workflows.md:

In Plan Mode, Claude uses AskUserQuestion to gather requirements and clarify your goals before proposing a plan.

In best-practices.md:

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

In sub-agents.md:

If a background subagent needs a permission it doesn't have or needs to ask clarifying questions, that tool call fails but the subagent continues.

In Agent SDK user-input.md (Limitations section):

AskUserQuestion is not currently available in subagents spawned via the Task tool

What's Wrong or Missing?

A. Insufficient tool documentation in Claude Code docs

The Claude Code documentation provides only a one-line description in a table. Users have no way to learn:

• Parameter constraints: 1-4 questions per call, 2-4 options per question
• Field details: question, header (max 12 chars), options, multiSelect
• User interaction: Users can always type free-text "Other" responses
• Timeout behavior: 60-second timeout mentioned only in Agent SDK docs

B. Conflicting information about subagent availability

The Claude Code docs (sub-agents.md) imply AskUserQuestion works in foreground subagents but may fail in background subagents. The Agent SDK docs (user-input.md) state it's "not currently available in subagents spawned via the Task tool" at all. These statements conflict.

C. No cross-references between doc sets

The Agent SDK has comprehensive AskUserQuestion documentation in the "Handle approvals and user input" page. The Claude Code docs never reference this, leaving CLI users unaware detailed documentation exists.

D. Unhelpful link target

The link in common-workflows.md points to #tools-available-to-claude, which is just a table with a one-line description. Users clicking to learn about the tool find no useful detail.

Suggested Improvement

Option A: Add dedicated section to Claude Code docs

Add an ### AskUserQuestion subsection under "Tools available to Claude" in settings.md:

### AskUserQuestion

Claude uses this tool to ask multiple-choice questions when it needs user input to proceed. Common use cases include gathering requirements in Plan Mode and clarifying ambiguous instructions.

**Question format:**
- 1-4 questions per tool call
- 2-4 options per question
- Each question has a `header` (max 12 characters) and full `question` text
- `multiSelect: true` allows selecting multiple options

**Responding to questions:**
- Select from the predefined options, or
- Type a custom response (always available as "Other")

**Limitations:**
- 60-second timeout for responses
- Not available in subagents (foreground or background)

For detailed SDK integration, see [Handle approvals and user input](https://platform.claude.com/docs/en/agent-sdk/user-input#handle-clarifying-questions).

Option B: Minimum fix

At minimum, add a cross-reference note to the tools table:

For detailed information on AskUserQuestion including question format and SDK integration, see the Agent SDK user input documentation.

Option C: Resolve the subagent conflict

Clarify in both doc sets whether AskUserQuestion:

• Works in foreground subagents only
• Fails gracefully vs. is completely unavailable
• Has different behavior in CLI vs. SDK contexts

Impact

High - Prevents users from using a feature

Additional Context

Mirror locations:

• code-claude/docs/en/settings.md
• code-claude/docs/en/common-workflows.md
• code-claude/docs/en/best-practices.md
• code-claude/docs/en/sub-agents.md
• platform-claude/docs/en/agent-sdk/user-input.md
• platform-claude/docs/en/agent-sdk/permissions.md

Related documentation:

• Agent SDK user input docs (comprehensive): https://platform.claude.com/docs/en/agent-sdk/user-input
• Agent SDK permissions docs: https://platform.claude.com/docs/en/agent-sdk/permissions

Impact:
Users who only read Claude Code CLI docs (the majority of CLI users) have no way to understand how AskUserQuestion works, what constraints it has, or how to effectively use prompts that trigger it. The conflicting subagent information may cause confusion when building workflows that depend on this tool.