[DOCS] Missing warning and workflow guidance for `AskUserQuestion` limitation in Subagents

Documentation Type

Unclear/confusing documentation

Documentation Location

• platform.claude.com/docs/en/agent-sdk/subagents - platform.claude.com/docs/en/agent-sdk/user-input

Section/Topic

• The "Limitations" section in user-input.md - The "Common patterns" or "Enforce constraints" section in subagents.md

Current Documentation

In the Handle approvals and user input section (user-input.md), under Limitations:

"Subagents: AskUserQuestion is not currently available in subagents spawned via the Task tool."

However, in the Subagents in the SDK section (subagents.md), subagents are described as:

"handle complex, multi-step tasks... separate agent instances that your main agent can spawn... Excellent for research assistants that explore dozens of files."

What's Wrong or Missing?

The documentation for Subagents paints them as highly capable autonomous units for complex tasks. However, it fails to provide a prominent warning that these units are strictly non-interactive.

If a developer builds a subagent for a "complex task" (e.g., a database migration assistant) and that subagent encounters ambiguity, it cannot use AskUserQuestion. Based on current docs, the agent will either:

1. Fail the tool call.
2. Attempt to "guess" (hallucinate) a parameter to avoid failing.
3. Hang/timeout if it keeps trying to find an answer it doesn't have.

The documentation is missing a "Best Practice" or "Workflow Pattern" for how a subagent should "escalate" a question back to the main agent so the main agent can then prompt the user.

Suggested Improvement

Add a "Interaction & Autonomy" section to subagents.md with the following suggested text:

### Interaction Limitation Important: Subagents are strictly autonomous. The AskUserQuestion tool is currently unavailable within a subagent context. If a subagent encounters a decision point requiring human input, it cannot prompt the user directly. Recommended Pattern: Escalation To handle ambiguity, instruct your subagent to return a structured result indicating that clarification is needed. The main agent can then use AskUserQuestion to resolve the issue. Example Prompting: "If you encounter multiple valid configuration paths and cannot proceed autonomously, stop and return a summary of the options to the main agent for user clarification."

Impact

High - Prevents users from using a feature

Additional Context

• Evidence: The AgentInput (Task tool) description in the Python/TypeScript references implies that subagents are the go-to for "complex" work, but "complex" work almost always requires a human-in-the-loop for edge cases.
• Related Documentation: This creates a conflict with the AskUserQuestion guide which describes the tool as the primary way to "gather requirements or clarify ambiguity." Developers need to know that this bridge is broken when using the Task tool.
• Example from other projects: Software like LangChain or AutoGPT explicitly handles "delegation with feedback" where a child agent can "bubble up" a request for info to the parent. Claude Code docs should define this specific "escalation" protocol since the tool itself is disabled.