Configure permissions

​

Permission system

​

Add a comment when you answer a permission prompt

• 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.

• 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

• 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.

​

Permission modes

​

Permission rule syntax

​

Match all uses of a tool

​

Use specifiers for fine-grained control

​

Match by input parameter

• 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
• A Skill(skill:<name>) deny rule instead matches the skill under any of its names, such as its alias or display name
• Run with --verbose to see the exact parameter names and values in each tool call
• Whitespace around the colon is ignored

​

Wildcard patterns

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

• 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.

​

Tool name wildcards

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

​

Tool-specific permission rules

​

Bash

​

Compound commands

​

Wrappers

​

Exec wrappers and find actions

• Exec wrappers: such as watch, setsid, ionice, and flock
• find: with an action that runs commands, deletes files, or writes files, such as -exec, -delete, or -fprint, or with -files0-from, which takes the paths to search from a file

​

What a Bash rule doesn’t match

​

Read-only commands

• 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.
• ps that could print environment variables: ps prompts when one of its arguments could act as the e option, such as in ps auxe or ps aux -e, because that option prints process environment variables. ps aux and ps -ef run without a prompt. The check on dashed forms such as ps aux -e requires Claude Code v2.1.290 or later.
• 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.
• Writes to special shell variables: a command that sets, unsets, or loops over certain special shell variables, such as PATH or IFS, prompts even when the rest of the command is read-only.
• 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.

• 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.

​

Redirections

• Output redirects: for > file, >> file, or 2> file, the check covers your Edit allow and deny rules, protected paths, and the working directories. A rule such as Bash(git commit *) allows the command, not the target. A target that starts with ~ or contains a glob character needs your approval.
• Input redirects: for < file, the check covers your Read allow and deny rules and the working directories. A target outside the working directories needs your approval unless an allow rule covers it. A target that contains a glob pattern, or a relative path that follows a cd in the same command, needs your approval even when an allow rule covers it. Claude Code checks input targets in v2.1.257 and later.

​

PowerShell

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

​

Read and Edit

• Image path: when you paste an image’s path or drag an image file into your prompt in the terminal and the rule matches that path, Claude Code doesn’t attach the image. If the paste holds no other image, the path stays in your prompt as text.
• Directory: the listing Claude receives leaves out the file and directory names the rule matches.

• Edit(/docs/**): edits in <primary working directory>/docs/, not /docs/ or <primary working directory>/.claude/docs/
• Read(~/.zshrc): reads your home directory’s .zshrc
• Edit(//tmp/scratch.txt): edits the absolute path /tmp/scratch.txt
• Read(src/**): as an allow rule, reads from <current-directory>/src/ only; as a deny or ask rule, matches a src directory at any depth under the current directory

• Allow rules: Edit(src/**) matches only <cwd>/src and the files under it. To allow a directory name at any depth, write Edit(**/src/**).
• Deny and ask rules: Read(secrets/**) matches a directory named secrets at any depth under the current directory, so the rule also applies to nested copies.

<current-directory>/
├── src/
│   └── app.ts