[DOCS] Sandbox docs do not mention the v2.1.179 `denyRead`/`allowRead` glob fix or warn that broad globs over large directory trees can blow up the Bash tool description

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Configure sandboxing" example that combines sandbox.filesystem.denyRead with sandbox.filesystem.allowRead, and the "Troubleshooting" / "Limitations" sections of the same page.

Current Documentation

The "Configure sandboxing" section shows this as the canonical example for denying the home directory while re-allowing the current project (sandboxing.md lines 181-195):

The example below blocks reading from the entire home directory while still allowing reads from the current project. Place it in your project's .claude/settings.json, because the relative path . resolves to the project root only when the configuration lives in project settings: ``json { "sandbox": { "enabled": true, "filesystem": { "denyRead": ["~/"], "allowRead": ["."] } } } ` The . in allowRead resolves to the project root because this configuration lives in project settings. If you placed the same configuration in ~/.claude/settings.json, . would resolve to ~/.claude instead, and project files would remain blocked by the denyRead` rule.

The "Troubleshooting" and "Limitations" sections of the same page list host-not-allowed errors, jest watchman conflicts, Go CLI TLS failures, Docker incompatibilities, and bubblewrap-in-container failures, but do not mention anything about denyRead/allowRead pattern size, the Bash tool description, or session usability on Linux. The sandbox.filesystem.denyRead and sandbox.filesystem.allowRead rows in the configuration table (sandboxing.md lines 254-255) describe the keys in one line each and do not flag the size pitfall.

What's Wrong or Missing?

A. The v2.1.179 fix is only reflected in the changelog

The changelog entry for v2.1.179 says: "Fixed a sandbox denyRead/allowRead glob over a large directory tree making the Bash tool description enormous and the session unusable on Linux." There is no mention of this fix, the failure mode, or the Linux-specific impact on the sandboxing page, the settings reference, or the permissions page. Users who configured broad denyRead globs (e.g. ["~/"], ["/"], ["/home"]) on Linux before 2.1.179 and saw the session become unusable have no way to discover from the relevant configuration docs that the issue is fixed, that it was Linux-specific, or that the trigger was the size of the globbed tree.

B. The documented example is exactly the anti-pattern that triggered the bug

The example above uses denyRead: ["~/"] (the entire home directory) paired with allowRead: ["."] (the project root). This is precisely the kind of broad glob over a large directory tree the fix targets, so the docs are still actively showing users the configuration that was unusable on Linux before v2.1.179. The example should at minimum point readers to the v2.1.179 fix and explain that very broad denyRead patterns can still be expensive to evaluate, or it should narrow the example to a smaller, more representative directory.

C. No guidance on how to size denyRead/allowRead patterns

The "Limitations" section covers security trade-offs but not the operational trade-off of broad denyRead globs. There is no note in the "Troubleshooting" section that says "if the Bash tool description appears huge or the session becomes unresponsive on Linux, narrow your denyRead patterns" or "use specific credential directories such as ~/.aws and ~/.ssh rather than ~/". The "Keep developers from widening the policy" section does mention denyRead/allowRead merging but does not address the size of the trees those patterns cover.

Suggested Improvement

Option A: Minimum fix (add a note to the existing example and troubleshooting section)

After the denyRead: ["~/"] / allowRead: ["."] example in the "Configure sandboxing" section, add:

Note: Very broad denyRead globs over large directory trees (such as ["~/"] or ["/"]) can make the Bash tool description very large and the session slow to start. Prefer narrower patterns such as ["~/.aws", "~/.ssh", "~/.gnupg"] and rely on the sandbox's default read policy rather than denying the whole home directory. This was fixed in v2.1.179 for the worst case on Linux, but narrower patterns still keep the Bash tool description small.

In the "Troubleshooting" section, add a new bullet:

Bash tool description becomes very large or the session becomes unusable on Linux: narrow your sandbox.filesystem.denyRead patterns. Very broad globs such as ["~/"] or ["/"] expand the Bash tool description, which historically made the session unusable on Linux. Use specific credential and config directories (for example ["~/.aws", "~/.ssh"]) instead of the whole home directory. Fixed in v2.1.179.

Option B: Comprehensive fix

In addition to Option A, add a row to the "Limitations" section under a new "Operational limitations" subsection that documents the v2.1.179 fix, the Linux-specific impact, and recommends narrow patterns. Also update the sandbox.filesystem.denyRead and sandbox.filesystem.allowRead rows in the configuration table (around line 254-255) to mention the size consideration with a link to the new troubleshooting entry.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sandboxing | 181-195 | denyRead: ["~/"] + allowRead: ["."] example |
| https://code.claude.com/docs/en/sandboxing | 254-255 | sandbox.filesystem.denyRead / allowRead configuration table rows |
| https://code.claude.com/docs/en/sandboxing | 303 | "Keep developers from widening the policy" mentions denyRead and allowRead merging |
| https://code.claude.com/docs/en/sandboxing | 337-347 | Troubleshooting section (no entry for the v2.1.179 fix) |
| https://code.claude.com/docs/en/sandboxing | 349-383 | Limitations section (no operational limitations entry) |
| https://code.claude.com/docs/en/settings | 375-377 | filesystem.denyRead / allowRead / allowManagedReadPathsOnly settings reference |
| https://code.claude.com/docs/en/permissions | Managed settings table | sandbox.filesystem.allowManagedReadPathsOnly row |

Total scope: 3 pages affected (sandboxing, settings, permissions) with the primary location being the sandboxing example and troubleshooting section.

Changelog reference: v2.1.179 changelog entry on https://code.claude.com/docs/en/changelog — "Fixed a sandbox denyRead/allowRead glob over a large directory tree making the Bash tool description enormous and the session unusable on Linux."

Cross-references: Agent SDK TypeScript sandbox SandboxFilesystemConfig (https://code.claude.com/docs/en/agent-sdk/typescript) also exposes denyRead (around line 3435) and could surface the same behavior on Linux through programmatic configuration.