[DOCS] Security page missing critical warning about bypassPermissions + allowUnsandboxedCommands defeating sandbox protection

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Built-in protections" section, specifically the bullet point about "Sandboxed bash tool"

Current Documentation

Sandboxed bash tool: Sandbox bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with /sandbox to define boundaries where Claude Code can work autonomously

What's Wrong or Missing?

The Security page describes the sandbox as "maintaining security" but omits a critical warning: when bypassPermissions is combined with allowUnsandboxedCommands, the sandbox protection is effectively defeated.

The Python Agent SDK reference includes this warning:

If permission_mode is set to bypassPermissions and allow_unsandboxed_commands is enabled, the model can autonomously execute commands outside the sandbox without any approval prompts. This combination effectively allows the model to escape sandbox isolation silently.

Users configuring bypassPermissions for automation may read the Security page and incorrectly assume the sandbox still provides protection. The SDK documentation has this warning, but the Security page—which is the primary resource for understanding Claude Code's security model—does not.

Suggested Improvement

Add a warning to the Security page's sandbox description:

Sandboxed bash tool: Sandbox bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with /sandbox to define boundaries where Claude Code can work autonomously ⚠️ Warning: When using bypassPermissions mode with allowUnsandboxedCommands enabled, the model can autonomously execute commands outside the sandbox without approval prompts, effectively bypassing sandbox isolation. Only use this combination in fully trusted, isolated environments.

Alternatively, add this to a new "Security considerations for automation" section that covers dangerous permission combinations.

Impact

High - Prevents users from using a feature

Additional Context

• Mirror location: code.claude.com/docs/en/security.md (line 23)
• The warning exists in the SDK reference: platform.claude.com/docs/en/agent-sdk/python.md (Sandbox Settings section)
• Related: The Permissions page describes bypassPermissions as "Bypass all permission checks" but doesn't mention sandbox implications
• Related feature request: #20260 proposes preventing this combination at runtime; this docs issue can be implemented independently as an interim measure
• This matters for users building automated pipelines who may configure bypassPermissions for convenience without realizing it compromises sandbox security when combined with other settings