[DOCS] Auto mode docs missing stalled permission-check spinner state

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Eliminate prompts with auto mode" / "When auto mode falls back" / "Cost and latency"

Current Documentation

The Auto mode documentation explains that classifier checks happen before some actions and can add latency:

"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."

It also documents denied actions and fallback thresholds:

"Each denied action shows a notification and appears in /permissions under the Recently denied tab, where you can press r to retry it with a manual approval." "If the classifier blocks an action 3 times in a row or 20 times total, auto mode pauses and Claude Code resumes prompting. Approving the prompted action resumes auto mode."

The latency accordion says:

"Each check sends a portion of the transcript plus the pending action, adding a round-trip before execution. Reads and working-directory edits outside protected paths skip the classifier, so the overhead comes mainly from shell commands and network operations."

What's Wrong or Missing?

Claude Code v2.1.126 added a distinct Auto mode UI signal: when a permission check stalls, the spinner turns red instead of continuing to look like the tool itself is running.

The docs explain normal classifier latency, denials, and fallback behavior, but they do not explain this stalled permission-check state or how users should interpret it. A user seeing the red spinner has no documentation-backed way to distinguish:

• a tool that is still actively running,
• a classifier/permission check that is stalled before the tool runs, or
• a denied/fallback state that should appear in /permissions.

This is especially relevant because the documented "Cost and latency" section already tells users that classifier checks add a round-trip before execution, but does not mention the visible stalled-check indicator added in v2.1.126.

Suggested Improvement

Add a short note near "When auto mode falls back" or in the "Cost and latency" accordion explaining the stalled-check spinner state. For example:

If an Auto mode permission check stalls before a tool starts, Claude Code changes the spinner to red to indicate that the permission check is waiting or not responding. This means the tool may not have started yet, even if the UI is still showing activity. If the action is denied, it appears in /permissions under Recently denied; repeated denials can cause Auto mode to fall back to manual prompts.

If there is a recommended user action when the red stalled-check spinner persists, include that as well, such as waiting, checking /permissions, retrying the action, or reporting feedback.

Impact

Low - Minor confusion or inconvenience

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/permission-modes | 145, 191-199, 230-231 | Primary Auto mode behavior, denial/fallback, and classifier latency documentation |
| https://code.claude.com/docs/en/auto-mode-config | 165-171 | Auto mode denial review flow documents denied actions, but not stalled permission-check UI |

Version context: v2.1.126 release entry says: "Auto mode: the spinner now turns red when a permission check stalls, instead of looking like the tool is running."

Total scope: 2 pages affected