[DOCS] Logic Conflict between Sandbox "Auto-Allow" and IAM Permission Mode for File Edits

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/sandboxing

Section/Topic

The "Sandbox modes" section, specifically the interaction between autoAllowBashIfSandboxed and the global permissionMode.

Current Documentation

states:

"Auto-allow mode works independently of your permission mode setting. Even if you're not in 'accept edits' mode, sandboxed bash commands will run automatically when auto-allow is enabled. This means bash commands that modify files within the sandbox boundaries will execute without prompting, even when file edit tools would normally require approval."

However, the IAM page (https://code.claude.com/docs/en/iam#permission-system) states:

"File Modification | Edit/write files | Approval Required: Yes | Until session end"

What's Wrong or Missing?

There is a logical conflict regarding security posture that could lead to accidental unauthorized file modifications.

The IAM and Security documentation establishes a mental model where file edits always require a prompt unless the user has explicitly opted into acceptEdits mode. The Sandboxing documentation introduces a "backdoor" to this rule: if a user enables the sandbox with auto-allow (which is recommended for productivity), the agent can bypass the file-edit approval requirement simply by using a sed, echo >, or python command inside a bash block instead of using the Edit or Write tools.

The documentation does not sufficiently warn users that enabling the sandbox with autoAllowBashIfSandboxed: true (the default when enabling the sandbox) effectively grants acceptEdits permissions to the Bash tool, overriding the global default permission mode.

Suggested Improvement

1. Add a Warning Block to the Sandboxing page:

> ⚠️ Security Note on Precedence: Enabling Auto-allow mode (autoAllowBashIfSandboxed: true) takes precedence over your global permissionMode. If enabled, Claude can modify files via Bash commands without a permission prompt, even if you are not in acceptEdits mode.

1. Update the IAM/Permissions page:

Add a note to the "Permission System" table or the "Bash" section explaining that the Bash tool's approval requirement changes if the Sandbox is active in Auto-allow mode.

1. Clarify the "Safe" Boundary: Define more clearly that "safe" in the context of the sandbox refers to containment (it can't hit your .ssh folder), but it does not mean "no-edit" (it can still overwrite your source code without asking).

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
• Related documentation: https://code.claude.com/docs/en/settings#sandbox-settings
• This is particularly important for enterprise users who might rely on the "Ask" default to prevent the model from hallucinating destructive changes to the project structure.