[DOCS] Missing documentation for the Bash tool's sandbox parameter

Documentation Type

Missing documentation (feature not documented)

Documentation Location

Settings & Permissions: https://docs.claude.com/en/docs/claude-code/iam SDK Tooling Reference (TypeScript): https://docs.claude.com/en/docs/claude-code/sdk/sdk-typescript SDK Tooling Reference (Python): https://docs.claude.com/en/docs/claude-code/sdk/sdk-python

Section/Topic

The documentation for the Bash tool's parameters and usage guidelines. The new sandbox parameter should be added to the tool's input schema and its behavior should be explained.

Current Documentation

The current documentation for the Bash tool input parameters (as seen in the SDK docs and the v1.0.113 system prompt) is:

{
  "command": "The command to execute",
  "timeout": "Optional timeout in milliseconds (max 600000)",
  "description": "Clear, concise description of what this command does...",
  "run_in_background": "Set to true to run this command in the background."
}

What's Wrong or Missing?

The documentation is missing the new sandbox boolean parameter for the Bash tool, which was introduced around version 1.0.124. This is a critical security feature that defaults to true and significantly changes how the tool operates. The documentation gives no indication of its existence, its purpose, or how to handle sandbox-related errors.

Suggested Improvement

The documentation for the Bash tool's input schema should be updated to include the sandbox parameter:

Updated Schema:

{
  "command": "The command to execute",
  "timeout": "Optional timeout in milliseconds...",
  "description": "Clear, concise description...",
  "run_in_background": "Set to true to run this command in the background.",
  "sandbox": {
    "type": "boolean",
    "description": "Set this to true to run the bash tool in a sandbox. Defaults to true."
  }
}

New Documentation Section:

A new section titled "Sandboxed Execution" should be added to the Bash tool documentation:

#### Sandboxed Execution By default, all commands executed via the Bash tool run in a sandboxed environment for enhanced security. This is controlled by the sandbox: true parameter, which is active by default. Sandbox Restrictions: - Network access is blocked. - Filesystem access is restricted to the project directory and a dedicated temporary directory. Temporary Directory: When running in sandbox mode, a temporary directory at /tmp/claude/ is made available. The TMPDIR environment variable is automatically set to this path, and most programs will use it for temporary files. Do not use /tmp directly. Handling Violations: If a command attempts an operation blocked by the sandbox, the tool will return an error containing <sandbox_violation> tags. You should report these violations to the user but avoid suggesting that they add sensitive paths (~/.bashrc, ~/.ssh/*, etc.) to an allowlist. Disabling the Sandbox: The sandbox should only be disabled if explicitly requested by the user for a trusted operation. To run a command outside the sandbox, set the parameter sandbox: false.

Impact

High - Prevents users from using a feature

Additional Context

• This feature was discovered by analyzing the internal system prompt for Claude Code v1.0.124, which contains detailed instructions for the model on how to use this feature.
• The official changelog for v1.0.124 mentions a "Fixed security vulnerability in Bash tool permission checks," which is directly related to the implementation of this sandbox. The lack of documentation means users are unaware of this significant security enhancement and its operational impact.