Claude Code permissions explained: allow rules, modes and auto mode

Claude Code asks before it does most things that have side effects. That is the right default and the wrong permanent state: a session you supervise closely needs fewer prompts than the default gives, and a session you leave alone needs rules you have thought about. This guide explains how the permission system works, what the modes are, how to write allow, deny and ask rules, where they live, how hooks extend them, and when skipping permissions is and is not sane. It is checked against Anthropic's documentation as of October 2026.

How do Claude Code permissions work?

The permission system is tiered. In its manual mode (config value default), file reads and searches inside the working directory run without asking; shell commands, file edits, web fetches and web searches prompt you first, with a built-in set of read-only commands such as ls, cat, grep and read-only forms of git exempt. Each prompt shows what Claude is about to do and offers Yes, "Yes, and don't ask again", and No.

On top of the mode sit rules in three lists: allow, ask and deny. They are evaluated in that order reversed: deny first, then ask, then allow, and the first match decides. Specificity does not change the order, so Bash(aws *) in deny blocks aws s3 ls even if the narrower command is in allow. A deny from any settings file beats an allow from any other.

The principle the documentation states outright: "Permission rules are enforced by Claude Code, not by the model." Telling Claude in a prompt or a CLAUDE.md not to push to main shapes what it tries; only a rule, a mode or a hook changes what it is allowed to do.

What are the permission modes?

Press Shift+Tab in the terminal to cycle modes, or start with claude --permission-mode acceptEdits and the like. From version 2.1.283 auto mode is the built-in starting mode for interactive terminal and VS Code sessions; permissions.defaultMode in your user settings changes that. Rules layer on top of every mode: a deny blocks in all of them, including bypassPermissions, and an ask rule prompts in all of them, including auto.

How do allow, deny and ask rules work?

A rule is Tool or Tool(specifier). A bare tool name matches every use; as a deny it removes the tool from Claude's view entirely. The specifier narrows it, and its shape depends on the tool.

A working file looks like this, and it is what the documentation gives as the example: npm scripts and commits run silently, pushes are refused.

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

Compound commands are split on &&, ||, ;, | and newlines, and an allow rule must match each part, so Bash(npm run *) does not approve npm run build && rm -rf /. A deny or ask applies if any part matches, including inside a subshell. Common wrappers such as timeout, nice and nohup are stripped before matching.

Where do the rules live? settings.json scopes

Precedence for an ordinary key runs managed, then --settings on the command line, then project local, then shared project, then user. Permission rules are simpler than that: a deny anywhere wins, then an ask anywhere, then an allow. The practical consequence is that a project's shared deny protects every teammate's local allow from accidentally opening it, and a managed deny cannot be undone by --allowedTools.

Use /permissions inside a session to see every rule and which file it came from. Choosing "Yes, and don't ask again" on a Bash or WebFetch prompt writes the rule to the repository's .claude/settings.local.json; a file-edit approval lasts only until the session ends.

What a Bash rule does not match

A Bash rule matches the text Claude writes, not the program it runs. The documentation is candid that a deny "isn't a security boundary around the program". Bash(rm *) stops rm -rf build/ and does not stop /bin/rm -rf build/ or bash -c 'rm -rf build/'; Bash(git push *) stops git push origin main and not git -C . push origin main.

Two things close that gap. Sandboxing gives OS-level filesystem and network enforcement that holds even if a prompt injection steers the model; the documentation calls permissions and sandboxing "complementary security layers". And for anything a pattern cannot express, a hook can read the whole command. The same instinct applies anywhere a string is as good as money: a voucher code, an API key in .env, a push to main. Guard the thing, not the spelling of the request for it.

Hooks as a gate

A PreToolUse hook is a shell command that runs before every tool call, before the permission prompt. It receives the tool name and input as JSON on stdin and can allow, deny or force a prompt. Exit code 2 blocks the call, with stderr as the reason, and nothing the hook prints can override that. Exit 0 with a JSON object on stdout gives a decision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Pushes to main go through a pull request"
  }
}

Hooks live under the hooks key in any settings file, with a matcher such as "Bash" or "Edit|Write". Three properties make them a real gate rather than a suggestion: a blocking hook wins over an allow rule; a hook's "allow" does not override a deny or ask rule; and an rm aimed at a critical path such as your home directory is never approved by a hook or an allow rule in any mode.

The pattern the documentation suggests for a low-friction session is to allow Bash wholesale and register a hook that rejects the handful of commands you never want run.

When is skipping permissions sane, and when is it not?

--dangerously-skip-permissions starts a session in bypassPermissions mode: no prompts, no safety checks, including writes to protected paths such as .git and .claude. The documentation's instruction is unambiguous: "Only use this mode in isolated environments like containers, VMs, or dev containers without internet access, where Claude Code cannot damage your host system." It refuses to start as root or under sudo on Linux and macOS, and the first interactive use shows a dialog asking you to accept responsibility.

• Sane: claude -p "<prompt>" --dangerously-skip-permissions inside a throwaway container or the sandbox runtime, running as a non-root user, on a checkout you can discard.
• Sane: CI with an exact allowlist and no prompts: claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read". Anything else is denied, not asked.
• Sane: auto mode on your laptop for a long task whose direction you trust. A separate classifier reviews shell commands and network requests and blocks anything that escalates beyond your request or looks driven by hostile content Claude read; your ask rules still prompt. The documentation adds that it "reduces permission prompts but does not guarantee safety".
• Not sane: bypass mode on your own machine, with your credentials, your home directory and your network, because the prompts were annoying. The gate is the safety feature; the fix for annoying prompts is better rules and a cheaper way to answer the ones that remain.

Cloud sessions ignore bypassPermissions and dontAsk from checked-in settings, so a repository cannot start a cloud session in bypass mode.

Answering the prompts that remain

Once reads, tests, commits and your docs domains are allowed, the prompts left are the ones worth a human: a push, an install, a write outside the project, a command the rules do not describe. The question is how to answer them without sitting at the terminal. Anthropic's Remote Control forwards them to the Claude app on your phone and can push a notification when "actions required"; setting it up is a one-line command.

PeakWatch puts the same prompt on an Apple Watch or a Wear OS watch, with the tool, its arguments and the SDK's reason on screen, Allow, Deny and Say why one tap away, and an automatic deny after sixty seconds so an unanswered ask is never a yes. It never auto-approves; Always covers a tool for the rest of a session once you have decided it is safe. It is in private beta.

Together with the habits that make long sessions safe to leave, that is a permission setup you can walk away from.

Hen Eytan · Founder, UPeak

Builds the UPeak apps and writes up the research behind them.