Skip to content

Claude Code Complete Guide

Claude Code Permission Modes: Complete Guide to 6 Modes and Settings Hierarchy

Target Audience:

DevOps engineers and team leads who want to systematically understand Claude Code's permission system and apply it to team operations

Key Takeaways

  1. There are 6 permission modes: 3 cycled via Shift+Tab and 3 configured via JSON settings
  2. settings.json follows a 4-tier hierarchy (Managed → Project → Local → User) with upper tiers overriding lower ones
  3. Permissions and sandbox are separate layers and should be used together

Verified Environment (March 2026)

ComponentVersion / Notes
Claude Codev2.0+
Permissions DocsConfigure permissions - Claude Code Docs1
Settings DocsClaude Code settings2

Permission System Overview

Claude Code is read-only by default. File edits and command execution require explicit approval1.

Four mechanisms control this behavior: permission modes, allow/deny/ask rules, Hooks, and the sandbox. When a tool call is made, evaluation follows this order:

  1. Hooks evaluation: PreToolUse hooks run and can allow, deny, or modify the call
  2. deny rules: If the call matches a deny rule in settings.json, it is blocked (even in bypassPermissions mode)
  3. allow rules: If the call matches an allow rule, it is approved
  4. ask rules: If matched, a confirmation prompt is shown
  5. Permission mode: If none of the above match, the active mode's default behavior applies

The 6 Permission Modes

3 Modes Cycled via Shift+Tab

Press Shift+Tab during a session to cycle through these modes1:

ModeBannerBehaviorUse Case
default(no banner)Prompts for confirmation on first use of each toolNormal development; when safety is the top priority
acceptEdits⏵⏵ accept edits onAuto-approves file edits; Bash commands still require confirmationEdit-heavy tasks like refactoring or test fixes
plan⏸ plan mode onRead-only; no changes or command executionCode review, investigation, planning before execution

Additional Modes via JSON Settings

These modes are set via defaultMode in settings.json or CLI flags1:

ModeConfigurationBehaviorUse Case
dontAsksettings.json onlyAuto-denies tool calls not in allow rules (no confirmation prompt)Headless agents with an explicit allowlist; everything else silently denied
bypassPermissionsclaude --dangerously-skip-permissions or settings.jsonSkips all permission checks (deny rules and Hooks still evaluated)Isolated containers, VMs, CI/CD pipelines only
Auto Modeclaude --enable-auto-modeClaude assesses risk and auto-approves or prompts accordingly (exact criteria not public)Research preview (March 2026+). Criteria not published; use in isolated environments recommended4

Setting the Default Mode in settings.json

{
  "defaultMode": "acceptEdits"
}

Valid values for defaultMode are default, acceptEdits, plan, dontAsk, and bypassPermissions2. Auto Mode is enabled via a separate CLI flag.

settings.json 4-Tier Hierarchy

Claude Code settings are managed across 4 tiers, with higher tiers overriding lower ones2:

PriorityTypeFile PathPurpose
HighestManagedmacOS: /Library/Application Support/ClaudeCode/managed-settings.json, Linux/WSL: /etc/claude-code/managed-settings.jsonEnforce organization-wide policies (MDM deployable)
HighProject (shared).claude/settings.json (committed to source control)Team-shared project conventions
MediumProject Local (personal).claude/settings.local.json (gitignored)Personal experimentation and overrides
LowestUser~/.claude/settings.jsonCross-project personal settings

For example, if a user setting allows a permission but the project setting denies it, the project setting takes precedence and blocks it.

Permission Rule Syntax

Rules use the format Tool or Tool(specifier)1.

Basic Syntax

{
  "permissions": {
    "allow": [
      "Edit",
      "MultiEdit",
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Important Syntax Rules

Glob pattern spacing matters. Bash(ls *) matches ls -la but not lsof. However, Bash(ls*) matches both1.

Shell operator handling: Claude Code recognizes shell operators like &&. An allow rule Bash(safe-cmd *) will not approve safe-cmd && other-cmd1.

MCP tool specification uses the mcp__server-name__tool-name format. Example: mcp__puppeteer__puppeteer_navigate. Wildcards like mcp__puppeteer__* cover all tools in a server1.

Subagent control uses the Agent(AgentName) format. Adding Agent(Explore) to deny disables the Explore subagent1.

Bash Permission Limitations

Using Bash permission patterns to constrain command arguments is fragile. For example, Bash(curl http://github.com/ *) intends to restrict to GitHub URLs but can be bypassed1:

  • Options before URL: curl -X GET http://github.com/...
  • Protocol difference: curl https://github.com/...
  • Redirect: curl -L http://bit.ly/xyz

Recommended alternatives: Block Bash network tools (curl, wget, etc.) via deny rules and control allowed domains with WebFetch(domain:github.com), or implement URL validation in a PreToolUse hook1.

Relationship with Sandbox

The permission system and sandbox are complementary security layers that should be used together13:

LayerScopeControls
PermissionsAll tools (Bash, Read, Edit, WebFetch, MCP, etc.)Which tools, files, and domains Claude can access
SandboxBash tool and its child processes onlyOS-level file system and network access restrictions

The sandbox uses Seatbelt on macOS (enabled by default since v1.0.20) and bubblewrap on Linux3.

File system isolation: Allows read/write within the working directory while blocking external file changes. Network isolation: Permits connections only to approved servers, preventing data exfiltration.

Anthropic's internal testing reports that the sandbox reduced permission prompts by 84%3.

Enterprise Management

Managed Settings

To enforce organization-wide policies, use Managed Settings2. Deployed via MDM or file placement, they always override user and project settings.

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  },
  "disableBypassPermissionsMode": "disable",
  "disableAutoMode": "disable"
}

Setting disableBypassPermissionsMode to "disable" disables both the --dangerously-skip-permissions flag and bypassPermissions mode in settings.json1.

Setting disableAutoMode to "disable" disables Auto Mode (--enable-auto-mode)4.

/permissions Command

Run /permissions during a session to list all active rules and their sources (which settings.json they come from)1.

Programmatic Control with Hooks

PreToolUse hooks execute before the permission system and can programmatically allow, deny, or modify tool calls5.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 validate_command.py \"$TOOL_INPUT\"",
        "timeout": 5000
      }
    ]
  }
}

A hook returning {"hookSpecificOutput": {"permissionDecision": "allow"}} grants permission; a non-zero exit code denies the call.

Due to reported deny rule bugs (GitHub Issues #6631 etc.), combining deny rules with Hooks is recommended for security-critical restrictions.

Decision Flowchart for Production Use

SituationRecommended ModeRationale
Exploring an unfamiliar repoplanZero change risk while understanding the codebase
Routine refactoringacceptEditsEdits auto-approved, commands confirmed
20+ step agentic tasksAuto ModeJudgment-based auto-approval minimizes interruptions
Automated execution in CI/CDbypassPermissions (in container)The environment itself is the security boundary
Headless agent with fixed tool allowlistdontAsk + allow listUnlisted tools silently denied
Working on machines with production credentialsdefault + deny listAll operations individually confirmed, sensitive files blocked

Next Reads

  1. Anthropic, "Configure permissions - Claude Code Docs", https://code.claude.com/docs/en/permissions ↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  2. Anthropic, "Claude Code settings", https://code.claude.com/docs/en/settings ↩↩↩↩

  3. Anthropic Engineering, "Making Claude Code More Secure and Autonomous", https://www.anthropic.com/engineering/claude-code-sandboxing ↩↩↩

  4. Awesome Agents, "Claude Code Gets Auto Mode - No More Permission Prompts", March 9, 2026, https://awesomeagents.ai/news/claude-code-auto-mode-research-preview/ ↩↩

  5. Anthropic, "Control execution with hooks", https://docs.anthropic.com/en/docs/claude-code/hooks ↩