[DOCS] Accept Edits docs contradict filesystem command auto-approval behavior

Adding some hands-on test results that confirm the behavior described here and highlight why the current acceptEdits semantics go beyond "file edits":

Test setup: Claude Code on macOS, ~/.agents/settings.json (custom dir with CLAUDE_CONFIG_DIR) with "defaultMode": "acceptEdits", no rm in the allow list, no deny rules.

Observed:

| Mode | rm <file> behavior |
| --- | --- |
| acceptEdits | Runs with no prompt, no visible approval UI |
| default | Prompts the user normally, can approve/deny per-call |
| deny: ["Bash(rm:*)"] | Hard block (no prompt, no override, command refused outright) |

This matches what the Agent SDK docs describe (rm, mv, cp, mkdir, touch auto-approved) but contradicts the main permission-modes doc that still says "still asks for commands".

Beyond the docs inconsistency, there's a design concern worth flagging:

acceptEdits is marketed and widely understood as "auto-approve file edits". Users reasonably expect this to mean the Edit/Write tools, not arbitrary destructive Bash verbs. In practice, a single model-generated rm -rf <path> under acceptEdits will execute silently with zero friction; the only thing that stopped it in my testing was an explicit deny entry. Prefix extensions from v2.1.97 (LANG=C rm foo, timeout 5 rm -rf foo) widen the surface further.

Suggestions:

1. Docs fix (this issue): make the main permission-modes page explicitly list the auto-approved filesystem commands and the prefix rules, so users aren't surprised.
2. Design fix (probably a separate issue): carve destructive verbs out of acceptEdits auto-approval, at minimum rm -rf, rm -r, and rm -f. These are not "edits" in any reasonable reading of the term, and requiring a deny rule as the sole guard is a footgun: deny is a hard block with no per-call override, so users who want a prompt-once experience have no middle ground.
3. Alternatively, introduce a finer-grained mode between default and acceptEdits that auto-approves Edit/Write only, leaving all Bash (filesystem or otherwise) on the normal prompt path.

Just checked the current docs again. This issue is not fully resolved yet.

Still relevant as of 2026-05-28. I checked the current docs and this documentation gap still appears unresolved.

Issue #45474 Verification

Title: [DOCS] Accept Edits docs contradict filesystem command auto-approval behavior
Issue Date: 2026-04-08
Verification Date: 2026-06-23
Status: RESOLVED

---

Issue Summary

This issue reports that the documentation for Claude Code's acceptEdits permission mode is inconsistent and outdated. Specifically, the reporter notes that the main docs still describe acceptEdits as "file edits only" or "still asks for commands," even though the changelog for v2.1.97 (April 8, 2026) introduced auto-approval for filesystem Bash commands (mkdir, touch, rm, mv, cp) and safe env-var/process wrapper prefixes (e.g. LANG=C rm foo, timeout 5 mkdir out). The reporter requested updates across permission-modes, permissions, desktop, how-claude-code-works, headless, desktop-quickstart, security, and the Agent SDK permissions cross-reference page.

---

Verification Results

Claim 1: permission-modes describes acceptEdits as "file edits only" or "still asks for commands"

Status: RESOLVED

The permission-modes page now describes the new behavior in detail. At https://code.claude.com/docs/en/permission-modes, lines 107-109:

acceptEdits mode lets Claude create and edit files in your working directory without prompting. The status bar shows ⏵⏵ accept edits on while this mode is active. In addition to file edits, acceptEdits mode auto-approves common filesystem Bash commands: mkdir, touch, rm, rmdir, mv, cp, and sed. These commands are also auto-approved when prefixed with safe environment variables such as LANG=C or NO_COLOR=1, or process wrappers such as timeout, nice, or nohup. Like file edits, auto-approval applies only to paths inside your working directory or additionalDirectories. Paths outside that scope, writes to [protected paths](#protected-paths), and all other Bash commands still prompt.

The mode summary table at line 18 also reflects this:

| [acceptEdits](#auto-approve-file-edits-with-acceptedits-mode) | Reads, file edits, and common filesystem commands (mkdir, touch, mv, cp, etc.) | Iterating on code you're reviewing |

Verdict: The page has been updated to document filesystem-command auto-approval and the env-var/wrapper prefix behavior.

---

Claim 2: permissions describes acceptEdits as auto-accepting file edit permissions only

Status: RESOLVED

At https://code.claude.com/docs/en/permissions, line 44:

| acceptEdits | Automatically accepts file edits and common filesystem commands (mkdir, touch, mv, cp, etc.) for paths in the working directory or additionalDirectories |

Verdict: The permissions table now matches the new behavior.

---

Claim 3: desktop says Auto accept edits still asks before running terminal commands

Status: RESOLVED

At https://code.claude.com/docs/en/desktop, line 72:

| Auto accept edits | acceptEdits | Claude auto-accepts file edits and common filesystem commands like mkdir, touch, and mv, but still asks before running other terminal commands. Use this when you trust file changes and want faster iteration. |

Verdict: Updated to clarify that the common filesystem commands are auto-approved while other terminal commands still prompt.

---

Claim 4: how-claude-code-works says Auto-accept edits "still asks for commands"

Status: RESOLVED

At https://code.claude.com/docs/en/how-claude-code-works, line 158:

* Auto-accept edits: Claude edits files and runs common filesystem commands like mkdir and mv without asking, still asks for other commands

Verdict: The wording now distinguishes common filesystem commands (auto-approved) from other commands (still prompts).

---

Claim 5: headless says shell commands still need --allowedTools or permissions.allow in acceptEdits mode

Status: RESOLVED

At https://code.claude.com/docs/en/headless, line 199:

acceptEdits lets Claude write files without prompting and also auto-approves common filesystem commands such as mkdir, touch, mv, and cp. Other shell commands and network requests still need an --allowedTools entry or a permissions.allow rule, otherwise the run aborts when one is attempted

Verdict: The headless guidance now correctly limits the --allowedTools requirement to "other shell commands" while calling out the filesystem commands that are auto-approved.

---

Claim 6: desktop-quickstart describes Auto accept edits as auto-accepting file edits only

Status: RESOLVED

At https://code.claude.com/docs/en/desktop-quickstart, line 106:

Adjust how much control you have. Your permission mode controls the balance. Ask permissions (default) requires approval before every edit. Auto accept edits auto-accepts file edits for faster iteration. Plan mode lets Claude map out an approach without touching any files, which is useful before a large refactor.

Verdict: This is a brief overview paragraph that no longer contradicts the new behavior. The detailed mode table on the linked desktop page (Claim 3) describes the filesystem-command auto-approval; the quickstart sentence is consistent and does not claim "file edits only."

---

Claim 7: security says Accept Edits keeps permission prompts for commands with side effects

Status: RESOLVED

At https://code.claude.com/docs/en/security, line 30:

* Accept Edits mode: Auto-approves file edits and a fixed set of filesystem Bash commands like mkdir, touch, rm, mv, cp, and sed for paths in the working directory. Other Bash commands and out-of-scope paths still prompt

Verdict: Updated to enumerate the auto-approved filesystem commands and clarify that other commands and out-of-scope paths still prompt.

---

Claim 8: The docs do not explain that safe env-var prefixes and safe process wrappers preserve filesystem-command auto-approval

Status: RESOLVED

At https://code.claude.com/docs/en/permission-modes, line 109:

These commands are also auto-approved when prefixed with safe environment variables such as LANG=C or NO_COLOR=1, or process wrappers such as timeout, nice, or nohup.

Verdict: The env-var and wrapper-prefix behavior is now documented with the changelog examples (LANG=C) and additional wrappers (NO_COLOR=1, timeout, nice, nohup).

---

Claim 9: The Agent SDK permissions cross-reference already documents filesystem-command auto-approval

Status: RESOLVED

At https://code.claude.com/docs/en/agent-sdk/permissions, line 92:

| acceptEdits | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (mkdir, rm, mv, etc.) are automatically approved |

Verdict: The Agent SDK page is consistent with the main docs.

---

Current State

| Claim | Status |
|-------|--------|
| permission-modes describes acceptEdits as "file edits only" or "still asks for commands" | RESOLVED |
| permissions describes acceptEdits as auto-accepting file edit permissions only | RESOLVED |
| desktop says Auto accept edits still asks before running terminal commands | RESOLVED |
| how-claude-code-works says Auto-accept edits "still asks for commands" | RESOLVED |
| headless says shell commands still need --allowedTools or permissions.allow in acceptEdits mode | RESOLVED |
| desktop-quickstart describes Auto accept edits as auto-accepting file edits only | RESOLVED |
| security says Accept Edits keeps permission prompts for commands with side effects | RESOLVED |
| Docs do not explain safe env-var prefixes and safe process wrappers | RESOLVED |
| Agent SDK permissions cross-reference already documents filesystem-command auto-approval | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved. The permission-modes page (lines 107-111) and the related user-facing pages now describe the v2.1.97 behavior consistently: file edits plus a defined set of filesystem Bash commands (mkdir, touch, rm, rmdir, mv, cp, sed) are auto-approved in acceptEdits mode, including safe env-var and process-wrapper prefixes. Other shell commands and out-of-scope paths still follow the normal permission flow.

---

References

• URL: https://code.claude.com/docs/en/permission-modes
• Lines 18, 107-111: Mode table and detailed acceptEdits description including the auto-approved filesystem commands and env-var/wrapper prefixes
• URL: https://code.claude.com/docs/en/permissions
• Line 44: Permission mode table updated to include filesystem commands
• URL: https://code.claude.com/docs/en/desktop
• Line 72: Desktop mode table updated
• URL: https://code.claude.com/docs/en/how-claude-code-works
• Line 158: Shift+Tab cycle description updated
• URL: https://code.claude.com/docs/en/headless
• Line 199: Headless guidance now calls out the auto-approved filesystem commands
• URL: https://code.claude.com/docs/en/desktop-quickstart
• Line 106: Quickstart paragraph is consistent with the updated behavior
• URL: https://code.claude.com/docs/en/security
• Line 30: Security overview lists the auto-approved filesystem commands
• URL: https://code.claude.com/docs/en/agent-sdk/permissions
• Line 92: Agent SDK mode table aligned with the main docs
• URL: https://code.claude.com/docs/en/changelog
• Lines 1711-1714: v2.1.97 changelog entry "Improved Accept Edits mode to auto-approve filesystem commands prefixed with safe env vars or process wrappers"

---

Conclusion & Recommendation

Primary Concern: The Claude Code docs described acceptEdits as auto-approving only file edits, which contradicted the v2.1.97 behavior of also auto-approving a defined set of filesystem Bash commands (including safe env-var and process-wrapper prefixes).

Resolution Status: RESOLVED

Recommendation: CLOSE

All eight pages called out in the issue have been updated to describe the filesystem-command auto-approval and (on permission-modes) the env-var/wrapper prefixes from the v2.1.97 changelog, with consistent wording across user-facing and Agent SDK pages.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.