Feature Request: Implement `--sandbox` Flag for Granular, Explicit File System and Execution Control

Title: Feature Request: Implement --sandbox Flag for Granular, Explicit File System and Execution Control

Labels: feature-request, enhancement, cli, security

Is your feature request related to a problem? Please describe.

Claude Code's current security model, based on permission modes (plan, acceptEdits, bypassPermissions) and settings.json rules, is powerful but presents a usability and security gap for many common use cases.

1. Complexity and "Permission Fatigue": The system can be complex for users to manage for ad-hoc tasks. The default mode often leads to "permission fatigue," prompting users to jump to the overly permissive --dangerously-skip-permissions mode, which is a blunt instrument that removes all safety rails.
2. Lack of a "Safe Middle Ground": There is no simple, explicit way to configure a "workspace-only" write mode. A user who trusts the agent to modify files within the project workspace but wants to strictly prohibit network access or system-wide changes has no easy command-line option.
3. Insecure by Default ("Blacklist" vs. "Whitelist"): The primary way to restrict write access is through deny rules in settings.json. This "blacklist" approach is less secure than a "whitelist" approach. It's impractical for users to create deny rules for every sensitive file on their system, creating a risk that the agent might mistakenly target files outside the immediate workspace (e.g., ../../config.json or ~/.bashrc).

This creates a significant gap between the highly restrictive plan mode and the potentially dangerous bypassPermissions mode.

Describe the solution you'd like

I propose the implementation of a --sandbox command-line flag, inspired by the robust and proven model in the OpenAI Codex CLI. This flag would provide granular, policy-based control over the agent's execution environment and would be decoupled from, and complementary to, the existing permission-mode system.

The proposed CLI syntax would be:
claude --sandbox <mode>

The modes would provide clear, tiered security policies:

• --sandbox read-only
• Behavior: The agent can read any file it has access to but is blocked from all file system writes (e.g., Edit, Write) and the execution of potentially destructive Bash commands (e.g., touch, rm). Outbound network access would also be blocked. This block would occur at the sandbox level, before the user is even prompted.
• Use Case: Safely analyzing a new codebase, answering questions, or auditing for issues in a CI pipeline with a guarantee of no side effects.

• --sandbox workspace-write
• Behavior: The agent can read from anywhere but can only perform file system writes within the current working directory (cwd) and its subdirectories. Any attempt to write outside this boundary would be blocked. Outbound network access would be prohibited by default, and Bash commands would still require explicit user permission per the existing rules.
• Use Case: This is the ideal "safe middle ground" for most development workflows like refactoring code, adding features, and writing tests. It provides a secure "sandpit" for the agent, dramatically reducing the risk of unintended system-wide modifications.

• --sandbox danger-full-access
• Behavior: Disables all sandboxing, allowing file system access limited only by the user's OS permissions. This would serve as a more descriptive and intentional alias for the existing --dangerously-skip-permissions flag.
• Use Case: For trusted, complex tasks in fully controlled and isolated environments (like the official devcontainer) where the user understands and accepts the risks.

How this complements existing features:

This --sandbox flag would be a user-friendly layer on top of the current system, enabling powerful, defense-in-depth combinations:

• The sandbox flag would define the policy baseline for the session.
• The permission-mode and settings.json rules would handle user approvals and exceptions within that baseline.

Example Scenarios:

• claude "Refactor module" --sandbox workspace-write --permission-mode acceptEdits

The user can safely auto-approve all file edits, confident that no changes can occur outside the project directory.

• claude "Analyze dependencies" --sandbox workspace-write --permission-mode default

The agent can write files (e.g., reports) within the project, but any attempt to edit a file outside the workspace will fail, even if the user accidentally approves it.

Furthermore, enterprise administrators could enforce --sandbox workspace-write via managed-settings.json to ensure a baseline level of security across the organization, while still allowing developers to manage interactive approvals. The sandbox mode should also be configurable in project/user settings.json, e.g., "sandboxMode": "workspace-write".

Describe alternatives you've considered

1. Using deny rules: As mentioned, this is a "blacklist" approach. It is difficult to maintain and is inherently less secure than whitelisting the project workspace.
2. Using allowedTools: This system controls what tools can run, but not where they can have side effects. It doesn't prevent a permitted Write tool from targeting ~/.bashrc.
3. Relying on Devcontainers: While an excellent solution for isolation, it requires a specific development setup. A built-in sandboxing mechanism provides a strong layer of defense for all users, regardless of their environment.

Why this is a valuable addition to Claude Code

1. Improves User Experience: Provides a simple, memorable, and explicit way for users to define the agent's capabilities for a given task.
2. Enhances Security Posture: Offers a safe and useful middle ground (workspace-write) that encourages users to grant only necessary permissions and moves from a blacklist to a more secure whitelist model.
3. Boosts CI/CD and Automation: A declarative flag is far easier and safer to use in scripts and automated workflows than managing configuration files or complex mode interactions.
4. Achieves Competitive Parity: This is a proven, high-value feature that a key competitor has successfully implemented, indicating clear market demand for this level of control.

Additional Context & Technical Inspiration

This proposal is heavily inspired by the successful implementation in the OpenAI Codex CLI, which has proven this decoupled, tiered model to be highly effective. For a robust, platform-native implementation, Claude Code could follow a similar path by using:

• macOS: Apple Seatbelt (sandbox-exec)
• Linux: Landlock and seccomp APIs

By implementing a --sandbox flag, Claude Code can make its powerful security features more accessible, intuitive, and secure for everyday development and automation, moving from a binary "trust or don't trust" model to a more sophisticated "trust but verify within these boundaries" model.