[DOCS]

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

Permission rule scope — Read() deny rules and Bash tool isolation

Current Documentation

The docs state that permissions deny rules (e.g. Read(~/.zshrc)) only block Claude's built-in Read tool, and that the sandbox is needed to constrain Bash subprocess access to the same files. From the sandboxing docs: "Sandboxing provides OS-level enforcement restricting what Bash commands can access at the filesystem and network level. It applies only to Bash commands and their child processes."

What's Wrong or Missing?

Experimentally verified on v2.1.79 (macOS, Apple Silicon M2 Pro, sandbox disabled): Read() deny rules also block Bash subprocess access to the same files. Adding Read(~/.eNotesCurrent.md) to the deny list immediately blocked Bash(cat:*) on that file, despite cat being explicitly in the allow list and the sandbox being completely disabled. Removing the deny entry restored Bash access. This was tested with cat, grep, and head — all blocked when the Read() deny was present, all working when it was removed.

This behaviour contradicts the documentation but is extremely useful — it means the permissions deny list is effective for both native tools and Bash commands without requiring the sandbox.

Suggested Improvement

Questions:

1. Is this intentional behaviour? If so, please document it.
2. If it's considered a bug, please be aware that users rely on this as their primary security mechanism when the sandbox is not viable (e.g. due to the network proxy silently blocking tools like dotnet that don't honour HTTP_PROXY).

Impact

High - Prevents users from using a feature

Additional Context

_No response_