Permission Rules

A permission rule names a tool, and it can name a pattern for that tool. Three lists hold the rules. allow runs a call with no prompt. ask always prompts. deny blocks the call. For example, Bash(git push:*) in deny stops each git push command.

Add rules to permissions.allow, permissions.ask, or permissions.deny in a settings file. Or run /permissions. Or pass --allowedTools and --disallowedTools for one session. Remove a rule to turn it off. allowManagedPermissionRulesOnly turns off rules from every scope except managed settings.

Example

.claude/settings.json
{
  "permissions": {
    "allow": ["Bash(bun test)", "Bash(git diff *)", "Read(src/**)"],
    "ask": ["Bash(git commit *)"],
    "deny": ["Bash(git push:*)", "Read(.env)", "WebFetch"],
    "additionalDirectories": ["../shared-lib"]
  }
}

The `permissions` Keys

Lists from all scopes merge. Official pages: Configure Permissions and Choose a Permission Mode.

Item	Status	What it does	How it works	Where to set it
`permissions.allow`	Documented: An official docs page names this item.	List of rules for allowed operations	Lists from all scopes merge. Project `allow` rules wait for workspace trust. `allowManagedPermissionRulesOnly` limits them to managed settings	Each settings scope
`permissions.ask`	Documented: An official docs page names this item.	List of rules that always prompt	`ask` and `deny` rules apply at once, before trust. An `allow` rule in a local file does not outrank an `ask` rule from a project or managed file	Each settings scope
`permissions.deny`	Documented: An official docs page names this item.	List of rules for denied operations	A bare tool name hides the tool from the model. See Tools	Each settings scope
`permissions.defaultMode`	Documented: An official docs page names this item.	Default permission mode	`manual` is an alias of `default`. `auto` and `bypassPermissions` do not take effect from project or local settings	User, managed, `--settings`
`permissions.disableBypassPermissionsMode`	Documented: An official docs page names this item.	Value `disable` removes `bypassPermissions`	Claude Code checks it when a session starts in that mode or can return to it	Mainly managed settings
`permissions.blockReadsOutsideWorkingDirectories`	Documented: An official docs page names this item.	Refuses `Read`, `Grep`, `Glob`, and `LSP` reads outside the working directories in each mode	`true` from any scope wins, also over a managed `false`. Needs `2.1.257`	Each settings scope
`permissions.additionalDirectories`	Documented: An official docs page names this item.	Extra directories in the permission scope	Applies after workspace trust. `--add-dir` and `/add-dir` do the same for one session	Each settings scope
`permissions.disableAutoMode`	Documented: An official docs page names this item.	Value `disable` turns auto mode off	The reason text is `disableAutoMode in settings`. See Auto Mode	Settings, mainly managed

Item	Status	What it does	How it works	Where to set it
`allowManagedPermissionRulesOnly`	Documented: An official docs page names this item.	Only managed settings supply permission rules	Rules from other scopes are ignored with a notice that names this key. Since `2.1.305`, plugins that Claude Desktop mounts by path no longer keep their `allowed-tools` (v2.1.305 release)	Managed settings
`skipDangerousModePermissionPrompt`	Documented: An official docs page names this item.	The user accepted the bypass dialog	Boolean	User settings
`skipAutoPermissionPrompt`	Documented: An official docs page names this item.	The user accepted the auto mode opt-in dialog	Boolean	Settings
`useAutoModeDuringPlan`	Documented: An official docs page names this item.	Plan mode uses auto mode semantics when auto mode is available	The default is `true`. A `false` from managed, `--settings`, user, or local settings wins	Settings
`autoMode`	Documented: An official docs page names this item.	Classifier rules	See Auto Mode	User, `--settings`, managed
`sandbox`	Documented: An official docs page names this item.	Bash sandbox	See Sandbox	Each settings scope

Rule Syntax

A rule has the form Tool or Tool(content). The tool name is case-sensitive. The content has no space at its start or end inside the parentheses. Source: the program text tool name case-sensitive, non-empty content with no leading/trailing whitespace inside the parens.

Form	Status	What it matches	Notes
`Bash(bun test)`, `PowerShell(...)`	Documented: An official docs page names this item.	Shell commands by pattern.	`` is a wildcard. `\` is a literal star. A pattern that ends in a space and one star also matches the bare command.
`Bash(git push:*)`	Documented: An official docs page names this item.	The legacy prefix form.	The suffix `:` matches the prefix before it. Use `Bash(git push )` in new rules.
`Read(src/**)`, `Edit(...)`	Documented: An official docs page names this item.	Files by glob.	`**` crosses folders. A rule that starts with `/` anchors at the primary working folder.
`WebFetch(domain:example.com)`	Documented: An official docs page names this item.	One host.	Claude Code requires the prefix `domain:`. It allows `domain:*.example.com`. It rejects a full URL.
`WebSearch(terms)`	Documented: An official docs page names this item.	Exact search terms.	Claude Code rejects the wildcards `*` and `?`.
`mcp__server`, `mcp__server__tool`	Undocumented: Only the program shows this item. It can change without notice.	All tools of one MCP server, or one tool.	The program pattern is `^mcp__[\w-]+(?:__(?:[\w.-]+\|\*))?$`.
`Skill(name)`	Documented: An official docs page names this item.	One skill.	The program text is `Skill execution blocked by permission rules`.
`Bash` (no content)	Documented: An official docs page names this item.	The whole tool.	In `deny`, a bare tool name hides the tool from the model.

tip

Explicit deny and ask rules apply before allow rules. See Permission Flow.

Flags and Hooks That Touch Permissions

Item	Status	What it does	How it works	Where to set it
`--permission-mode <mode>`	Documented: An official docs page names this item.	Sets the mode for one session	Choices `acceptEdits`, `auto`, `bypassPermissions`, `manual`, `dontAsk`, `plan`	CLI
`--allowedTools`, `--disallowedTools`	Documented: An official docs page names this item.	Allow or deny tool rules for one session	Comma or space separated, such as `"Bash(git *) Edit"`	CLI
`--dangerously-skip-permissions`	Documented: An official docs page names this item.	Same as `--permission-mode bypassPermissions`	Use only in sandboxes with no internet	CLI
`--allow-dangerously-skip-permissions`	Documented: An official docs page names this item.	Makes bypass available without enabling it	You can choose the mode later	CLI
`--permission-prompts <host\|none>`	Documented: An official docs page names this item.	Who answers prompts with `--print`	`none` denies every prompt. The mode still decides the rest	CLI print mode
`--restricted`	Documented: An official docs page names this item.	Restricted mode	It refuses `bypassPermissions`. It confines file tools to the working directories. Env `CLAUDE_CODE_RESTRICTED=1`	CLI
`PermissionRequest` hook	Documented: An official docs page names this item.	Answers a prompt	Output `decision.behavior` is `allow` (with `updatedInput`, `updatedPermissions`) or `deny` (`message`, `interrupt`)	Hooks
`PermissionDenied` hook	Documented: An official docs page names this item.	Fires on an auto mode denial	Output `retry`	Hooks

Permission Updates

A PermissionUpdate changes rules or the mode. Hooks and SDK hosts send and receive them.

Field	Values
`type`	`addRules`, `replaceRules`, `removeRules`, `setMode`, `addDirectories`, `removeDirectories`
`destination`	`userSettings`, `projectSettings`, `localSettings`, `session`, `cliArg`
rule value	An object with `toolName` and `ruleContent`.

Source: PermissionUpdate in the Mod API type file of the 2.1.312 program (schemas/claude-code.d.ts).

How It Works

Permission Flow shows how Claude Code walks the lists, the hooks, and the mode.

Example​

The permissions Keys​

Related Top-Level Keys​

Rule Syntax​

Flags and Hooks That Touch Permissions​

Permission Updates​

How It Works​

Related Pages​

Example

The `permissions` Keys

Related Top-Level Keys

Rule Syntax

Flags and Hooks That Touch Permissions

Permission Updates

How It Works

Related Pages