claude-code - 💡(How to fix) Fix [DOCS] Auto mode docs omit that `permissions.ask` rules still trigger manual approval prompts [1 comments, 2 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Eliminate prompts with auto mode and How the classifier evaluates actions

Current Documentation

The auto mode page currently says:

Auto mode lets Claude execute without permission prompts. A separate classifier model reviews actions before they run, blocking anything that escalates beyond your request, targets unrecognized infrastructure, or appears driven by hostile content Claude read.

Later, the same page describes the decision order as:

1. Actions matching your allow or deny rules resolve immediately
2. Read-only actions and file edits in your working directory are auto-approved, except writes to protected paths
3. Everything else goes to the classifier
4. If the classifier blocks, Claude receives the reason and tries an alternative

What's Wrong or Missing?

This page does not explain that explicit permissions.ask rules can still interrupt auto mode and open a manual approval dialog.

Because the page says auto mode runs "without permission prompts" and the decision order only names allow and deny rules, readers can easily conclude that any prompt in auto mode must be a classifier fallback. That is incomplete for current behavior: the permissions docs define ask rules as prompting for confirmation, and they evaluate in deny -> ask -> allow order.

As a result, users who add or inherit a permissions.ask rule do not get a clear docs explanation for why auto mode is still prompting.

Suggested Improvement

Update the auto mode docs to state explicitly that permissions.ask rules still produce a manual approval prompt in auto mode.

Two small changes would make this clear:

1. In Eliminate prompts with auto mode, add a note that auto mode removes classifier-driven prompts, but explicit permissions.ask rules still prompt.
2. In How the classifier evaluates actions, change "allow or deny rules" to "allow, ask, or deny rules" or add a sentence immediately below the list explaining that a matching ask rule surfaces the permission dialog instead of sending the action to the classifier.

This is especially relevant after v2.1.141, where the permission dialog now explains when a permissions.ask rule caused the prompt.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 1 page affected

Related docs: