[DOCS] Sandboxing docs missing startup warning behavior when sandbox.enabled is true but dependencies are absent

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Prerequisites section and sandbox configuration behavior

Current Documentation

The sandboxing page documents the sandbox.enabled: true configuration and lists platform-specific prerequisites (Seatbelt on macOS, bubblewrap on Linux). However, it does not describe what happens when sandbox.enabled: true is set but the required dependencies are missing.

What's Wrong or Missing?

Changelog v2.1.78 (marked as a security fix) states that previously, when sandbox.enabled: true was configured but dependencies were missing, the sandbox was silently disabled — meaning users believed sandboxing was active when it was not. Now a visible startup warning is shown.

This is security-relevant behavior. Users who configure sandbox.enabled: true need to know:

1. What happens if dependencies are missing (startup warning, sandbox not active)
2. How to resolve the warning (install the missing dependencies)
3. That previously the sandbox could silently disable itself without notification

Suggested Improvement

Add a warning or troubleshooting note in the prerequisites or configuration section:

Warning: If sandbox.enabled: true is set but required dependencies are missing (e.g., bubblewrap on Linux), Claude Code displays a startup warning and runs without sandbox protection. Install the missing dependencies to enable sandboxing. In versions before 2.1.78, this situation caused the sandbox to silently disable itself without warning.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sandboxing | Prerequisites, configuration, and troubleshooting |
| https://code.claude.com/docs/en/settings | sandbox.enabled setting description |
| https://code.claude.com/docs/en/security | Sandbox security overview |

Total scope: 3 pages affected

Source: Changelog v2.1.78

Security: Fixed silent sandbox disable when sandbox.enabled: true is set but dependencies are missing — now shows a visible startup warning