Claude Code Permission Modes in 2026: What , Whitelists, and Sandbox Boundaries Actually Restrict This article was written with the assistance of AI, under human supervision and review.
Most Claude Code security failures stem from treating permission modes and sandbox boundaries as interchangeable concepts.
Teams ship agents with Auto mode enabled, assuming the Bash sandbox prevents harm.
The sandbox restricts file system access.
Permission modes control whether Claude even attempts the action.
When these two layers misalign, the agent either breaks production workflows or leaks credentials through unrestricted tool calls.
The confusion compounds when engineers discover and assume whitelisting individual capabilities (like or ) provides complete protection.
It does not.
The whitelist prevents Claude from invoking forbidden tools.
It says nothing about what those allowed tools can reach once invoked.
A configuration that permits but forgets to restrict the Bash sandbox to a safe directory tree lets the agent execute without friction.
The correct architecture separates concerns.
Permission modes (Auto, Prompt, Restricted, Custom) decide whether Claude asks before acting.
Sandbox boundaries (bubblewrap on Linux, Seatbelt on macOS) define the outer limits of what Bash commands can touch.
Defense-in-depth pairs permission deny rules with tight sandbox restrictions so even a prompt-approval mistake cannot escape isolation.
Key Takeaways Permission modes control whether Claude attempts an action; sandbox boundaries limit what that action can reach if approved or auto-granted. whitelisting blocks specific capabilities like or but does not restrict file paths or network access within allowed tools.
Restricted mode denies all tool calls by default; Custom mode lets teams whitelist only essential tools while denying everything else.
Sandbox isolation (bubblewrap, Seatbelt) prevents Bash commands from accessing paths outside defined boundaries even when permission modes allow execution.
Defense-in-depth pairs permission deny rules with sandbox restrictions so a single misconfiguration cannot compromise the entire system.
The Four Permission Modes: Auto, Prompt, Restricted, and Custom Permission modes determine when Claude halts to request approval before invoking a tool.
Auto grants every capability without asking.
Prompt requires user confirmation for each tool call.
Restricted denies all tools by default.
Custom mode combines an whitelist with explicit deny rules for fine-grained control.
Auto mode ships with zero friction.
The agent edits files, runs shell commands, and installs packages without interruption.
This speed comes at a cost.
When Claude misinterprets a task and attempts to the wrong branch, Auto mode executes the command instantly.
No confirmation dialog appears.
The force-push overwrites production history before a human notices.
Prompt mode surfaces every tool invocation for approval.
The agent stops to ask: "Run ?" This visibility catches errors early but slows iteration.
Developers working in tight feedback loops approve dozens of prompts per session.
Alert fatigue sets in.
A malicious or confused request slips through because the approval reflex becomes automatic.
Restricted mode flips the default to deny.
Claude cannot invoke any tool unless the team explicitly permits it.
This mode suits production environments where the agent operates on a fixed set of well-tested tasks.
A deployment pipeline that only needs for Docker builds and for config validation can deny every other capability.
The agent cannot install packages, edit source files, or query external APIs.
Custom mode provides surgical control.
Teams define an array containing exactly the capabilities the agent requires.
A data processing workflow might permit , , and while denying and .
The configuration pairs the whitelist with explicit deny rules for high-risk tools.
This matters because the whitelist operates as an allowlist.
Omitting a tool from prevents invocation but does not block future additions without review.
Understanding --allowedTools and Whitelisting Specific Capabilities is a configuration flag that accepts an array of tool identifiers.
Engineers use it to construct a minimal permission surface.
The whitelist prevents Claude from invoking tools outside the approved set, but it does not constrain what those tools can access once invoked.
A configuration that includes in grants the agent permission to modify any file the process user can write.
The whitelist does not restrict paths.
If the agent runs with root privileges and the sandbox is misconfigured, can overwrite .
The permission mode allowed the tool invocation.
The sandbox failed to isolate file system access.
The distinction between tool invocation and resource access is critical. appears in many whitelists because automated workflows need shell execution.
A whitelist entry for permits the agent to spawn any Bash command.
It does not limit arguments or working directory.
Without a sandbox boundary, the agent can execute .
Teams often pair with deny rules to create defense-in-depth.
A configuration might whitelist and while denying and .
The deny rules act as a safety net.
If a future code change accidentally adds a high-risk tool to the whitelist, the explicit deny rule blocks invocation until a maintainer reviews the change.
The implication here is that solves the invocation problem but not the access problem.
A complete security posture requires both a whitelist and a sandbox.
Sandbox Boundaries: What bubblewrap and Seatbelt Actually Restrict Sandbox isolation operates one layer below permission modes.
Once a tool invocation succeeds (either through Auto mode or after prompt approval), the sandbox determines what system resources that tool can touch.
On Linux, Claude Code uses bubblewrap.
On macOS, it uses Seatbelt profiles.
Both technologies create a restricted execution environment that denies access to paths outside a defined boundary. bubblewrap creates a new mount namespace.
The agent's Bash commands see a minimal file system tree.
A typical configuration mounts as read-write and , , as read-only.
Everything else remains invisible.
When the agent executes , the file does not exist in the sandboxed view.
The kernel blocks the read before it reaches the real file system.
Seatbelt profiles on macOS work differently but achieve the same goal.
The profile specifies allowed paths, forbidden paths, and default deny rules.
A production profile might permit reads from and deny everything else.
When the agent attempts , the Seatbelt kernel extension intercepts the system call and returns an error.
The boundary applies to all child processes.
If the agent runs , the package manager spawns dozens of subprocesses to fetch dependencies and execute lifecycle scripts.
Every subprocess inherits the sandbox restrictions.
A malicious post-install script cannot write to or read from because the sandbox denies access at the kernel level.
Network access often escapes sandbox restrictions by default. bubblewrap can isolate the network namespace but many teams leave it open to allow dependency downloads and API calls.
This creates an asymmetry.
The agent cannot read but can exfiltrate data through .
A complete defense-in-depth configuration pairs file system isolation with network filtering or restricts to prevent arbitrary outbound connections.
The failure mode here is subtle but expensive.
Teams configure tight permission whitelists but forget to restrict the sandbox.
The agent cannot invoke but can still run through .
The sandbox allows network access.
Credentials leak through a side channel the permission mode never controlled.
Defense-in-Depth: Combining Permission Deny Rules with Sandbox Restrictions Defense-in-depth pairs multiple security layers so a single misconfiguration cannot compromise the system.
In Claude Code, this means configuring both permission deny rules and sandbox boundaries to address different failure