Configure permissions

Claude Code supports fine-grained permissions so that you can specify exactly what the agent is allowed to do and what it can’t. You can check permission settings into version control to share them with every developer in your organization, and each developer can customize their own.

Permission system

Claude Code uses a tiered permission system to balance power and safety. The table shows, for each tool type, whether Manual mode asks before the action runs. The other permission modes change which of these ask you; in auto mode a classifier reviews actions instead of you, and how the classifier evaluates actions lists which ones it sees.

Tool type	Example	Approval required	”Yes, and don’t ask again” behavior
Read-only	File reads, Grep	No, within the working directory and additional directories	N/A
Bash commands	Shell execution	Yes, except a built-in set of read-only commands	Permanently per repository and command
File modification	Edit/write files	Yes	Until session end
Web fetch	WebFetch	Yes, except a built-in set of preapproved documentation domains	Permanently per repository and domain
Web search	WebSearch	Yes	Permanently per repository

When you choose “Yes, and don’t ask again” and the approval saves permanently, such as for a Bash command or a WebFetch domain, Claude Code saves the rule to .claude/settings.local.json at the root of the git repository, resolved through worktrees to the main checkout. The rule applies to future sessions anywhere in that repository, including sessions started in subdirectories and in worktrees. A file-modification approval isn’t saved to the file: as the table shows, it lasts until the session ends. In some cases, such as outside a git repository or on Windows, Claude Code doesn’t use the repository root; Where Claude Code looks for each file lists those cases and where it saves the rule instead. Before v2.1.211, Claude Code always saved the rule in the starting directory, so an approval granted in a worktree or subdirectory didn’t apply to the rest of the repository. Rules that earlier versions saved in a subdirectory or worktree still apply to sessions started there. Sometimes a permission prompt offers only a one-time approval, with no “don’t ask again” option and no option to allow the action for the rest of the session. Claude Code offers those options only when the prompt can show you everything they would allow, so a rule you save from a prompt covers only what its option named. When the directory you started Claude Code in is what makes the option’s label too long, Claude Code shortens it in the label, replacing your home directory with ~ and then the end of the path with …, and keeps the option. You still save the same rule. Claude Code leaves the options out in three cases:

Command or edit: too large to show in full.
Commands or paths the rule would cover: the label can’t fit them all.
Starting directory too long, not shortened: it contains characters Claude Code can’t display safely, or even its start doesn’t fit.

Approve the action once, or add the rule yourself in /permissions.

Add a comment when you answer a permission prompt

You can attach a note to Claude when you approve or deny a single action. On most permission prompts, including Bash, PowerShell, file, and MCP tool prompts, move to Yes or No and press Tab to open a comment field on that option. WebFetch and browser prompts don’t offer the field. The options that allow the action for the rest of the session or save a rule don’t take one either. With the field open, type the comment and then press one of these keys:

Enter: submits your answer with the comment attached. If you leave the field empty, Claude Code submits the answer without a comment.
Tab: closes the field without answering. Claude Code keeps the text you typed and still sends it if you answer with that option.
Shift+Tab: on a file prompt, such as an Edit or Write prompt, closes the field the same as Tab. Before v2.1.235, pressing Shift+Tab inside the field instead selected the option that allows the action for the rest of the session, so Claude Code approved the action for the rest of the session and discarded the comment.

Claude Code delivers the comment differently depending on how you answered:

Yes: Claude Code runs the action, then sends your comment to Claude after the result.
No: Claude Code sends your comment to Claude as the reason for the denial, and Claude continues working. If you select No without a comment on a prompt from the main conversation, Claude Code stops the turn.

Manage permissions

You can view and manage Claude Code’s tool permissions with /permissions. The dialog lists all permission rules and the settings.json file each rule comes from. You can open the dialog while Claude is working: when you add or remove a rule, Claude Code applies the change starting with Claude’s next tool call in the same turn. Before v2.1.234, Claude Code queued the command until the turn finished.

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, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn’t change the order. A broad deny rule like Bash(aws *) blocks every matching call, including calls that also match a narrower allow rule like Bash(aws s3 ls), so a deny rule can’t carry allowlist exceptions. The same precedence applies between ask and allow: a matching ask rule prompts even when a more specific allow rule also matches the same call. Deny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like Bash removes the tool from Claude’s context entirely, so Claude never sees it. Bare-name removal applies to every tool except EndConversation: a deny rule can’t remove it while any other tool remains, and an ask rule never prompts for it. A scoped rule like Bash(rm *) leaves the tool available and blocks matching calls when Claude attempts them.

Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or CLAUDE.md shape what Claude tries to do, but they don’t change what Claude Code allows. To grant or revoke access, use /permissions, the rules described here, a permission mode, or a PreToolUse hook.

When auto mode is available to your session, the dialog also includes the auto mode classifier rules. Select the Auto mode tab to view them.

Permission modes

Claude Code supports several permission modes that control how it approves tool calls. See Permission modes for when to use each one. To change the mode sessions start in, set defaultMode in your settings files. Which mode a session starts in covers the built-in default for each plan and what the VS Code extension reads.

Mode	Description
`default`	Prompts for permission on first use of each tool. Labeled Manual in the CLI, the VS Code and JetBrains extensions, and the desktop app, and Claude Code accepts `manual` as an alias. The label and alias require Claude Code v2.1.200 or later. The desktop app’s label doesn’t depend on your CLI version
`acceptEdits`	Automatically accepts file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, and `cp` for paths in the working directory or `additionalDirectories`
`plan`	Claude reads files and runs read-only shell commands to explore but doesn’t edit your source files; with auto mode available, classifier-approved commands also run. Labeled Plan in the CLI and the VS Code extension
`auto`	Auto-approves tool calls with background safety checks that verify actions align with your request
`dontAsk`	Auto-denies every call that would otherwise prompt; file reads in your working directories and other actions that need no approval still run, as do tools pre-approved via `/permissions` or `permissions.allow` rules. `AskUserQuestion`, MCP tools marked `requiresUserInteraction`, and connector tools your organization set to `ask` in sessions where that setting reaches Claude Code are denied even if you’ve allowed them
`bypassPermissions`	Skips permission prompts, except for the actions no mode auto-approves

In bypassPermissions mode, Claude Code skips permission prompts, including for writes to protected paths such as .git and .claude. The cross-session messaging safeguards still apply. Only use this mode in isolated environments like containers or VMs where Claude Code can’t cause damage.

To prevent bypassPermissions or auto mode from being used, set permissions.disableBypassPermissionsMode or permissions.disableAutoMode to "disable" in any settings file. These are most useful in managed settings where they can’t be overridden.

Permission rule syntax

Permission rules follow the format Tool or Tool(specifier). Parentheses inside the specifier are literal, so a command or path that contains them needs no escaping.

Match all uses of a tool

To match all uses of a tool, use only 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. As a deny rule, both forms remove the tool from Claude’s context.

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

Match by input parameter

Deny and ask rules can match a top-level input parameter on any built-in tool with Tool(param:value). To match a parameter on an MCP tool, pass a deny rule with --disallowedTools. When Claude Code loads a settings file, it skips any mcp__ rule that has parentheses. Claude Code lists the skipped rule in the invalid-settings dialog when an interactive session starts, and in claude doctor output. A parameter rule matches when Claude calls the tool with that parameter set to that exact value. An allow rule for one parameter value wouldn’t establish that the call is safe overall, so allow rules continue to use each tool’s own specifier syntax. This works for any scalar parameter the tool accepts:

Rule	Matches
`Agent(model:opus)`	Agent calls that request the Opus model tier
`Agent(isolation:worktree)`	Agent calls that request a git worktree
`Bash(run_in_background:true)`	Bash calls that run in the background

Parameter matching follows these rules:

The parameter name must be a direct field of the tool’s input, such as model on the Agent tool. Fields nested inside an object or array are not matchable
Each rule names one parameter. To gate on both model and isolation, write two rules, Agent(model:opus) and Agent(isolation:worktree), rather than combining them in one rule
The value supports * as a wildcard that matches any sequence of characters, so Agent(isolation:*) matches any explicit isolation value. Without * the match is exact
A parameter the model omits is never matched, so Agent(model:*) doesn’t match a call that leaves model unset
The value is compared against the literal input Claude sends, before any normalization. Agent(model:opus) matches the alias opus but not a full model ID. Run with --verbose to see the exact parameter names and values in each tool call
Whitespace around the colon is ignored

You can’t match a tool’s primary content field this way: command for Bash and PowerShell, file_path for Read, Edit, and Write, path for Grep and Glob, notebook_path for NotebookEdit, and url for WebFetch. A rule like Bash(command:rm *) would be bypassable by a compound command, so Claude Code ignores it and emits a startup warning. Use Bash(rm *), Read(./path), or WebFetch(domain:host) instead.

Wildcard patterns

A * in a Bash rule matches any text, including spaces, so one rule covers a family of commands. A rule with no * matches one exact command.

Put the * after the subcommand. In git log --oneline main, git is the program and log is the subcommand, the word that determines what the program does. Claude Code matches everything before the first * as written, so those words are what limit the rule: Bash(git log *) allows only git log commands, and Bash(git *) allows every git command. Claude Code warns at startup about an allow rule with a * before the subcommand, such as Bash(git * main).

Write the command you want Claude to run without asking, and replace the parts that vary with *. With this configuration, Claude Code runs npm scripts and git commits without asking and refuses commands that begin with git push. A push written another way, such as git -C . push, isn’t matched; see what a Bash rule doesn’t match.

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

A * can go anywhere in the rule: at the start, in the middle, or at the end. Each row shows a rule, commands it matches, and nearby commands it doesn’t match:

You write	Matches	Doesn’t match
`Bash(npm run build)`	`npm run build`	`npm run build --watch`
`Bash(npm run *)`	`npm run build`, `npm run test --watch`, `npm run`	`npm install`
`Bash(git log * main)`	`git log --oneline main`, `git log -5 main`, `git log --output=<file> main`	`git log main`, `git push origin main`
`Bash(git * main)`	`git merge main`, `git push origin main`, `git -c core.fsmonitor=<script> diff main`	`git log`
`Bash(* --version)`	`node --version`, `bash -c 'echo hi' --version`	`node -v`
`Bash(ls *)`	`ls -la`, `ls`	`lsof`
`Bash(ls*)`	`ls -la`, `lsof`
`Bash(* --help *)`	`npm --help x`	`npm --help`

Three matching rules produce those rows:

The * stands in for whatever text is in its place. In Bash(git * main), it stands in for the subcommand, so Claude Code matches every git subcommand and every option before it. That includes -c, which makes git run a program you name. In Bash(* --version), the * stands in for the program, so any program matches.
A * at the end, with a space before it, also matches the bare command. Bash(ls *) matches ls, and Bash(git log *) matches git log. That holds only when the trailing * is the rule’s only wildcard: Bash(* --help *) matches npm --help x but not npm --help.
The space before a trailing * is part of the rule. Bash(ls *) requires a space after ls, so lsof doesn’t match. Bash(ls*) has no space, so it matches lsof too.

The :* suffix is an equivalent way to write a trailing wildcard, so Bash(ls:*) matches the same commands as Bash(ls *). The permission dialog writes the space-separated form when you select “Yes, and don’t ask again” for a command prefix. The :* form is only recognized at the end of a pattern. In a pattern like Bash(git:* push), the colon is treated as a literal character and won’t match git commands.

Tool name wildcards

Deny and ask rules also accept glob patterns in the tool-name position. The pattern must match the full tool name: "*" matches every tool, and "mcp__*" matches every MCP tool across all servers. A tool matched by a bare-name glob deny rule is removed from Claude’s context, the same as a bare tool name, including the EndConversation exception: a glob deny can’t remove it while any other tool remains, and a glob ask never prompts for it. This configuration denies every MCP tool:

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

Allow rules accept tool-name globs only after a literal mcp__<server>__ prefix. The server segment must be glob-free so the rule names a specific server you configured. mcp__puppeteer__* matches every tool from the puppeteer server, and mcp__github__get_* matches its get_ tools. An unanchored allow glob such as "*", "B*", or "mcp__*" is skipped with a warning and doesn’t auto-approve anything. A deny or ask rule whose tool name matches no known tool produces a startup warning to catch typos. Tool names containing _ or * are exempt from the check. The label shown for a tool in the transcript and permission dialog can differ from its canonical name. For example, the tool labeled Stop Task in the transcript has the canonical name TaskStop. Permission rules and hook matchers don’t match the label, so a rule written as Stop Task doesn’t match. For deny and ask rules, the startup warning above catches the mismatch. Use the canonical names listed in the tools reference.

Tool-specific permission rules

Bash

Bash rules match the whole command text, with * standing in for any text. Wildcard patterns shows which commands each rule shape matches and where to put the *. The rest of this section covers how Claude Code matches compound commands and wrappers, what a rule doesn’t match, read-only commands, and redirections.

Compound commands

Claude Code is aware of shell operators, so a rule like Bash(safe-cmd *) won’t give it permission to run the command safe-cmd && other-cmd. The recognized command separators are &&, ||, ;, |, |&, &, and newlines. A rule must match each subcommand independently.

Deny and ask rules apply when any subcommand matches them, including a command nested inside a subshell, a command substitution, or a control-flow body such as a for loop. An ask rule like Bash(git clean *) still prompts you for cd /tmp && git clean -f or echo "$(git clean -f)", even in auto mode. When && or || has nothing after it, such as in npm test &&, Claude Code treats the command as unparseable and doesn’t split it into subcommands for allow-rule matching, so a rule such as Bash(npm *) doesn’t approve it. When you approve a compound command with “Yes, and 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.

Wrappers

Before matching Bash rules, Claude Code strips a fixed set of wrappers, so a rule like Bash(npm test *) also matches timeout 30 npm test. The stripped wrappers are timeout, time, nice, nohup, and stdbuf, plus the shell builtins command and builtin, and zsh’s noglob. Each runs its argument as the actual command. Two related forms aren’t stripped: the query form command -v, which looks up a command rather than running one, and zsh’s nocorrect. Claude Code also strips a leading assignment of certain known-safe environment variables, so Bash(npm test *) matches NODE_ENV=test npm test. An allow rule won’t match past an assignment of any other variable. A deny or ask rule matches past any leading assignment, so Bash(rm *) in deny still matches FOO=bar rm -rf tmp/. Bare xargs is also stripped, so Bash(grep *) matches xargs grep pattern. Stripping applies only when xargs has no flags: an invocation like xargs -n1 grep pattern is matched as an xargs command, so rules written for the inner command do not cover it. This wrapper list is built in and is not configurable. Development environment runners such as direnv exec, devbox run, mise exec, npx, and docker exec are not in the list. Because these tools execute their arguments as a command, a rule like Bash(devbox run *) matches whatever comes after run, including devbox run rm -rf .. To approve work inside an environment runner, write a specific rule that includes both the runner and the inner command, such as Bash(devbox run npm test). Add one rule per inner command you want to allow. Exec wrappers such as watch, setsid, ionice, and flock can’t be auto-approved by a prefix rule like Bash(watch *), so in Manual mode they always prompt. The same applies to find with -exec or -delete: a Bash(find *) rule doesn’t cover these forms. To approve a specific invocation, write an exact-match rule for the full command string.

What a Bash rule doesn’t match

A Bash rule matches the command text Claude writes, after Claude Code splits compound commands and strips wrappers. It doesn’t match the same program invoked in a different form, so a deny or ask rule covers the invocation Claude usually produces and isn’t a security boundary around the program. These rules in deny or ask stop the first form and not the others:

Rule	Stops	Doesn’t stop
`Bash(curl *)`	`curl https://example.com`	`/usr/bin/curl https://example.com`, `sh -c 'curl https://example.com'`
`Bash(rm *)`	`rm -rf build/`	`/bin/rm -rf build/`, `bash -c 'rm -rf build/'`
`Bash(git push *)`	`git push origin main`	`git -C . push origin main`, `git -c push.default=current push origin main`, `git 'push' origin main`

Your other rules and the permission mode decide the commands in the last column. For filesystem and network enforcement that doesn’t depend on the command text, use sandboxing. To inspect the full command text with your own logic before it runs, use a PreToolUse hook.

Read-only commands

Claude Code recognizes a built-in set of Bash commands as read-only and runs them without a permission prompt in every mode, except for a path that permissions.blockReadsOutsideWorkingDirectories fences. The set includes ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, and read-only forms of git. The set is not configurable; to require a prompt for one of these commands, add an ask or deny rule for it. A redirect such as ls > out.txt adds a check on the target. See Redirections. Unquoted glob patterns are permitted for commands whose every flag is read-only, so ls *.ts and wc -l src/*.py run without a prompt. In Manual mode, commands from this set still prompt in these cases:

Unquoted globs for commands with write-capable flags: commands with write-capable or exec-capable flags, such as find, sort, sed, and git, prompt when an unquoted glob is present, because the glob could expand to a flag like -delete.
docker pointed at another daemon: read-only forms of docker prompt when the command carries a flag that selects a different daemon, such as -H, --context, or Podman’s --url and --connection.
file with path-opening flags: file prompts when it passes -m/--magic-file or -f/--files-from, because those flags make file open the paths named in the flag’s value.
Network paths on Windows: a command whose arguments include a network (UNC) path, such as \\server\share\file, prompts because accessing a network path can send your Windows credentials to the host it names. The same check applies to PowerShell tool commands.
Commands the analysis can’t parse: when Claude Code can’t fully parse a command, it asks for approval instead of treating the command as read-only. Commands longer than 10,000 characters always prompt because they exceed what the analysis parses.

A cd into a path inside your working directory or an additional directory is also read-only, and a compound command like cd packages/api && ls runs without a prompt when each part qualifies on its own. These combinations prompt even when each part is read-only:

cd with git: prompts when the cd changes into a different directory, since running git in a new directory can execute that directory’s hooks. A cd whose target resolves to the current working directory is a no-op and doesn’t trigger the prompt.
cd with a redirect: prompts when Claude Code can’t determine which directory the redirect target resolves against after the cd runs. A command whose only redirect target is /dev/null, such as cd app; grep -r pattern . 2>/dev/null, doesn’t prompt, because /dev/null doesn’t depend on the working directory.

Bash permission patterns that try to constrain command arguments are fragile. For example, Bash(curl http://github.com/ *) intends to restrict curl to GitHub URLs, but won’t match variations like:

Options before URL: curl -X GET http://github.com/...
Different protocol: curl https://github.com/...
Redirects: curl -L http://short.example.com/xyz, which redirects to GitHub
Variables: URL=http://github.com && curl $URL

For more reliable URL filtering, consider:

Restrict Bash network tools: use deny rules to stop curl, wget, and similar commands, then use the WebFetch tool with WebFetch(domain:github.com) permission for allowed domains. A deny rule doesn’t match the same program by path or inside sh -c, so pair it with the sandbox network allowlist when the restriction must hold; see

Settings

Permissions and sandboxing

Environments

Model and responses

Interface

Permission system

Add a comment when you answer a permission prompt

Manage permissions

Permission modes

Permission rule syntax

Match all uses of a tool

Use specifiers for fine-grained control

Match by input parameter

Wildcard patterns

Tool name wildcards

Tool-specific permission rules

Bash

Compound commands

Wrappers

What a Bash rule doesn’t match

Read-only commands

​Permission system

​Add a comment when you answer a permission prompt

​Manage permissions

​Permission modes

​Permission rule syntax

​Match all uses of a tool

​Use specifiers for fine-grained control

​Match by input parameter

​Wildcard patterns

​Tool name wildcards

​Tool-specific permission rules

​Bash

​Compound commands

​Wrappers

​What a Bash rule doesn’t match

​Read-only commands

Permission system

Add a comment when you answer a permission prompt

Manage permissions

Permission modes

Permission rule syntax

Match all uses of a tool

Use specifiers for fine-grained control

Match by input parameter

Wildcard patterns

Tool name wildcards

Tool-specific permission rules

Bash

Compound commands

Wrappers

What a Bash rule doesn’t match

Read-only commands