Claude Code Permissions and Tools Allowlist

Configure Claude Code permission modes, allowed tools, deny rules, MCP tools, shell command patterns, and safer automation workflows.

Claude Code permissions decide which tools can run and when Claude must ask before acting. Treat the allowlist as a workflow boundary, not a convenience toggle. The goal is enough access to move quickly, while keeping risky actions visible and recoverable.

Quick Answer

Use permission modes for the overall workflow, and tool rules for the exact surface area. For sensitive work, pair plan mode with read-only tools. For headless automation, use an explicit allowlist and deny anything that should never run.

Need	Recommended setup
Understand a codebase	`plan` mode plus read/search tools.
Small feature work	Allow reads, edits, tests, `git status`, and `git diff`.
CI or PR summary	Print mode with a narrow allowlist.
Auth, billing, migration, deployment	Start in `plan`, approve implementation step by step.
MCP access	Allow exact `mcp__server__tool` names where possible.
Dangerous operations	Add deny or disallowed rules, not just missing allow rules.

Permission Modes vs Tool Rules

These are related but not the same:

Control	What it does
Permission mode	Sets the overall approval behavior for a session.
Allowed tools	Pre-approves specific tools or command patterns.
Deny or disallowed tools	Blocks tools or patterns, often before mode approval.
Sandbox settings	Adds OS-level limits for shell commands and child processes.
Managed settings	Lets organizations enforce policy across machines.

The key detail from official docs: allow rules approve matching tools, but deny rules are what block tools. Do not assume that a tool is unavailable just because it is missing from an allowlist.

Settings Precedence

Claude Code reads settings from multiple places. Scalar settings, such as permissions.defaultMode, follow this priority order:

Priority	Source	What it means
1	Managed settings	Organization policy. Cannot be overridden.
2	Command line arguments	Temporary override for the current session.
3	Local project settings	`.claude/settings.local.json`, personal to this repo.
4	Shared project settings	`.claude/settings.json`, committed for the team.
5	User settings	`~/.claude/settings.json`, default for your projects.

Array settings behave differently. Permission arrays such as permissions.allow, permissions.ask, and permissions.deny merge across scopes and are de-duplicated instead of replacing each other. The same applies to many sandbox filesystem arrays. Use /status to verify which settings sources Claude Code loaded for the current session.

For permission rules, matching order matters: deny rules are checked first, then ask rules, then allow rules. The first matching rule wins.

Common Permission Modes

Mode	Good for	Caution
`default`	Everyday interactive work	Sensitive actions may still ask for approval.
`plan`	Research, architecture, code review, risky changes	Read-only planning, not implementation.
`acceptEdits`	Faster coding in a trusted working directory	It does not broadly approve every MCP tool.
`dontAsk`	Fixed-surface automation	Anything not pre-approved is denied.
`auto`	Model-classified approvals where supported	Behavior depends on environment support.
`bypassPermissions`	Throwaway sandboxes only	Do not use on normal workstations or production repos.

Sandbox vs Permissions

Permissions decide whether a tool call may run and whether Claude Code asks first. Sandboxing limits what a Bash command and its child processes can access after the command starts.

Control	Covers	Does not cover by itself
Permission rules	Tool approval, `Read`, `Edit`, `Bash`, `WebFetch`, MCP tool names.	OS-level isolation for subprocesses.
Bash sandbox	Bash commands and child processes, filesystem and network boundaries.	Built-in file tools, MCP servers, hooks, and computer use.
Sandbox runtime or VM	The whole Claude Code process when configured that way.	Approval policy unless permission modes are also set.

In auto-allow sandbox mode, sandboxed Bash commands can run without individual prompts, but explicit deny rules are still respected. Commands that cannot run inside the sandbox fall back to the regular permission flow unless strict sandbox settings disable that escape hatch.

Practical Allowlist Examples

Read-Only Exploration

Use this when you want Claude Code to map a repository without changing it:

{
  "permissions": {
    "defaultMode": "plan",
    "allow": ["Read", "Glob", "Grep", "LS"]
  }
}

Small Feature Work

Allow project reads, edits, tests, and safe Git inspection:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "LS",
      "Edit",
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": ["Bash(sudo *)", "Bash(rm -rf *)"]
  }
}

PR Summary Automation

Use print mode with a narrow set of tools:

claude -p "Summarize this pull request and list test risks" \
  --allowedTools "Read,Glob,Grep,LS,Bash(git diff:*)" \
  --permission-mode plan

MCP Tool Allowlist

MCP tools use names like:

mcp__github__list_issues
mcp__context7__resolve_library_id

Prefer exact names for write-capable services:

{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",
      "mcp__github__get_pull_request",
      "mcp__context7__*"
    ]
  }
}

Use wildcards only when the whole server is appropriate for the session. A documentation lookup server is a different risk profile from a GitHub, Slack, database, or deployment server.

Shell Command Rules

Shell patterns should be specific:

Broad pattern	Safer pattern
`Bash(*)`	`Bash(npm test)`
`Bash(git *)`	`Bash(git status)`, `Bash(git diff)`
`Bash(npm *)`	`Bash(npm run build)`, `Bash(npm test)`
`Bash(rm *)`	Usually deny, then approve one-off cleanup manually.

If a command can delete files, change credentials, publish packages, deploy, or modify infrastructure, keep it out of the default allowlist.

Team Policy Checklist

Keep shared permissions narrow by default.
Add deny rules for operations that should never run unattended.
Use plan mode for auth, payment, database, deployment, and cross-module refactors.
Review .claude/settings.json or project settings before committing.
Document allowed MCP servers and their token scopes.
Prefer temporary approvals for one-off tasks.
Use managed settings when an organization needs enforced policy.

Common Mistakes

Treating allow rules or --allowedTools as a complete security boundary.
Using bypassPermissions with a small allowlist and expecting the allowlist to constrain it.
Allowing broad shell patterns for convenience.
Giving a read-only task write-capable MCP tools.
Committing personal tool permissions as team defaults.

Official Sources

Next: GitHub CLI Integration - Connect GitHub workflows without opening unnecessary permissions.

Claude Code Permissions and Tools Allowlist

On this page