[DOCS] Auto mode docs do not describe the v2.1.205 prompt fallback for `rm -rf` whose target variable cannot be resolved from the conversation

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/permission-modes#when-auto-mode-falls-back

Section/Topic

The "Eliminate permission prompts with auto mode" section of permission-modes.md, specifically the "When auto mode falls back" subsection and the "What the classifier blocks by default" list above it. The matching classifier-evaluation discussion on https://code.claude.com/docs/en/auto-mode-config should also be checked so the new prompt path is described once and cross-referenced from both pages.

Current Documentation

From permission-modes.md, the "When auto mode falls back" subsection currently reads:

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. These thresholds are not configurable. Any allowed action resets the consecutive counter, while the total counter persists for the session and resets only when its own limit triggers a fallback. In non-interactive mode with the -p flag, repeated blocks abort the session since there is no user to prompt. Repeated blocks usually mean the classifier is missing context about your infrastructure. Use /feedback to report false positives, or have an administrator configure trusted infrastructure.

The "What the classifier blocks by default" list above that subsection (around the existing destructive-default entries) currently includes:

Irreversibly destroying files that existed before the session Deleting files in /tmp, $TMPDIR, or another shared scratch or cache directory by wildcard, glob, or age filter rather than by a specific named path * git reset --hard, git checkout -- ., git restore ., git clean -fd, git stash drop, or git stash clear, which the classifier presumes would discard uncommitted changes

The same page's bypassPermissions section (around the "circuit breaker" sentence for filesystem-root removals) is the only place where rm -rf is named:

Explicit ask rules still force a prompt in this mode, and removals targeting the filesystem root or home directory, such as rm -rf / and rm -rf ~, still prompt as a circuit breaker against model error.

The https://code.claude.com/docs/en/permissions page repeats that circuit breaker in the bypassPermissions table row:

bypassPermissions | Skips permission prompts, except those forced by explicit ask rules. Root and home directory removals such as rm -rf / also still prompt as a circuit breaker

auto-mode-config.md (https://code.claude.com/docs/en/auto-mode-config) walks through what autoMode settings do but never names the unresolved-variable prompt behavior.

What's Wrong or Missing?

The v2.1.205 changelog says:

Improved auto mode to ask before running rm -rf on a variable it can't resolve from context

Nothing in the auto mode documentation (the "Eliminate permission prompts with auto mode" section starting on https://code.claude.com/docs/en/permission-modes or the related auto-mode-config.md page) describes that new prompt path. Before v2.1.205 the auto-mode docs described only two transitions from auto mode back to a permission prompt: the Recently-denied-tab retry, and the 3-in-a-row / 20-total classifier threshold. After v2.1.205 there is a third one — an immediate prompt when the classifier sees rm -rf whose argument is a variable that cannot be resolved from the conversation or settings. Without a corresponding documentation entry, a user who hits the new prompt cannot tell from code.claude.com what triggered it, what the new rule is, or that it is part of auto mode rather than bypassPermissions.

A. The "When auto mode falls back" subsection enumerates only two prompt paths

The subsection describes the Recently-denied retry and the count-threshold fallback, then jumps to the repetition-cause guidance. It does not mention that auto mode also prompts when Bash contains rm -rf against an argument that the classifier cannot resolve from the transcript. A reader using the subsection to understand when auto mode will reach a permission prompt will assume the only triggers are denial patterns; the unresolved-variable path is invisible.

B. The destructive-default list does not surface the new behavior

"What the classifier blocks by default" calls out the case-by-case behaviors for destructive operations (force pushes, git reset --hard, mass deletion by wildcard/glob, IaC destroy, mass rm -rf /). The v2.1.205 case — rm -rf against an unresolvable variable — does not appear. Users reading the list to decide what auto mode rejects or prompts on, and users debugging an unexpected permission prompt, both have no place to look up the rule.

C. The auto-mode-config reference does not mention the path

auto-mode-config.md is the page where users learn how autoMode settings interact with the classifier's evaluation order (allow/deny rules, environment entries, defaults). The new prompt path sits in the same evaluation order, so users configuring autoMode.allow rules to whitelist Bash commands of their own will not realize the unresolved-variable path lives next to those rules and may override them.

D. The bypassPermissions circuit-breaker sentence is the only rm -rf reference, but it covers a different case

The existing bypassPermissions documentation cites rm -rf / and rm -rf ~ as filesystem-root circuit breakers. The v2.1.205 entry is unrelated to filesystem-root removals — it concerns variables and parameter expansions inside an otherwise-plausible rm -rf. Cross-linking from the bypass-permissions prose to the new auto-mode prompt (or vice versa) would help a reader comparing the two modes realize they are different safety nets for different problems.

Suggested Improvement

Add a note in the "When auto mode falls back" subsection and an entry in the "What the classifier blocks by default" list that describe the v2.1.205 prompt fallback for unresolvable rm -rf variables. Cross-reference the change from auto-mode-config.md so users configuring autoMode rules can see the evaluation step.

Before (end of the "When auto mode falls back" paragraph at permission-modes.md):

Repeated blocks usually mean the classifier is missing context about your infrastructure. Use /feedback to report false positives, or have an administrator configure trusted infrastructure.

After:

Repeated blocks usually mean the classifier is missing context about your infrastructure. Use /feedback to report false positives, or have an administrator configure trusted infrastructure. {/ min-version: 2.1.205 /}As of v2.1.205, auto mode also prompts on its own when Bash contains an rm -rf whose argument is a variable, parameter expansion, or command substitution that cannot be resolved from the transcript or settings — for example rm -rf "$unresolved_var" or rm -rf ${UNSET} — instead of letting the classifier infer intent on those commands. Approving the prompt lets the command run; denying returns control to Claude with the rejection reason, the same as a manual classifier denial. The unrelated rm -rf / and rm -rf ~ safety net for [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) still applies only there, not to auto mode.

Add a new bullet to the "What the classifier blocks by default" list, sitting next to the existing "Irreversibly destroying files that existed before the session" line:

{/ min-version: 2.1.205 */}Bash commands of the form rm -rf whose target argument is a shell variable, parameter expansion, or command substitution that the classifier cannot resolve from the conversation or settings — for example rm -rf "$unresolved_var", rm -rf ${UNSET}, or rm -rf "$(cat /path/that/does/not/exist)". Instead of running the classifier on the inferred intent, auto mode prompts the user for approval. Earlier versions let the classifier decide based on context alone.

Add a short note to the introduction paragraph of auto-mode-config.md (https://code.claude.com/docs/en/auto-mode-config) immediately after the sentence that already links out to the permission-modes reference:

{/ min-version: 2.1.205 /}Auto mode also falls back to a permission prompt for rm -rf whose variable argument cannot be resolved from the transcript — see When auto mode falls back.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permission-modes | "Eliminate permission prompts with auto mode" section: "When auto mode falls back" subsection and the "What the classifier blocks by default" list |
| https://code.claude.com/docs/en/auto-mode-config | The classifier-evaluation / autoMode-settings discussion that explains where this prompt sits in the ordering |

Total scope: 2 pages affected

The v2.1.205 changelog entry that motivates this issue reads:

Improved auto mode to ask before running rm -rf on a variable it can't resolve from context

The change is auto-mode specific and only affects how the classifier handles Bash commands whose rm -rf argument cannot be statically resolved. The existing bypassPermissions circuit breaker for rm -rf / and rm -rf ~ (already documented on https://code.claude.com/docs/en/permission-modes#skip-all-checks-with-bypasspermissions-mode and the permissionMode row at https://code.claude.com/docs/en/permissions) addresses a different case — filesystem-root removals — and should remain distinct from the new auto-mode prompt path. Both pages should mention each other so a reader comparing the two modes can see that the new prompt is auto-mode only.