[DOCS] Sandbox Edit permissions for bash write access not clearly documented

Documentation Type

Unclear/confusing documentation

Documentation Location

https://docs.claude.com/en/docs/claude-code/settings#sandbox-settings

Section/Topic

Sandbox filesystem permissions - Edit and Bash allow rules

Current Documentation

From https://docs.claude.com/en/docs/claude-code/settings#sandbox-settings, under "Sandbox settings":

"Edit allow rules permit file writes (in addition to the defaults, e.g. the current working directory)"

From https://docs.claude.com/en/docs/claude-code/sandboxing, in the "Default behavior" section:

"Filesystem restrictions are configurable: Define custom allowed and denied paths through settings"

Neither page explicitly states that Edit() rules control bash filesystem writes.

What's Wrong or Missing?

The documentation never explicitly states that Edit() allow rules extend filesystem write permissions for bash commands running in the sandbox. This creates severe confusion:

1. Users assume Write() permissions would control filesystem writes (they only control the Write tool)
2. The statement "Edit allow rules permit file writes" is ambiguous - it's unclear if this applies to:

• The Edit tool only, OR
• All bash filesystem write operations in the sandbox

1. There's no clear example showing how to allow bash commands to write outside the working directory in sandboxed mode
2. The relationship between permission rules (Edit/Write/Read) and sandbox filesystem access is never clarified
3. Users attempting to solve this problem find conflicting information online mixing non-sandboxed and sandboxed permission systems

Suggested Improvement

Add a dedicated section to the Sandboxing documentation (https://docs.claude.com/en/docs/claude-code/sandboxing), after the "Default behavior" section and before "Network restrictions":

Extending Bash Write Permissions in Sandbox Mode

By default, bash commands in the sandbox can only write to the current working directory. Any bash operation that writes files (including echo >, touch, mkdir, cp, or tools like just) will fail with "Read-only file system" errors when attempting to write outside the working directory.

To allow bash commands to write to additional directories, use Edit allow rules:

{
  "permissions": {
    "allow": [
      "Edit(/path/to/directory/**)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

Important:

• Edit() permissions extend filesystem write access for all bash operations in the sandbox
• Write() permissions only control the Write tool and do NOT affect any bash write capabilities
• Use glob patterns like /** to allow writes to all files within a directory

Common use cases:

• Allow temporary file creation: Edit(/tmp/myapp/**)
• Allow tools to write to runtime directories: Edit(/run/user/1000/just/**)
• Allow build tools to write to cache directories: Edit(/home/user/.cache/build/**)

Impact: High - Prevents users from using sandboxed mode with any bash operations that need to write to specific directories outside the working directory

Additional Context:

This issue causes severe confusion during troubleshooting where users:

1. Try Write() permissions (doesn't work - only affects the Write tool)
2. Try filesystem.allowWrite configuration (not exposed in Claude Code's settings.json)
3. Find conflicting information from people discussing non-sandboxed mode
4. Only discover Edit() works through trial and error after extensive research

The underlying sandbox-runtime library uses allowWrite configuration, but Claude Code exposes this through Edit() permissions instead - this mapping should be clearly documented.

---

Reproduction Steps

Prerequisites:

• Claude Code with sandbox enabled
• Configuration: "sandbox": { "enabled": true, "autoAllowBashIfSandboxed": true }

Steps:

1. Try any bash write operation outside the working directory:

``bash
echo "test" > /tmp/test.txt
``

1. Observe the error:

``
bash: line 4: /tmp/test.txt: Read-only file system
``

1. Add "Write(/tmp/**)" to permissions.allow list in .claude/settings.local.json

1. Reload Claude Code and retry the same command

1. Observe it still fails with the same error:

``
bash: line 4: /tmp/test.txt: Read-only file system
``
(Write permissions don't apply to bash)

1. Replace "Write(/tmp/**)" with "Edit(/tmp/**)" in settings

1. Reload Claude Code and retry

1. Observe it now succeeds:

``bash
echo "test" > /tmp/test.txt && cat /tmp/test.txt
# Output: test
``
(Edit permissions control bash filesystem writes)

Expected Documentation

The documentation should clearly state in the Sandboxing section:

• How to extend bash write permissions beyond the working directory
• That Edit() allow rules control all bash filesystem writes in sandbox mode
• That Write() allow rules only control the Write tool, not bash commands
• Examples showing common bash operations (echo, touch, mkdir, etc.) and tools
• Clear distinction between tool permissions and sandbox filesystem access

Impact

High - Prevents users from using a feature

Additional Context

Generated by: Claude Code (Sonnet 4.5) during sandbox permission troubleshooting session

Environment:

• claude-code 2.0.27 (Claude Code)
• Platform: Linux (NixOS)
• Sandbox: Enabled with autoAllowBashIfSandboxed: true
• Date: 2025-10-26

Other related docs:
https://docs.claude.com/en/docs/claude-code/sandboxing