jamie-bitflight/permissions

Claude Code Permissions Reference

Claude Code uses a tiered permission system to balance capability and safety. Permissions control which tools Claude can use and what resources they can access.

---

Permission Tiers

| Tool Type | Examples | Approval Required | "Don't ask again" Scope | |-----------|----------|-------------------|------------------------| | Read-only | File reads, Grep, Glob | No | N/A | | Bash commands | Shell execution | Yes | Permanent per project + command | | File modification | Edit, Write | Yes | Until session end |

---

Rule Evaluation Order

Rules evaluate in order: deny → ask → allow. First match wins. Deny rules always take precedence.

flowchart TD
    Start([Tool call requested]) --> Deny{Matches a deny rule?}
    Deny -->|Yes| Blocked[BLOCKED — tool cannot run]
    Deny -->|No| Ask{Matches an ask rule?}
    Ask -->|Yes| Prompt[Prompt user for approval]
    Ask -->|No| Allow{Matches an allow rule?}
    Allow -->|Yes| Approved[APPROVED — tool runs]
    Allow -->|No| Default[Default behavior for tool type]

---

Permission Modes

Set defaultMode in settings files:

| Mode | Behavior | |------|----------| | default | Prompts for permission on first use of each tool | | acceptEdits | Auto-accepts file edit permissions for session | | plan | Read-only — cannot modify files or execute commands | | delegate | Coordination-only for team leads (requires active agent team) | | dontAsk | Auto-denies tools unless pre-approved via /permissions or permissions.allow | | bypassPermissions | Skips all permission prompts (containers/VMs only) |

WARNING: bypassPermissions disables all checks. Only use in isolated environments. Administrators can prevent it with disableBypassPermissionsMode: "disable" in managed settings.

---

Permission Rule Syntax

Rules follow the format Tool or Tool(specifier).

Match All Uses

Use tool name without parentheses:

• Bash — matches all Bash commands
• WebFetch — matches all web fetch requests
• Read — matches all file reads

Bash(*) is equivalent to Bash.

Tool-Specific Specifiers

Bash (Wildcard Patterns)

* matches at any position. Space before * enforces word boundary.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Word boundary behavior:

• Bash(ls *) — matches ls -la but NOT lsof (space enforces boundary)
• Bash(ls*) — matches both ls -la AND lsof (no boundary)

Shell operator awareness: Claude Code recognizes shell operators (&&, |, ;). A rule like Bash(safe-cmd *) will NOT approve safe-cmd && other-cmd.

Caveat: Bash argument constraint patterns are fragile. For reliable URL filtering, deny curl/wget and use WebFetch(domain:...) instead, or use PreToolUse hooks.

Read and Edit (Gitignore Patterns)

Follow gitignore specification:

| Pattern | Meaning | Example | |---------|---------|---------| | //path | Absolute path from filesystem root | Read(//Users/alice/secrets/**) | | ~/path | Path from home directory | Read(~/Documents/*.pdf) | | /path | Relative to settings file | Edit(/src/**/*.ts) | | path or ./path | Relative to current directory | Read(*.env) |

IMPORTANT: /Users/alice/file is NOT absolute. It is relative to the settings file. Use //Users/alice/file for absolute paths.

Glob behavior: * matches files in a single directory. ** matches recursively across directories.

WebFetch

• WebFetch(domain:example.com) — matches requests to example.com

MCP

• mcp__puppeteer — all tools from the puppeteer server
• mcp__puppeteer__* — wildcard, same effect
• mcp__puppeteer__puppeteer_navigate — specific tool

Task (Subagents)

• Agent(Explore) — matches Explore subagent
• Agent(Plan) — matches Plan subagent
• Agent(my-custom-agent) — matches custom agent

Deny specific agents:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

---

Managed Settings (Organization Deployment)

Administrators deploy managed-settings.json to system directories. These cannot be overridden by user or project settings.

Locations:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux/WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

These are system-wide paths (not user home directories) requiring administrator privileges.

Managed-Only Settings

| Setting | Effect | |---------|--------| | disableBypassPermissionsMode | Set "disable" to prevent bypassPermissions mode | | allowManagedPermissionRulesOnly | When true, only managed settings can define allow/ask/deny rules | | allowManagedHooksOnly | When true, only managed and SDK hooks are allowed | | strictKnownMarketplaces | Controls which plugin marketplaces users can add |

---

Settings Precedence

Highest to lowest priority:

1. Managed settings (system-wide, cannot be overridden)
2. Command line arguments
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

A permission allowed in user settings but denied in project settings is blocked.

---

Working Directories

By default, Claude has access to files in the launch directory. Extend access:

• Startup: claude --add-dir <path>
• Session: /add-dir
• Persistent: add to additionalDirectories in settings

Additional directories follow the same permission rules as the original working directory.

---

Permissions + Sandboxing

Permissions and sandboxing are complementary security layers:

• Permissions control which tools Claude can use and which resources they access (all tools)
• Sandboxing provides OS-level enforcement restricting Bash filesystem and network access (Bash only)

Use both for defense-in-depth:

• Permission deny rules block Claude from attempting access
• Sandbox restrictions prevent Bash commands from reaching resources outside boundaries
• Filesystem sandbox restrictions use Read/Edit deny rules (not separate sandbox config)
• Network restrictions combine WebFetch permissions with sandbox allowedDomains

---

Manage Permissions

Use /permissions during a session to view and manage all permission rules and their source settings files.

Detailed Reference

For comprehensive rule examples, Bash pattern edge cases, and hook-based permission extension, see references/permissions-reference.md.

SOURCE: Claude Code Permissions Documentation (accessed 2026-02-17)