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

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

acceptEdits mode behavior, especially which filesystem Bash commands are auto-approved and how safe env-var or wrapper-prefixed forms are handled

Current Documentation

The permission modes page currently says:

acceptEdits mode lets Claude create and edit files in your working directory without prompting. Writes to protected paths and all non-edit actions still prompt the same as default mode.

Related user-facing pages repeat the same behavior model:

Claude auto-accepts file edits but still asks before running terminal commands.

* Auto-accept edits: Claude edits files without asking, still asks for commands

acceptEdits lets Claude write files without prompting, but shell commands and network requests still need an --allowedTools entry or a permissions.allow rule, otherwise the run aborts when one is attempted:

At the same time, the Agent SDK permissions page already documents broader behavior:

Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren't filesystem operations) still require normal permissions.

Auto-approved operations: File edits (Edit, Write tools) Filesystem commands: mkdir, touch, rm, mv, cp

What's Wrong or Missing?

Changelog v2.1.97 adds another user-visible detail:

Improved Accept Edits mode to auto-approve filesystem commands prefixed with safe env vars or process wrappers (e.g. LANG=C rm foo, timeout 5 mkdir out)

The current docs are inconsistent and outdated:

A. Main Claude Code docs still describe acceptEdits as “file edits only” or “still asks for commands”

That is no longer accurate if filesystem Bash commands such as mkdir, touch, rm, mv, and cp are auto-approved in acceptEdits mode.

B. The docs do not explain that safe env-var prefixes and safe process wrappers preserve filesystem-command auto-approval

Users cannot tell whether common variants like LANG=C rm foo or timeout 5 mkdir out should prompt, be auto-approved, or require extra allow rules.

C. Headless guidance is especially misleading for automation

The headless page currently says shell commands still need --allowedTools or permissions.allow rules in acceptEdits mode. That appears too broad if filesystem commands are auto-approved, including safe prefixed/wrapped forms.

Suggested Improvement

Update the acceptEdits documentation on the main Claude Code pages to match current behavior:

1. Clarify that acceptEdits auto-approves file edits and a limited set of filesystem Bash commands in the working directory (for example mkdir, touch, rm, mv, cp), except protected paths.
2. Add a short note that safe env-var prefixes and safe wrappers are treated the same way, with examples from the changelog such as LANG=C rm foo and timeout 5 mkdir out.
3. Keep the distinction that other Bash commands and network requests still follow the normal permission flow unless separately allowed.
4. Align permission-modes, permissions, desktop, how-claude-code-works, and headless so they all describe the same behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permission-modes | Says acceptEdits prompts for "all non-edit actions" |
| https://code.claude.com/docs/en/permissions | Permission mode table describes acceptEdits as auto-accepting file edit permissions only |
| https://code.claude.com/docs/en/desktop | Says Auto accept edits still asks before running terminal commands |
| https://code.claude.com/docs/en/how-claude-code-works | Says Auto-accept edits "still asks for commands" |
| https://code.claude.com/docs/en/headless | Says shell commands still need --allowedTools or permissions.allow in acceptEdits mode |
| https://code.claude.com/docs/en/desktop-quickstart | Describes Auto accept edits as auto-accepting file edits only |
| https://code.claude.com/docs/en/security | Says Accept Edits keeps permission prompts for commands with side effects |
| https://code.claude.com/docs/en/agent-sdk/permissions | Agent SDK cross-reference already documents filesystem-command auto-approval |

Total scope: 7 user-facing pages appear affected, plus 1 Agent SDK cross-reference page

Source: Changelog v2.1.97

Exact changelog entry: Improved Accept Edits mode to auto-approve filesystem commands prefixed with safe env vars or process wrappers (e.g. LANG=C rm foo, timeout 5 mkdir out)