Claude Code permissions

Outside the box · General

The concept

Claude Code reads settings from several files. Highest first, they are an organization's managed settings, JSON passed with --settings on the command line, your uncommitted .claude/settings.local.json, the project's committed .claude/settings.json, and your user file ~/.claude/settings.json. A key set higher overrides the same key lower down, but a list such as permissions.allow merges across the files. A cloud session reads fewer of them, as Cloud sessions shows. Besides permissions, a settings file can set env variables and hooks.

Permission rules name a tool, optionally narrowed to a command or path:

{
  "permissions": {
    "allow": ["Bash(npm test *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"]
  }
}

An allow rule lets a call run without a prompt, ask always prompts, and deny blocks. Claude Code checks deny first, then ask, then allow, and the first match decides, so a narrow allow can't carve an exception out of a broad deny, and a deny in any file blocks what another file allows. A project's allow rules apply only once you accept the folder's trust dialog; its deny and ask rules apply at once, since they only restrict.

The permission mode sets what happens to a call no rule settles. default prompts on the first use of each tool; acceptEdits also accepts file edits and common file commands inside the working directory; plan explores without editing; auto has a classifier model check each action instead of asking; dontAsk denies whatever would prompt; and bypassPermissions skips prompts, where allow rules have no effect but a deny still blocks and an ask rule still prompts. defaultMode in a settings file sets the mode a session starts in.

Writes to Claude Code's protected paths, such as .git, .vscode, .mcp.json and most of .claude, are never auto-approved, except in bypassPermissions and in some interactive plan-mode sessions. No allow rule changes that: the safety check runs before the allow rules, so an Edit(.claude/**) entry does nothing. What happens instead depends on the mode: default and acceptEdits prompt, auto sends the write to the classifier, and dontAsk denies it.

A PreToolUse hook runs before the rules and can deny a call, force a prompt or let it run. A hook that blocks stops the call even when an allow rule matches it, but a hook's allow never skips a deny or ask rule; Blocking hooks shows such a hook.

Full referenceClaude Code docs: Configure permissions