Restricting an agent's tools feels like a safety win — fewer capabilities, fewer surprises. But one of the tools people routinely forget to list is the one that lets Claude stop and ask you something.
Why AskUserQuestion Vanishes When You Restrict an Agent's Tools
If you pass an explicit tools or allowedTools array and omit AskUserQuestion, Claude silently loses the ability to ask you anything — no error, no warning, no log line. The Agent SDK documentation states it plainly: when you restrict Claude with an explicit tools array, you must list AskUserQuestion yourself or the agent loses the capability . What you observe instead is an agent that guesses and moves on.
Quick Answer: Omitting AskUserQuestion from an explicit tools array silently disables Claude's ability to ask clarifying questions. Anthropic reports users approve 93% of permission prompts , so losing the other input seam matters more than it looks.
AskUserQuestion is a first-class built-in, not an implicit fallback. Each call supports 1–4 questions with 2–4 options each, a header capped at 12 characters, and an optional multiSelect flag; answers return keyed by question text and valued by the selected label .
That matters because the SDK describes exactly two situations where user input reaches Claude: tool permission approval (deleting files, running commands) and clarifying questions via AskUserQuestion . Dropping it from the array cuts one of the two seams — and the remaining one only fires on tool calls the harness already flags.
Adding it back does not fix every surface. AskUserQuestion is not currently available in subagents spawned via the Agent tool, regardless of what the array contains . The topic came up in a walkthrough of a widely-shared skill that told the agent to skip confirmation entirely — a reminder that improving execution and disabling the safety gate are two different edits.
Before You Restrict Tools: What to Check in Your Config
Before you edit a tools array, find where the restriction is actually declared — the same behavior has three separate homes, and fixing the wrong one leaves the agent mute. Restriction lives in SDK options.tools/options.allowedTools, in a plugin- or enterprise-managed skill config, or in the harness via permissionMode. Anthropic's permissions doc specifies a six-step evaluation order: hooks → deny rules → ask rules → permission mode → allow rules → canUseTool . Permission mode is evaluated before allow rules, so dontAsk short-circuits — listing AskUserQuestion and adding a matching allow rule changes nothing, because the mode denies the interaction call outright (source: Agent SDK permissions).
Check these three surfaces in order, then confirm your version floor.
| Surface | Where it lives | Effect on AskUserQuestion |
|---|---|---|
| Tool allowlist | options.tools / options.allowedTools | Omitted → capability silently absent |
| Permission mode | permissionMode: "dontAsk" | Denied even when listed and allowed |
| Skill body | SKILL.md text | Instruction only, not a runtime boundary |
One version gate: MCP tools flagged _meta["anthropic/requiresUserInteraction"] only fall through to the user callback on Claude Code v2.1.199 and later . If you depend on that flag, confirm the running version before assuming the prompt will appear.
Putting AskUserQuestion Back: Four Steps
Restoring the ability to ask takes four concrete edits, and the first one is naming the tool explicitly. Because an explicit tools array is opt-out by default, AskUserQuestion disappears unless you list it yourself . Add it back by name, then work down the remaining three checks.
- List the tool. Open the
toolsorallowedToolsarray in your SDK call, skill config, or headless launcher and add the literal stringAskUserQuestionalongside your other entries. - Fix the permission mode. If
permissionModeisdontAsk, the call is denied even when the tool is listed and allowed . Switch todefault,plan, oracceptEditson any path where clarification should be possible, and reservedontAskfor a narrow headless run paired with an explicitallowedToolslist. - Optional: render previews. TypeScript callers can set
toolConfig.askUserQuestion.previewFormatto"markdown"or"html"so each option carries a renderedpreview. - Test with unbounded scope. Send a prompt that names no file, directory, or list — "migrate my codebase" is the canonical trigger in Anthropic's own claude-api skill, which instructs the agent to ask which scope to apply and "do not start editing until the user confirms" . A structured card with 2–4 options should appear instead of a silently assumed default.
Confirm the shape of what comes back, too: answers arrive keyed by question text and valued by the selected label, with a freeform response field if the user dismisses the card entirely . Handle the dismissal branch, or a skipped question reads as no answer at all.
Where the Fix Falls Short: dontAsk Mode and Subagents
Listing AskUserQuestion in the tools array is necessary but not sufficient — the permission mode can still deny the call after the array permits it. Anthropic's permissions doc specifies a six-step evaluation order: hooks → deny rules → ask rules → permission mode → allow rules → canUseTool . Normally AskUserQuestion falls through to the user callback even when an allow rule matches and even under bypassPermissions. Under permissionMode: "dontAsk", those same calls are denied instead, because the mode never prompts [2]. Your step-3 fix does nothing until the mode changes too.
Three more boundaries worth checking before you assume the agent can ask:
- Subagents.
AskUserQuestionis not currently available in subagents spawned via the Agent tool, regardless of how the parent's array is configured [1]. - Hooks.
AskUserQuestionandExitPlanModeare interaction tools; a hook can only satisfy them by returning updated input containing the actual answers. Allowing the call through leaves it unresolved [13]. - Version drift. v2.1.212 routes plan-mode shell writes such as
touchandrmback through the callback, and v2.1.198 added aCLAUDE_SDK_CAN_USE_TOOL_SHADOWEDwarning when acanUseToolcallback can never be reached . A version bump quietly shifts which calls need a callback at all.
Checking Your Other Skills for the Same Miss
Audit the rest of your setup in one pass. Grep every SKILL.md and subagent definition you maintain for a tools or allowedTools array, then confirm AskUserQuestion is listed wherever clarification should still be reachable:
grep -rn "allowedTools\|\"tools\"" ~/.claude/skills .claude/skills .claude/agentsWhere it is absent, decide deliberately rather than by omission. Anthropic's own claude-api skill splits the rule in two: don't ask when the user names an exact file, directory, or list — treat it as definitive — but ask which scope applies, and "do not start editing until the user confirms," when a request like "migrate my codebase" arrives unbounded . The community solid-gemc skill draws the line harder: clarifying questions are waivable on request, but the final Approve / Edit / Plan-only gate is not, even when the user says "just run it" — because init may pull a roughly 1.7 GB JLabCE .sif and run two scons builds .
Re-audit after every SDK bump. The six-step permission evaluation order and the exact denial scope of dontAsk both shifted across 2026 point releases — v2.1.199 added MCP requiresUserInteraction handling, v2.1.207 changed allow results omitting updatedInput, v2.1.212 rerouted plan-mode shell writes . The takeaway: autonomy over interpretation, never over consequences — and keep that boundary in a permission rule or hook, not only in a sentence of Markdown.
Frequently asked questions
What actually happens if I restrict tools without including AskUserQuestion?
Nothing visible — no error, no warning, no log line. Claude Code simply proceeds as if the tool does not exist, and the agent that would have paused for a structured multiple-choice card instead fills the ambiguous scope with default assumptions. Anthropic's Agent SDK documentation states plainly that if you restrict Claude with an explicit tools array, you must list AskUserQuestion yourself or the agent silently loses the ability to ask . In well-written skills the fallback is disclosure — the freeCodeCamp commit-message-writer example instructs the agent to make assumptions and note them after the output rather than suppress them . In a badly written one, the assumption is never surfaced at all.
Does permissionMode: dontAsk also block AskUserQuestion?
Yes. Under dontAsk, AskUserQuestion calls are denied outright rather than routed to the user, so adding the tool back to the array does not restore asking in that mode. Anthropic's permissions doc describes a six-step evaluation order — hooks → deny rules → ask rules → permission mode → allow rules → canUseTool — and notes that AskUserQuestion, MCP tools flagged _meta["anthropic/requiresUserInteraction"] (Claude Code v2.1.199+), and org-set ask connector tools normally fall through to the user callback even when an allow rule matches and even under bypassPermissions . dontAsk is the one mode that inverts this: it never prompts, so the request to ask is itself refused. Anthropic recommends pairing it with an explicit allowedTools list for locked-down headless agents.
Can subagents spawned via the Agent tool use AskUserQuestion at all?
No. AskUserQuestion is not currently available in subagents spawned through the Agent tool, regardless of what the parent's tools array or permission configuration specifies . This is a structural limit, not a config mistake — a subagent that hits ambiguous scope has no path back to the user and must either guess or fail. Design accordingly: resolve scope in the parent turn (where the card can render) before fanning work out, or have the subagent return an explicit "underspecified" result for the parent to escalate. Hooks documentation makes the same seam visible from the other side: AskUserQuestion and ExitPlanMode are interaction tools that an automation hook can only satisfy by returning updated input containing answers, not by merely allowing the call .
What's the standard exception pattern for "don't ask clarifying questions" skill rules?
Proceed without asking only when the user names an exact file, a specific directory, or an explicit file list — definitive scope. Ask when the scope is unbounded or the action is irreversible. Anthropic's public claude-api skill encodes exactly this split: when a user names a file, directory, or provider, "treat it as definitive — don't ask for confirmation," but when a user says "migrate my codebase" or "upgrade to Sonnet 4.6" with no named target, the skill must ask which scope to apply and "do not start editing until the user confirms" . The community solid-gemc skill goes further, keeping its approval gate non-waivable even when the user says "go," "yes," or "skip the approval," because setup can pull an approximately 1.7 GB container image and run two builds . The shorthand: autonomy over interpretation, not autonomy over consequences.
How do I verify the fix actually restored asking?
Send a deliberately underspecified prompt — one with no named file, directory, or scope, such as "migrate my codebase" — and confirm a structured multiple-choice card appears instead of a silently-assumed default. A real AskUserQuestion call renders 1–4 questions with 2–4 options each, each question carrying a header capped at 12 characters and an options array of label/description pairs . If you see prose that begins with an assumption instead, the tool is still missing or the mode is still dontAsk. Test per model, too: PwC's clarification study measured GPT-5.2 asking on 52% of tasks versus Claude at 23% and Gemini never , so a passing test on one model says little about another.
Does the timing of the question matter, or just whether it gets asked?
Timing carries most of the value. PwC's "Ask Early, Ask Late, Ask Right" (arXiv:2605.07937, May 8 2026) found that goal clarification injected at 10% of the trajectory recovers near-oracle performance — pass@3 of 0.78 against an oracle 0.80 — but is effectively worthless by 70%, while input clarification retains value to roughly the 50% mark . Ambig-DS reports the same shape from the cost side: ambiguity costs −0.10 to −0.29 normalized score on target-ambiguity tasks, and one permitted clarification recovers +0.20 . Practical reading: restore AskUserQuestion at the top of the run, not as a late escape hatch after the agent has already committed to an interpretation.
Watch / Sources
Last updated: 2026-08-07. Behavior verified against Anthropic's Agent SDK user-input and permissions documentation; permission-evaluation details reflect Claude Code v2.1.199–v2.1.212 release notes and may change in later point releases.
Enjoyed this article? Subscribe to get new stories by email whenever they're published.