Claude Code Permissions and Sandboxing: Modes, Rules, and Isolation Boundaries (2026)

Claude Code permissions and sandboxing are the two layers that decide what a session may do: permission modes and rules decide whether Claude asks before an action, while the Bash sandbox and outer isolation (containers, VMs) decide what an action can reach once it runs. Since the August 14, 2026 rollout, auto mode — where a second model called the classifier reviews actions instead of you — is the default starting mode on Pro, Max, and Team plans. Based on the official documentation as of September 8, 2026, this guide maps all six modes, the rule syntax, the sandbox's OS-level boundaries, and how the layers combine.

TL;DR

• Six modes: default (Manual), acceptEdits, plan, auto, dontAsk, bypassPermissions — auto is the built-in starting mode on Pro / Max / Team (v2.1.228+ on macOS/Linux/WSL, v2.1.233+ on native Windows)
• In auto mode, a classifier model reviews actions instead of you; by default it blocks curl | bash-style download-and-execute, secret exfiltration, production deploys, force pushes, and terraform destroy
• 3 blocks in a row or 20 in a session: auto mode pauses and hands prompting back to you — the thresholds are not configurable
• Deny rules block in every mode, including bypassPermissions; broad allow rules like Bash(*) are dropped while auto mode is on
• The built-in Bash sandbox (Seatbelt on macOS, bubblewrap + socat on Linux/WSL2) enforces file and network boundaries at the OS level and combines with any mode except plan-mode interactions

The six permission modes at a glance

| Mode | What runs without asking | Best for | |---|---|---| | default (Manual) | Reads only | Reviewing every action yourself; sensitive work | | acceptEdits | Reads, file edits, common filesystem commands (mkdir, touch, mv, cp) | Iterating on code you're reviewing | | plan | Reads, plus classifier-approved commands when auto mode is available | Exploring a codebase before changing anything | | auto | Everything, with background safety checks | Long tasks, reducing prompt fatigue | | dontAsk | Only pre-approved tools | Locked-down CI and scripts | | bypassPermissions | Everything | Isolated containers and VMs only |

Three notes the table can't show. First, the mode the CLI calls Manual is the config value default — hooks and SDK code use the value, while manual works as an alias from v2.1.200. Second, plan mode blocks edits until you approve a plan, and dontAsk mode auto-denies everything that would otherwise prompt (the status bar shows ⏵⏵ don't ask on). Third, even bypassPermissions doesn't approve everything: the actions no mode auto-approves — tools matched by an explicit ask rule, for example — still prompt.

Auto mode: the classifier that reviews instead of you

In auto mode a second model, the classifier, reviews actions instead of you — and classifier calls don't count against your usage limits. Each action walks a fixed decision order, and the first matching step wins:

1. Actions matching your allow, ask, or deny rules resolve immediately.
2. Writes to protected paths go to the classifier even when an allow rule matches — and so do rm / rmdir removals targeting a critical path (v2.1.218+).
3. MCP tools marked requiresUserInteraction prompt you directly; so do connector tools your organization set to ask.
4. Ask rules that match on command content, like Bash(git push *), fall back to a permission prompt.
5. Read-only actions and file edits inside your working directory are auto-approved — except protected paths and the first read outside the working directories, which prompts.
6. Everything else goes to the classifier.

What the classifier blocks by default. The classifier trusts your working directory and the git remotes configured when the session started (a remote added mid-session is not trusted). Blocked by default: downloading and executing code (curl | bash), sending sensitive data to external endpoints, production deploys and migrations, mass deletion on cloud storage, granting IAM or repo permissions, modifying shared infrastructure, irreversibly destroying files that existed before the session, force pushes, commits or pushes that would leak secrets when they run, destructive git commands (git reset --hard, git clean -fd, git stash drop, git commit --amend on a commit this session didn't create or that was already pushed), IaC destroys (terraform destroy, pulumi destroy, cdk destroy), writing to secret managers, merging a PR no human approved, and commands-in-comments to automation like atlantis apply.

When auto mode falls back. If the classifier blocks an action 3 times in a row or 20 times in a session, auto mode pauses and Claude Code resumes prompting you; approving the prompted action resumes auto mode. The thresholds are not configurable. A blocked action shows a notification and lands in /permissions under Recently denied, where r retries it with manual approval.

Allow rules change inside auto mode. On entering, broad rules that grant arbitrary code execution are dropped: blanket Bash(*) / PowerShell(*), wildcarded interpreters like Bash(python*), package-manager run commands, and agent and Monitor allow rules. Narrow rules like Bash(npm test) stay in effect, and dropped rules are restored when you leave auto mode.

Organizations can opt out: disableAutoMode: "disable" in managed settings removes auto from the Shift+Tab cycle, forces --permission-mode auto to start in Manual, and pulls running sessions out of auto mode (v2.1.251+).

Which mode a session actually starts in

The starting mode comes from the first of these that applies: the --permission-mode flag (or --dangerously-skip-permissions), then permissions.defaultMode in a settings file, then the built-in default:

| How you run Claude Code | Built-in starting mode | |---|---| | Pro, Max, or Team plan, in a terminal or VS Code extension | auto | | Enterprise plan or Claude Console API key | default (Manual) | | claude -p or the Agent SDK | default (Manual) | | Bedrock, Agent Platform, Foundry, AWS platform, or a signed-in gateway session | default (Manual) | | Feature-flag fetching off, or first session after install/upgrade before flags arrive | default (Manual) |

Two settings-file traps: setting "auto" in a project's .claude/settings.json or .claude/settings.local.json does not take effect — the session uses the built-in default instead. Setting "bypassPermissions" in those same two files doesn't take effect either; the session starts in Manual. Both values only apply from user settings (~/.claude/settings.json), managed settings, or the CLI flag.

Permission rules: allow, ask, deny

Modes set the baseline; permission rules layer on top to pre-approve or block specific tools. The syntax is tool-specific: Bash(npm test) matches an exact command, Bash(git push *) wildcards a prefix, WebFetch(domain:example.com) gates a domain, and read-only Bash commands are recognized as a built-in safe set.

The evaluation order across scopes is simple and strict: deny rules from any scope are evaluated before allow rules — a user-level deny blocks a project-level allow, and managed settings outrank everything. One more gate: permissions.allow rules and permissions.additionalDirectories in a project's .claude/settings.json grant capability, so Claude Code only applies them after you accept the workspace trust dialog for that folder.

Inside auto mode, remember the rule-dropping behavior from the previous section: your blanket Bash(*) allow rule won't save a command the classifier wants to block — narrow rules survive, broad ones are suspended.

The Bash sandbox: OS-enforced boundaries

The sandbox flips the approval model: instead of approving each command, you define which files and network domains commands can touch, and the operating system enforces that boundary on every Bash command and its child processes. It's built in on macOS (Seatbelt — nothing to install) and Linux/WSL2 (two packages: bubblewrap for filesystem isolation, socat to relay network traffic through the sandbox proxy). Native Windows isn't supported — run Claude Code inside WSL2.

Run /sandbox to open the panel: Mode (auto-allow vs regular permissions), Overrides (whether failed commands may retry unsandboxed — allowUnsandboxedCommands), and Config. By default, sandboxed commands can write to the working directory, the session temp directory, and any directories added via --add-dir. A command that can't run sandboxed falls back to the regular permission flow, with prompts titled "Bash command (unsandboxed)".

Network isolation runs through a proxy outside the sandbox. No domains are pre-allowed: the first time a command needs a domain, Claude Code prompts — or, in auto mode, sends the request to the classifier. "Yes, and don't ask again" saves a WebFetch(domain:...) allow rule to your local settings. strictAllowlist (v2.1.219+) hardens this: anything outside the allowlist is denied instead of prompting, and allowManagedDomainsOnly in managed settings locks the allowlist to entries the admin defined.

Protected paths close the loophole the writable directory would otherwise open: inside writable directories, the sandbox still denies writes to what Claude Code loads and executes — .claude settings, skills/, agents/, commands/, hooks/, .mcp.json, your shell startup files, .gitconfig, git internals, and everything under ~/.claude including the .credentials.json store. A command that could edit those files could grant itself permissions; the sandbox makes that a denied write even when the directory is writable.

Two hardening settings worth knowing: credential masking (masked environment variables and credential files — on Linux/WSL2 a sentinel copy is read while the proxy substitutes the real value on egress — plus AWS SigV4 re-signing), and sandbox.failIfUnavailable, which turns "sandbox couldn't start, running unsandboxed" from a warning into a hard failure for managed deployments.

How the layers combine (and where they don't)

The sandbox and auto mode work independently and combine — except in plan mode, where auto-allow doesn't widen approvals. Three practical combinations:

• Manual + sandbox auto-allow: iterate locally with fewer prompts without a classifier. Deny rules still apply, and ask rules that name a command (like Bash(git push *)) still prompt. This is the middle path for people who don't have auto mode on their plan.
• Auto mode + sandbox: the classifier reviews the command string before it runs; the OS boundary holds while it runs — even if an allowed command does more than its name suggests.
• dontAsk + exact allowlist: the CI combination — Claude runs only what matches your allow rules, read-only commands, and PreToolUse-hook-approved calls; everything else is denied, never queued.

The conceptual split matters for threat modeling: permission decisions are evaluated before a command runs, based on the command string and the classifier's judgment; the sandbox is enforced by the OS on the running process, regardless of what the model chose to run.

Choosing outer isolation: sandbox runtime, dev container, or VM

The built-in sandbox restricts only Bash — file tools, MCP servers, and hooks still run on your host. When you need the whole process inside the boundary:

| Approach | What is isolated | Requires Docker | Setup effort | |---|---|---|---| | Sandboxed Bash tool | Bash commands and child processes | No | Minimal (macOS) / low (Linux, WSL2) | | Sandbox runtime | Whole Claude Code process, including file tools, MCP servers, hooks | No | Low | | Dev container | Full development environment | Yes | Medium | | Custom container | Full development environment | Yes | Medium to high | | Virtual machine | Full operating system | No | High | | Claude Code on the web | Full OS, hosted by Anthropic | No | None (subscription; GitHub for web launches) |

The docs' own honesty section is worth repeating: sandbox isolation reduces the impact of a breach, it does not eliminate risk. Any approach that allows network egress can still leak data the agent can read; any approach that mounts your project writable can still modify that code. And isolation doesn't change what's sent to the model — your prompts and the files Claude reads reach the API with or without a sandbox.

Enterprise controls worth knowing

• Managed settings outrank user and project settings; deny rules from managed scope block in every mode.
• disableAutoMode: "disable" removes auto mode for the whole org; sandbox.enabled can be enforced the same way, with failIfUnavailable as the security gate.
• strictAllowlist + allowManagedDomainsOnly pin the sandbox's network allowlist to admin-defined domains.
• Embedders can supply policy via the SDK managedSettings option, unless the admin sets the allowManaged*Only locks.
• Project-level allow rules only activate after the workspace trust dialog — a phishing-via-clone defense.

Migrating off bypassPermissions

bypassPermissions still exists for fully unattended runs inside containers and VMs — and its guardrails have tightened: it's blocked as root or via sudo on Linux/macOS, Claude Code on the web ignores it from settings files, and in a -p run the few calls that would still prompt are denied instead. If you're still using it as a daily driver on your host, the migration path is:

1. Interactive work: start in default (Manual) and enable the sandbox in auto-allow mode (/sandbox) — most builds and tests stop prompting, with no classifier involved.
2. Hands-off sessions: switch to auto mode and let the classifier review; add the sandbox for defense in depth.
3. CI: dontAsk plus an exact allowlist (claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"), inside your runner's own isolation.

Related guides

• Foundation first: The Complete Claude Code Guide — install, daily workflow, and the basics this guide assumes
• The hooks end of the permission system: Claude Code Hooks and Subagents
• Running sessions on your own hardware: Claude Code Self-Hosted Environments
• A different sandbox angle — disposable microVMs like Coop: browse the resource library
• When permissions meet the network: MCP Authorization and OAuth

Frequently asked questions

What is the default permission mode in Claude Code now?

Auto mode is the built-in starting mode on Pro, Max, and Team plans since the August 14, 2026 rollout (v2.1.228+ on macOS/Linux/WSL, v2.1.233+ on native Windows). Enterprise plans, Console API keys, claude -p, and the Agent SDK still start in Manual (default). Your own defaultMode setting survives unless you accept the one-time switch prompt, and an organization-managed default never changes.

What does the auto-mode classifier block by default?

Downloading-and-executing code (curl | bash), sending sensitive data to external endpoints, production deploys and migrations, mass cloud-storage deletion, granting IAM or repo permissions, force pushes, destructive git commands like git reset --hard and git commit --amend on older commits, IaC destroys, writes to secret managers, merging unapproved PRs, and comments that command automation. The classifier also treats the working directory's session-start git remotes as trusted and everything else as external.

What's the difference between the Bash sandbox and a dev container?

The Bash sandbox restricts only Bash commands and their child processes, per command, via the OS — file tools, MCP servers, and hooks still run on your host. A dev container puts the entire Claude Code process inside the isolation boundary, so everything is restricted. The sandbox is minimal setup and fits everyday interactive work; containers and VMs fit untrusted code and unattended runs.

Do permission rules still apply in auto mode?

Yes, and they resolve before the classifier sees anything: allow, ask, and deny rules match first in the fixed decision order. Deny rules block in every mode. The one change: on entering auto mode, broad allow rules that grant arbitrary code execution — Bash(*), wildcarded interpreters, package-manager run commands — are dropped, and restored when you leave auto mode.

Does --dangerously-skip-permissions still exist?

Yes, for fully unattended runs in containers and VMs — required isolation, and blocked as root or via sudo on Linux and macOS. Claude Code on the web ignores it from settings files; in a -p run, the few calls that would still prompt (explicit ask rules, critical-path deletions) are denied instead of prompting. Even in this mode, deny rules still block and the cross-session messaging safeguards still apply.

Can my organization force sandboxing or turn auto mode off?

Yes to both, via managed settings: disableAutoMode: "disable" removes auto mode (and pulls running sessions out of it), and sandbox enforcement with failIfUnavailable: true makes a missing sandbox a hard failure instead of a warning. strictAllowlist and allowManagedDomainsOnly pin the sandbox network allowlist to admin-defined domains.

Official references

• Choose a permission mode (mode table, auto mode mechanics, classifier block list; primary source for this guide)
• Permission rules (rule syntax, scopes, workspace trust)
• Sandboxing (Seatbelt / bubblewrap, network proxy, protected paths, credential masking)
• Sandbox environments (sandbox runtime vs dev container vs VM comparison)
• What's new W32 — auto mode becomes the default (August 2026 rollout)

This article reflects the official Claude Code documentation as of September 8, 2026 (v2.1.228+ behavior documented above). Permission behavior evolves fast — the official docs win.