Configure permissions - Claude Code Docs [proxy]

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:

Tool type	Example	Approval required	”Yes, don’t ask again” behavior
Read-only	File reads, Grep	No	N/A
Bash commands	Shell execution	Yes	Permanently per project directory and command
File modification	Edit/write files	Yes	Until session end

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:

Mode	Description
`default`	Standard behavior: prompts for permission on first use of each tool
`acceptEdits`	Automatically accepts file edit permissions for the session
`plan`	Plan Mode: Claude can analyze but not modify files or execute commands
`dontAsk`	Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules
`bypassPermissions`	Skips all permission prompts (requires safe environment, see warning below)

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:

Rule	Effect
`Bash`	Matches all Bash commands
`WebFetch`	Matches all web fetch requests
`Read`	Matches all file reads

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:

Rule	Effect
`Bash(npm run build)`	Matches the exact command `npm run build`
`Read(./.env)`	Matches reading the `.env` file in the current directory
`WebFetch(domain:example.com)`	Matches fetch requests to example.com

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.

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:

Pattern	Meaning	Example	Matches
`//path`	Absolute path from filesystem root	`Read(//Users/alice/secrets/**)`	`/Users/alice/secrets/**`
`~/path`	Path from home directory	`Read(~/Documents/*.pdf)`	`/Users/alice/Documents/*.pdf`
`/path`	Path relative to project root	`Edit(/src/*/.ts)`	`<project root>/src/*/.ts`
`path` or `./path`	Path relative to current directory	`Read(*.env)`	`<cwd>/*.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 system, and the hook output can determine whether to approve or deny the tool call in place of the permission system.

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:

Setting	Description
`disableBypassPermissionsMode`	Set to `"disable"` to prevent `bypassPermissions` mode and the `--dangerously-skip-permissions` flag
`allowManagedPermissionRulesOnly`	When `true`, prevents user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply
`allowManagedHooksOnly`	When `true`, prevents loading of user, project, and plugin hooks. Only managed hooks and SDK hooks are allowed
`allowManagedMcpServersOnly`	When `true`, only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. See Managed MCP configuration
`blockedMarketplaces`	Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See managed marketplace restrictions
`sandbox.network.allowManagedDomainsOnly`	When `true`, only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Denied domains still merge from all sources
`strictKnownMarketplaces`	Controls which plugin marketplaces users can add. See managed marketplace restrictions
`allow_remote_sessions`	When `true`, allows users to start Remote Control and web sessions. Defaults to `true`. Set to `false` to prevent remote session access

Settings precedence

Permission rules follow the same settings precedence as all other Claude Code settings: managed settings have the highest precedence, followed by command line arguments, local project, shared project, and user settings. 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.

Configure permissions - Claude Code Docs