claude-code - 💡(How to fix) Fix Docs: Sandboxing page implies Write/Edit tools are subject to sandbox restrictions [1 participants]

Summary

The sandboxing documentation has two sections with wording that implies the built-in Write and Edit tools are subject to sandbox restrictions.

1. "Filesystem isolation" section

The sandboxed bash tool restricts file system access to specific directories:

• Default writes behavior: Read and write access to the current working directory and its subdirectories
• Default read behavior: Read access to the entire computer, except certain denied directories

Despite saying "sandboxed bash tool", the bullet points read as general file access rules for Claude Code. A reader would reasonably conclude that Write/Edit are also restricted to the working directory — they are not. Write/Edit can write anywhere the user approves via the permission prompt.

2. "not just Claude's file tools"

These restrictions are enforced at the OS level (Seatbelt on macOS, bubblewrap on Linux), so they apply to all subprocess commands, including tools like kubectl, terraform, and npm, not just Claude's file tools.

The phrase "not just Claude's file tools" suggests the sandbox applies to Write/Edit AND subprocess commands. In practice, Write and Edit bypass the sandbox entirely.

Observed behavior

With sandbox enabled and allowOnly restricting writes to the working directory:

• Bash: echo "test" > ~/other-dir/file.txt → blocked with "Operation not permitted" (expected)
• Write tool: writing to ~/other-dir/file.txt → permission prompt shown, succeeds if approved

This confirms the sandbox only applies to Bash subprocesses, not the built-in file tools.

Suggested fix

Make it explicit that these restrictions apply only to Bash subprocesses:

Section 1 — clarify scope:

The sandbox restricts Bash subprocess file system access to specific directories. The built-in Write and Edit tools are not affected by these restrictions — they use the permissions system instead.

Section 2 — fix the misleading phrase:

These restrictions are enforced at the OS level (Seatbelt on macOS, bubblewrap on Linux), so they apply to all Bash subprocess commands, including tools like kubectl, terraform, and npm. Note: the built-in Write and Edit tools are not subprocesses — they use the permissions system instead.