Claude Code Permissions Guide: 6 Modes, Allowlists, and the Security Sandbox Explained

What Are Claude Code Permission Modes and How Should You Configure Them?

Claude Code reads, writes, and executes in your real codebase. This guide breaks down all 6 permission modes, shows you how to build allowlist/denylist rules, explains the 5-layer config priority chain, and clarifies how the OS-level sandbox adds a second line of defense. By the end, you will know exactly how to let AI ship code without giving it the keys to production.

The 30-Second Answer

Claude Code directly edits files and runs commands on your machine. Permissions are not annoying pop-ups; they are the mechanism that makes AI-assisted coding safe enough for real projects.

Three rules cover 90% of use cases: Use default mode daily (read-only by default, asks before any write). Switch to plan mode for large refactors (read-only exploration, produces a plan before touching files). Never touch bypassPermissions unless you are inside a disposable container.

The most common beginner mistake: jumping straight to bypassPermissions or --dangerously-skip-permissions to avoid prompts, then discovering AI changed files you never reviewed. The more important the project, the less you should equate "fewer prompts" with "no prompts at all."

Key takeaways:

• Claude Code has 6 permission modes: default / acceptEdits / plan / auto / dontAsk / bypassPermissions.
• Press Shift+Tab to cycle through default, acceptEdits, and plan. The other three require launch flags.
• Fine-grained control uses allow / ask / deny arrays in settings.json. Evaluation order: deny first, then ask, then allow.
• Configuration spans 5 layers. Priority from highest to lowest: managed policy > CLI flags > local > project > user. A deny at any layer cannot be overridden below it.
• The security sandbox is not a permission mode. It enforces OS-level file and network boundaries after commands start running.

Why Should Beginners Care About Permissions?

Permissions act as a brake on "letting AI actually do things." Claude Code differs from suggestion-only chat tools in one critical way: when it edits a file, the file changes. When it runs a command, the command executes. Greater capability demands a matching control mechanism.

Beginners face higher risk for a straightforward reason: you do not yet know the project structure well enough to spot a dangerous command on sight. Opening permissions too wide at this stage invites the AI to modify files it should not touch or run commands with consequences you did not anticipate.

This is also why Claude Code can be trusted inside real codebases. Its permission system is layered, configurable, and auditable. You can always halt a risky operation before it happens. Model capability matters, but the "brake pedal" boundary mechanism determines whether you dare use it on projects that matter.

Conservative does not mean idle. You can let Claude analyze read-only, produce a plan, and list the permissions it needs. Approve only after you review. That keeps tasks moving forward while preserving your judgment. Mature usage is not permanent refusal or permanent approval. It is treating different risks differently.

I learned this the hard way early on. During one of my first Claude Code sessions, I granted broad write access to speed things up on a personal project. Claude restructured three config files I had not committed yet. The changes mixed with my uncommitted work, and untangling them took longer than the original task. Since then, I always git commit a clean checkpoint before expanding permissions, and I start every new project in default mode for at least the first session.

What Does Claude Code's Permission System Actually Control?

The permission system gates whether Claude Code can perform a given action category: reading files, writing files, running commands, accessing the network, invoking tools, or triggering external services. Each category carries different risk, so a blanket allow/deny makes no sense.

Anthropic's official docs split tools into three risk tiers:

Think of Claude Code in default mode as a read-only intern. It can look, search, and analyze freely. The moment it wants to modify a file or run a command, it raises its hand and asks first. Permission modes and rules are the "which tasks require reporting and which can proceed independently" handbook you write for that intern.

When evaluating a permission request, look beyond the binary allow/deny. Ask three questions: What is the purpose of this action? How wide is the blast radius? Can it be rolled back? Reading is usually low-risk, but reading API keys or customer data requires caution. Running commands varies entirely by content: checking status or running tests is typically safe, while deleting files or deploying to production demands careful review.

The 6 Permission Modes Compared

Claude Code ships with 6 permission modes. Many older tutorials only cover 3 plus a bypass flag, so they are outdated. Each mode differs in which actions proceed without asking you:

Picture these 6 modes as gears on a permission dial. default is the most controlled gear: nearly everything asks first. bypassPermissions is the most aggressive: nothing asks at all. The four modes in between each occupy a different position on the "convenience vs. control" spectrum. Shift up or down based on task risk.

One safety baseline spans all modes except bypassPermissions: writes to protected paths are never auto-approved. This covers .git, .claude, .vscode, .idea directories and dotfiles like .bashrc, .zshrc, .gitconfig. These are too sensitive for any permissive mode to touch silently. This is Claude Code's failsafe against "AI corrupts the repo state or its own configuration."

Default Mode and Plan Mode Explained

These two modes cover 90% of beginner scenarios. Master them first.

default mode is the factory state. Read-only actions run immediately. File modifications and non-read commands trigger a prompt on first use. You can choose "allow this time" or "always allow this type." The balance is practical: reads never interrupt you, but every write and command stays under your direct supervision. Start here. You cannot go wrong.

plan mode is "read-only plus planning." Claude reads files, runs read-only commands to explore, and produces a modification plan, but never touches your source files. After completing the plan, it stops and asks: approve and execute, refine the plan further, or review each proposed change manually.

Switch to plan mode when:

• You face architecture-level changes (refactoring, migration) and need to see the full picture first
• You open an unfamiliar codebase for the first time and want Claude to map the structure
• You are unsure how many files an operation will affect
• You want to verify Claude understands your requirements before it acts

From my experience running production workflows, plan mode is the most underrated gear. The most common beginner mistake is letting AI edit immediately, discovering the direction was wrong, then rolling back and starting over. Spending two minutes reviewing a plan of "what Claude intends to do" costs far less than twenty minutes cleaning up "what Claude already did wrong." The larger the change, the more you should plan first.

What Does acceptEdits Mode Auto-Approve?

acceptEdits mode lets Claude create and edit files inside the working directory without per-file prompts. The status bar shows "accept edits on." Beyond file edits, it auto-approves exactly seven common file commands per the official docs: mkdir, touch, rm, rmdir, mv, cp, and sed (harmless wrappers like timeout or nice prefixed to these commands also pass).

Auto-approval only covers the current working directory and any directories you explicitly added via additionalDirectories. It has clear boundaries, not a blank check:

• Paths outside the working directory still prompt you
• Writes to protected paths (.git, .claude, etc.) still prompt you
• Bash commands beyond those seven still prompt you

Risk level: moderate. File edits skip confirmation, but git still provides an audit trail and rollback path. Use it for mechanical repetitive tasks (like generating test file templates where clicking approve every time adds friction) when you already have a clean git checkpoint. Avoid it for critical code changes, unfamiliar projects, or any state where you have not committed recently.

A common pitfall: treating acceptEdits as "full auto." Someone lets Claude modify fifteen files in an uncommitted working tree, realizes the direction was wrong, and discovers the changes are tangled with their original uncommitted work, making rollback painful. The correct workflow: git commit a clean checkpoint first, switch to acceptEdits, work through a batch, then switch back to default and review.

What Are Auto Mode and dontAsk Mode?

These two modes arrived in 2026. Most beginners will not need them immediately, but you should know they exist and how they differ from the modes above.

auto mode lets Claude execute without prompts, but an independent classifier model reviews every action before it runs. The classifier automatically blocks three categories: actions outside the scope of your current request, actions targeting unfamiliar infrastructure, and actions that appear to be driven by malicious content Claude read. It defaults to allowing "local file operations in the working directory, installing packages from the dependency manifest, read-only network requests." It defaults to blocking "curl-pipe-bash execution, sending sensitive data to external endpoints, production deployments and migrations, force-pushing or pushing directly to main."

auto mode has four hard prerequisites. Miss any one and it will not activate:

• Version: Claude Code v2.1.83 or newer
• Model: Claude Opus 4.6+ or Sonnet 4.6. Older models (Sonnet 4.5, Opus 4.5, Haiku) are not supported
• Platform: Anthropic API only. Not available on Bedrock, Vertex, or Foundry
• Organization: Team and Enterprise accounts require an admin to enable it in the dashboard

If Claude Code reports that auto is unavailable, one of these four conditions is unmet. It is a research preview: it reduces prompts but does not guarantee safety. Use it only for tasks where you trust the general direction, and do not rely on it as a substitute for human review of sensitive operations.

dontAsk mode takes the opposite approach: it only runs tools you pre-approved, automatically rejecting everything else (including actions that would normally prompt). This is the fully automated mode for CI pipelines and locked-down environments. Like auto, it does not appear in the Shift+Tab cycle and requires a launch flag.

Think of auto as hiring an assistant who makes independent judgment calls: you do not micromanage, and it avoids dangerous actions on its own, but its judgment is not perfect. Think of dontAsk as a vending machine that only accepts items on the menu, rejecting everything else without discussion.

Why Should 99% of Users Avoid bypassPermissions?

bypassPermissions mode skips every permission prompt and safety check. Tool calls execute immediately. This is Claude Code's only mode that can cause unrecoverable damage. The legacy flag --dangerously-skip-permissions is equivalent.

Legitimate use cases are narrow: disposable containers, one-shot VMs, air-gapped dev containers where Claude cannot damage your host machine. Never use it on production code, unfamiliar projects, or the first time you run a given prompt.

Hard constraints worth knowing:

• It has zero protection against prompt injection. If you want prompt-free operation with background safety checks, use auto mode instead
• Even in this mode, rm -rf / and rm -rf ~ (commands that delete the root or home directory) still trigger a prompt as a last-resort safeguard against model errors
• You cannot switch into bypassPermissions from an existing session. You must restart with --permission-mode bypassPermissions (or the legacy --dangerously-skip-permissions)
• Running this mode as root or via sudo on Linux and macOS is blocked at startup
• Admins can set disableBypassPermissionsMode to disable in managed settings to ban it organization-wide

In my workflows, I have never found a scenario where bypassPermissions was genuinely necessary outside of throwaway Docker containers. When you feel "nothing else will work," the actual problem is almost always that your allowlist rules are not configured properly. The cost asymmetry is severe: it saves a few seconds when things go right, but one mistake can cost you an entire project. Keep it inside isolated environments and never bring it into real work.

Configuring Allowlist and Denylist Rules

Modes set the baseline. Fine-grained control comes from rules. Your settings.json has three arrays under permissions that form your allowlist and denylist:

• allow: allowlist. Matching actions auto-approve without prompting
• ask: always prompt for confirmation
• deny: denylist. Matching actions are blocked outright

Rules follow the format Tool or Tool(specific content). Here are the patterns from the official docs:

A beginner-friendly daily configuration:

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm run *)",
      "Bash(git status *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push *)"
    ]
  }
}

This ruleset means: npm scripts, git status, and git log auto-approve. Delete commands and push commands are always blocked.

The critical mechanism: evaluation order is always deny then ask then allow. The first matching rule wins. This means deny always takes priority. If an action matches both a deny entry and an allow entry, it gets blocked.

A common pitfall with allowlists: trying to restrict command arguments with patterns like Bash(curl http://github.com/ *) to limit curl to a specific domain. This is fragile. Switching to https, adding a -X GET flag, using variable interpolation, or even adding an extra space breaks the match. The official recommendation: block curl and wget in your denylist, then use WebFetch(domain:...) to allow trusted domains. For dynamic argument validation, use PreToolUse Hooks, which run a script before the permission prompt and can make context-aware allow/block decisions. Allowlists are fast for static rules; Hooks handle the cases where arguments matter.

The 5-Layer Configuration Priority System

Permission rules can live in 5 locations. Priority flows from highest to lowest:

One iron rule: a deny at any layer cannot be allow-ed back by a lower layer. If the project-level config denies a permission but the user-level config allows it, the deny wins. The reverse also holds: a user-level deny overrides a project-level allow. This works because deny rules at every layer evaluate before all allow rules.

The mental model is simple: "higher layers are more authoritative, and deny always wins." Put personal preferences at the user level (reused across projects). Put team rules at the project level (committed to git, shared). Put experiments in local settings (does not pollute the repo). Put organizational red lines in managed settings (nobody can override). Get the layers right, and permissions stay clean no matter how many people collaborate.

How Is the Security Sandbox Different from Permission Modes?

Many developers conflate "sandbox" with "permission modes." The official docs explicitly clarify: /sandbox is not a permission mode. They are two complementary layers.

The one-sentence distinction:

• Permission modes decide "should this tool call run, and should it ask first?" Claude Code evaluates this before execution.
• The security sandbox decides "what can this bash command access after it starts running?" The operating system enforces this.

The sandbox confines bash commands and their child processes inside an OS-level container. By default, commands can only write to the current working directory. Read access is broader but can be tightened. Network access starts at zero: no domain is pre-approved, and Claude asks the first time it connects to any new domain. The OS mechanisms behind this are Seatbelt on macOS and bubblewrap on Linux and WSL2. Native Windows does not support the sandbox; you need to run Claude Code inside WSL2. Activate it with the /sandbox command, which offers two modes: auto-approve sandbox prompts or follow normal permission prompts.

Think of permission modes as the security guard at the door who decides "does this person get in, and do they need to sign the visitor log?" Think of the sandbox as the walls and locked doors inside the building that determine "once inside, which rooms can they enter and which drawers can they open?" One controls entry. The other controls access after entry. Both cover different segments of the security chain.

Why use both layers? This is the core of defense in depth. Permission rules intercept Claude's intentions before execution. The sandbox enforces hard OS boundaries when commands actually run. Even if a prompt injection tricks Claude into executing a dangerous command, the sandbox's OS boundary still stands, preventing the command from reaching files or networks outside the allowed scope. For beginners, you do not need complex sandbox rules on day one. Knowing "it serves a different function from permission modes and adds an extra safety layer" is enough to get started.

What Are the 5 Most Common Permission Mistakes?

Mistake 1: Opening everything to avoid prompts. Feels smooth short-term, dangerous long-term. The fix: layer your permissions by risk. Low-risk commands go in the allowlist. High-risk operations keep their confirmation prompts.

Mistake 2: Looking at the command name but ignoring the working directory. The same command produces completely different effects in different directories. When reviewing a permission request, place it in context: what directory is Claude in, and which files will this touch?

Mistake 3: Approving edits without reviewing diffs. Claude's text summary of what it changed is not verification. The diff is the ground truth. Build the habit of running git diff after every batch, especially in acceptEdits mode.

Mistake 4: Treating publish, commit, and delete like ordinary writes. These are high-risk actions that affect real users, real assets, or external systems. They require individual confirmation and should never be placed in an auto-approve list.

Mistake 5: Treating the sandbox as bulletproof. The sandbox blocks out-of-bounds file access, but it has limits. Network filtering does not decrypt TLS traffic. Allowing a broad domain like github.com could still permit data exfiltration. The sandbox reduces risk; it does not eliminate it. Pair it with permission rules for solid coverage.

What Is a Good Practice Schedule for Learning Permissions?

Permissions are not something you understand by reading. You build intuition through practice. Follow this progression:

Day 1: Read-only analysis. Stay on default. Let Claude read the project structure, explain files, and flag areas it considers risky. Approve nothing.

Day 2: Single-file writes. Allow Claude to modify one file. Run git diff immediately after. Confirm the change matches your intent.

Day 3: Low-risk command execution. Let Claude run tests or format checks. Before approving, ask it to explain in plain language what the command does, what it reads and writes, and what happens if it fails.

After one week: Plan-driven medium tasks. Enter plan mode for a medium-sized change. Review the plan, then approve execution. Keep high-risk actions (deployments, deletions) at the "prepare the command but do not execute" level.

After two weeks: Solidify your rules. Move every low-risk command you have been approving daily into your settings.json allowlist. Move every action that made you hesitate into the deny list. Once your rules stabilize, prompts decrease noticeably, but the boundaries remain.

Skipping the first few days is tempting. Many developers try to hand off an entire feature on day one, then get either buried in prompts or burned by overly broad permissions. Incremental authorization is slower at first, but each step produces visible results within a controlled scope. That beats a one-shot permission grant that goes wrong in unpredictable ways.

Final Thoughts: Clear Boundaries Make AI Collaboration Work

The core of permissions is boundary clarity. You are not distrusting Claude Code. You are ensuring it operates within the right scope. Clear boundaries make AI execution meaningful.

When you are unsure whether to approve an action, ask Claude to explain four things: What does this action do? How wide is the impact? Can it be undone? Is there a read-only alternative? If it can answer clearly, consider approving.

The best permission setup is not "always prompt" or "always auto-approve." It is letting low-risk tasks flow and stopping high-risk actions cold. Layer your permissions, solidify rules over time, and let the sandbox provide a second line of defense. That combination turns Claude Code into a controllable execution partner rather than an opaque black box.

Related Reading

• Claude Code Complete Guide 2026 - The complete Claude Code reference guide
• Claude Code Hooks Tutorial - Hooks enforce and extend permission rules
• Codex Sandbox & Security Guide - Compare with Codex sandbox security model
• Claude Code Slash Commands - Commands that respect permission boundaries
• AI Agent Security & Channels - Agent-level security in the OpenClaw runtime

Frequently Asked Questions

What does Claude Code's permission system actually control?

Claude Code's permission system gates whether the AI can read files, write files, execute shell commands, access the network, and invoke external tools. Unlike chat-based AI assistants that only suggest code, Claude Code directly modifies real files and runs real commands. The permission system ensures you approve risky operations before they happen, protecting sensitive code, preventing accidental deletions, and keeping you in control.

How do I switch between permission modes?

Press Shift+Tab in the command line to cycle through default, acceptEdits, and plan. The current mode appears in the status bar. You can also launch with claude --permission-mode plan. To set a persistent default, add permissions.defaultMode to your settings.json. The auto, dontAsk, and bypassPermissions modes require launch flags or specific conditions to activate.

What is the difference between the sandbox and permission modes?

They are complementary layers. Permission modes decide whether a tool call should run at all, evaluated before execution. The sandbox restricts what bash commands can access after they start running, using OS-level enforcement: Seatbelt on macOS, bubblewrap on Linux and WSL2. Together they form defense in depth: even if a prompt injection gets past Claude's judgment, the sandbox's OS boundary still blocks access to files and networks outside the allowed scope.

Why can't I enable auto mode?

Auto mode has four requirements: Claude Code v2.1.83+, Claude Opus 4.6+ or Sonnet 4.6 model, Anthropic API platform (not Bedrock/Vertex/Foundry), and admin enablement for Team/Enterprise accounts. If Claude Code says auto is unavailable, one of these conditions is unmet. It is a research preview, not a production guarantee.

How do allowlist and denylist rules get evaluated?

The fixed evaluation order is deny first, then ask, then allow. The first matching rule wins. This means a deny entry always takes priority: if an action matches both deny and allow, it gets blocked. Rules use the format Tool(pattern) with wildcard support. For dynamic argument validation beyond static patterns, use PreToolUse Hooks.

Where to Go Next

Permissions work best alongside hooks, tool integrations, task instructions, and project configuration. Continue with these topics:

• Claude Code official permission modes documentation
• Claude Code permissions configuration reference
• Claude Code sandboxing documentation

— Leo