Configure permissions

Control what Claude Code can access and do with fine-grained permission rules, modes, and managed policies.

Claude Code supports fine-grained permissions so that you can specify exactly what the agent is allowed to do and what it cannot. Permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.

Permission system

Claude Code uses a tiered permission system to balance power and safety:

Manage permissions

You can view and manage Claude Code's tool permissions with /permissions. This UI lists all permission rules and the settings.json file they are sourced from.

• Allow rules let Claude Code use the specified tool without manual approval.
• Ask rules prompt for confirmation whenever Claude Code tries to use the specified tool.
• Deny rules prevent Claude Code from using the specified tool.

Rules are evaluated in order: deny -> ask -> allow. The first matching rule wins, so deny rules always take precedence.

Permission modes

Claude Code supports several permission modes that control how tools are approved. Set the defaultMode in your settings files:

Permission rule syntax

Permission rules follow the format Tool or Tool(specifier).

Match all uses of a tool

To match all uses of a tool, use just the tool name without parentheses:

Bash(*) is equivalent to Bash and matches all Bash commands.

Use specifiers for fine-grained control

Add a specifier in parentheses to match specific tool uses:

Wildcard patterns

Bash rules support glob patterns with *. Wildcards can appear at any position in the command. This configuration allows npm and git commit commands while blocking git push:

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

The space before * matters: Bash(ls *) matches ls -la but not lsof, while Bash(ls*) matches both. The legacy :* suffix syntax is equivalent to * but is deprecated.

Tool-specific permission rules

Bash

Bash permission rules support wildcard matching with *. Wildcards can appear at any position in the command, including at the beginning, middle, or end:

• Bash(npm run build) matches the exact Bash command npm run build
• Bash(npm run test *) matches Bash commands starting with npm run test
• Bash(npm *) matches any command starting with npm
• Bash(* install) matches any command ending with install
• Bash(git * main) matches commands like git checkout main, git merge main

When * appears at the end with a space before it (like Bash(ls *)), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, Bash(ls *) matches ls -la but not lsof. In contrast, Bash(ls*) without a space matches both ls -la and lsof because there's no word boundary constraint.

When you approve a compound command with "Yes, don't ask again", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving git status && npm test saves a rule for npm test, so future npm test invocations are recognized regardless of what precedes the &&. Subcommands like cd into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.

Read and Edit

Edit rules apply to all built-in tools that edit files. Claude makes a best-effort attempt to apply Read rules to all built-in tools that read files like Grep and Glob.

Read and Edit rules both follow the gitignore specification with four distinct pattern types:

On Windows, paths are normalized to POSIX form before matching. C:\Users\alice becomes /c/Users/alice, so use //c/**/.env to match .env files anywhere on that drive. To match across all drives, use //**/.env.

Examples:

• Edit(/docs/**): edits in <project>/docs/ (NOT /docs/ and NOT <project>/.claude/docs/)
• Read(~/.zshrc): reads your home directory's .zshrc
• Edit(//tmp/scratch.txt): edits the absolute path /tmp/scratch.txt
• Read(src/**): reads from <current-directory>/src/

WebFetch

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

MCP

• mcp__puppeteer matches any tool provided by the puppeteer server (name configured in Claude Code)
• mcp__puppeteer__* wildcard syntax that also matches all tools from the puppeteer server
• mcp__puppeteer__puppeteer_navigate matches the puppeteer_navigate tool provided by the puppeteer server

Agent (subagents)

Use Agent(AgentName) rules to control which subagents Claude can use:

• Agent(Explore) matches the Explore subagent
• Agent(Plan) matches the Plan subagent
• Agent(my-custom-agent) matches a custom subagent named my-custom-agent

Add these rules to the deny array in your settings or use the --disallowedTools CLI flag to disable specific agents. To disable the Explore agent:

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

Extend permissions with hooks

Claude Code hooks provide a way to register custom shell commands to perform permission evaluation at runtime. When Claude Code makes a tool call, PreToolUse hooks run before the permission prompt. The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed.

Skipping the prompt does not bypass permission rules. Deny and ask rules are still evaluated after a hook returns "allow", so a matching deny rule still blocks the call. This preserves the deny-first precedence described in Manage permissions, including deny rules set in managed settings.

Working directories

By default, Claude has access to files in the directory where it was launched. You can extend this access:

• During startup: use --add-dir <path> CLI argument
• During session: use /add-dir command
• Persistent configuration: add to additionalDirectories in settings files

Files in additional directories follow the same permission rules as the original working directory: they become readable without prompts, and file editing permissions follow the current permission mode.

How permissions interact with sandboxing

Permissions and sandboxing are complementary security layers:

• Permissions control which tools Claude Code can use and which files or domains it can access. They apply to all tools (Bash, Read, Edit, WebFetch, MCP, and others).
• Sandboxing provides OS-level enforcement that restricts the Bash tool's filesystem and network access. It applies only to Bash commands and their child processes.

Use both for defense-in-depth:

• Permission deny rules block Claude from even attempting to access restricted resources
• Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making
• Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration
• Network restrictions combine WebFetch permission rules with the sandbox's allowedDomains list

Managed settings

For organizations that need centralized control over Claude Code configuration, administrators can deploy managed settings that cannot be overridden by user or project settings. These policy settings follow the same format as regular settings files and can be delivered through MDM/OS-level policies, managed settings files, or server-managed settings. See settings files for delivery mechanisms and file locations.

Managed-only settings

Some settings are only effective in managed settings:

Settings precedence

Permission rules follow the same settings precedence as all other Claude Code settings:

1. Managed settings: cannot be overridden by any other level, including command line arguments
2. Command line arguments: temporary session overrides
3. Local project settings (.claude/settings.local.json)
4. Shared project settings (.claude/settings.json)
5. User settings (~/.claude/settings.json)

If a tool is denied at any level, no other level can allow it. For example, a managed settings deny cannot be overridden by --allowedTools, and --disallowedTools can add restrictions beyond what managed settings define.

If a permission is allowed in user settings but denied in project settings, the project setting takes precedence and the permission is blocked.

Example configurations

This repository includes starter settings configurations for common deployment scenarios. Use these as starting points and adjust them to fit your needs.

See also

• Settings: complete configuration reference including the permission settings table
• Sandboxing: OS-level filesystem and network isolation for Bash commands
• Authentication: set up user access to Claude Code
• Security: security safeguards and best practices
• Hooks: automate workflows and extend permission evaluation