Skip to main content

Permission Flow

Before a tool runs, Claude Code decides one of three things: allow it, ask you, or deny it. Several parts take a turn: rules, hooks, the permission mode, safety checks, and sometimes a classifier model. This page shows the order and where you can act.

Example​

You set deny: ["Bash(git push:*)"] and allow: ["Bash(bun test)"]. You run in default mode.

  1. Claude asks to run git push origin main. The deny rule matches, so Claude Code denies the call. No prompt shows.
  2. Claude asks to run bun test. No deny or ask rule matches. The allow rule matches, so it runs.
  3. Claude asks to run rm -rf build. No rule matches. The mode is default, so you get a prompt.

The Order of Checks​

Official pages: Configure Permissions and Choose a Permission Mode. The docs do not give the full order. The steps below follow the program, so treat the exact order as unstable.

Step by Step​

  1. Explicit deny and ask rules apply first, before workspace trust. Source: the official Settings Reference.
  2. PreToolUse hooks can allow, deny, or ask. A hook allow does not override a deny or ask rule. Source: the Mod API type file of the 2.1.312 program (schemas/claude-code.d.ts) and the program text hook allows approve the command.
  3. Allow sources let the call run: allow rules, the rules of acceptEdits, and read-only command lists. Program texts: Read-only command is allowed and Auto-allowed with sandbox (autoAllowBashIfSandboxed enabled).
  4. The mode decides the rest. default prompts. dontAsk denies. auto asks the classifier. bypassPermissions allows. The other modes follow the rules on Permission Modes.
  5. A prompt runs PermissionRequest hooks first. Then the dialog shows. Notification hooks fire for unanswered requests in SDK hosts. CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1 stops that.
  6. An auto mode denial fires PermissionDenied. The hook can ask for a retry.

A safety check covers rm -r on a mounted drive, the folder that holds mounted drives (/Volumes, /media, WSL /mnt/c), or a top-level file or folder of a drive. Since 2.1.304 the program says it "requires explicit approval and cannot be auto-allowed by permission rules". CLAUDE_CODE_DISABLE_MOUNTED_DRIVE_RM_PROMPT turns this prompt off (Tools and Bash).

Claude Code also checks deny and ask rules at startup. It warns about a rule that matches no tool (matches no tool · check for typos). It also warns about a rule that gives a raw string where the tool needs its own matcher (never matches). Source: the program (chunk-ytgxgfq5.js:1100). Since 2.1.311, a warning about a rule from a settings file shows once per user until the rule changes. The program saves a key for each shown warning in the seenSecurityWarnings entry of the user config file (the last 256 keys), and the key holds the source, the settings file, and the warning text (chunk-ytgxgfq5.js:1174, chunk-5zvdwenv.js:16).

Built-in safety checks, called circuit breakers, can also force a prompt. Some are immune to bypassPermissions. See Permission Modes. The diagram omits them because the program does not show where they run.

The working folders matter too. A path outside the working folders gets the reason workingDir (Path is outside allowed working directories). permissions.blockReadsOutsideWorkingDirectories: true refuses reads outside the working folders in every mode.

What You Can Change at Each Step​

StepWhat you change
Rulespermissions.allow, ask, deny. See Permission Rules.
HooksPreToolUse, PermissionRequest, and PermissionDenied hooks. See the Hooks pages.
Safety checksMostly fixed. blockReadsOutsideWorkingDirectories, --restricted, and isolatePeerMachines enable some.
Modepermissions.defaultMode and --permission-mode. See Permission Modes.
Sandboxsandbox.* keys. See Sandbox.
ClassifierThe autoMode setting. See Auto Mode.

Where It Sits in a Turn​

The check runs in the tool stage of every turn. See The Agent Loop for the stages around it and Architecture for the pieces.