claude-code - 💡(How to fix) Fix [DOCS] Auto mode docs omit the explicit `AskUserQuestion` exception

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/permission-modes

Section/Topic

The "Eliminate prompts with auto mode" section, especially the guidance about clarifying questions.

Current Documentation

The docs currently say:

Auto mode also nudges Claude to keep working without stopping for clarifying questions. For stronger autonomous behavior while keeping permission prompts, set the Proactive output style instead.

Related guidance elsewhere still recommends explicit AskUserQuestion workflows:

For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the AskUserQuestion tool.

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

What's Wrong or Missing?

In v2.1.146, the release entry says auto mode no longer suppresses AskUserQuestion when the user or a skill explicitly relies on it.

The current Claude Code docs still read as if auto mode broadly pushes Claude away from clarifying questions, but they do not document the exception for explicit AskUserQuestion workflows. That leaves the docs out of sync with current behavior and creates conflicting guidance:

A. The permission-modes page reads like a blanket rule

The current wording implies that auto mode suppresses clarifying questions in general, without saying that explicitly requested AskUserQuestion flows still work.

B. Prompt-writing guidance has no mode-specific caveat

The best-practices page recommends asking Claude to interview the user with AskUserQuestion, but it does not explain how that interacts with auto mode.

C. Reusable workflows remain ambiguous

Because the exception is undocumented, users cannot tell whether an invoked skill or other explicit workflow that depends on AskUserQuestion is expected to work in auto mode or be suppressed.

Suggested Improvement

Update the auto mode docs to document the explicit AskUserQuestion exception introduced in v2.1.146.

Suggested wording for the permission-modes page:

Before:

Auto mode also nudges Claude to keep working without stopping for clarifying questions.

After:

Auto mode generally nudges Claude to keep working without stopping for clarifying questions, but it does not suppress AskUserQuestion when you explicitly ask Claude to use that workflow or when an active skill depends on it.

Also add a short cross-reference from the interview-style prompt guidance so users know that explicitly requested AskUserQuestion flows still work in auto mode.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

The current docs explain the general auto-mode preference for fewer interruptions, but they do not explain the v2.1.146 exception for explicit AskUserQuestion workflows.