What you will be able to do
- Choose the permission mode that fits a team workflow, from interactive review to a locked-down CI run
- Predict how deny rules, hooks, permission modes, allow rules and canUseTool combine to settle one tool call
- Configure a headless claude -p or Agent SDK run that has an exact allowlist and fails closed
- Define subagents whose tools, hooks and permission mode stay within the parent session's guardrails
Key concept
Permission evaluation order — Each tool call passes through a fixed chain: hooks, then deny rules, ask rules, the permission mode, allow rules, and finally the canUseTool callback. The first step that settles the call wins. A guardrail only holds if it sits in a step that runs before the permission mode approves the call.
1.Six permission modes and what each runs without asking
A permission mode decides which tool calls Claude Code runs on its own and which ones stop for a person. A team picks the mode by asking who will be watching. With an engineer at the keyboard, a prompt costs a few seconds. In CI nobody answers, so a prompt either hangs the job or has to be turned into a denial. The six modes range from approving almost nothing to approving everything.
| Mode | Runs without asking | Best for |
|---|---|---|
| default | Reads only | Reviewing every action yourself, sensitive work |
| acceptEdits | Reads, file edits, and common filesystem commands (mkdir, touch, mv, cp) | Iterating on code you're reviewing |
| plan | Reads, plus classifier-approved commands when auto mode is available | Exploring a codebase before changing it |
| auto | Everything, with background safety checks | Long tasks, reducing prompt fatigue |
| dontAsk | File reads in working directories and pre-approved tools; anything that would prompt is denied | Locked-down CI and scripts |
| bypassPermissions | Everything | Isolated containers and VMs only |
The two modes at the far end are easy to mix up. auto hands review to a classifier model. It approves or blocks each call it looks at, so nobody has to list tools in advance, but nobody controls exactly which calls get through either. bypassPermissions skips the checks entirely. It belongs only where the environment itself is disposable: a container, a VM, or the sandbox runtime, run as a non-root user on Linux and macOS. plan blocks edits until someone approves a plan. acceptEdits removes the edit prompts but still asks before other shell commands.
The starting mode comes from the first source that sets it. A --permission-mode flag (or --dangerously-skip-permissions) wins. Next is permissions.defaultMode in a settings file, and last is the built-in default. Where defaultMode lives decides its reach: ~/.claude/settings.json covers one person's machine, the project's .claude/settings.json covers one repository, and managed settings cover the whole organization. A repository cannot raise its own trust level, though. Auto and bypassPermissions do not take effect from project or local settings. For a team, the stronger controls are the two managed-settings switches. permissions.disableAutoMode set to "disable" removes auto mode so nobody can select it, and permissions.disableBypassPermissionsMode blocks bypassPermissions.
{
"permissions": {
"defaultMode": "default"
}
}Checkpoint 1 of 7· Match them up
Match each permission mode to what it runs without asking a person.
Tap a term, then the definition that fits it.
The modes differ in what they approve without a person and in what happens to everything else. dontAsk turns would-be prompts into denials, which suits locked-down CI. bypassPermissions skips checks entirely, so it belongs only in isolated environments.
“File reads inside your working directories and pre-approved tools; anything that would prompt is denied”Source: code.claude.com
Sources1
2.Headless runs and CI: allowlists that fail closed
Headless operation means running Claude Code with claude -p or driving it from the Agent SDK in Python or TypeScript. The prompt goes in as an argument or on stdin, and the result comes back on stdout. That makes it easy to pipe a diff in or wire Claude into an npm script. For scripts that parse the result, --output-format json returns structured JSON with the result, the session ID and metadata. --json-schema constrains the output to a schema you supply.
Both claude -p and the Agent SDK start in default mode, whatever a terminal session would use. In default mode, a call that needs approval goes to a human, or in the SDK to your canUseTool callback. When the SDK has no callback, the call is denied. A CI job that should never stall wants that denial to be deliberate and complete, and dontAsk provides it. Every call that would prompt is denied at once. Calls that need no approval still run, such as file reads in the working directories and the read-only command set, along with anything your --allowedTools entries or permissions.allow rules cover.
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};Allowlist entries come in two shapes. A bare name such as Read approves every call to that tool. A scoped rule such as Bash(npm test *) approves only the matching calls, and other Bash calls fall through to the permission mode. In CI the CLI equivalent is claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read". Three tempting alternatives each break the exact-list requirement. acceptEdits approves file writes and common filesystem commands without asking. auto lets a classifier decide what is risky. bypassPermissions runs tool calls you never listed. A few calls are denied under dontAsk even when an allow rule matches them: AskUserQuestion, MCP tools marked requiresUserInteraction, and reads from network paths.
Checkpoint 2 of 7· Check yourself
A nightly CI job runs claude -p with nobody watching. It may run npm test and read files, and every other call that needs approval must be refused at once instead of hanging the job. Which invocation meets that requirement?
dontAsk runs the calls on the allowlist and denies anything else that would prompt, so the list is exact and the job never stalls. bypassPermissions would also run tools that are not on the list. acceptEdits approves file writes without asking, and its remaining prompts would hang a job with nobody watching. auto leaves the decision to a classifier instead of a fixed list.
“dontAsk: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs”Source: code.claude.com
Checkpoint 3 of 7· Exam question
A platform team runs an Agent SDK job in CI with no human attached and no canUseTool callback. The agent should read the repository and run only the test and lint scripts; any other call that would need approval must fail immediately instead of waiting. Which configuration meets this?
Correct answer: A — Set permissionMode: "dontAsk" and allowedTools to Read, Grep, Glob and two scoped Bash(npm ...) rules; calls outside the list are denied with no prompt.
- A. Correct: in dontAsk mode a call that would normally prompt is denied straight away and no callback is needed. The scoped allow rules let only the read tools and the two npm scripts run, so the unattended CI job gets a fixed boundary and never stalls.
- B. Incorrect: bypassPermissions skips permission checks, and allowedTools does not narrow it. Bash commands and file writes outside the listed rules are approved too, so the job could run arbitrary commands instead of only the test and lint scripts.
- C. Incorrect: in auto mode a classifier model decides about unlisted actions, so a command it rates safe can still run. The job needs every call outside the list to be rejected deterministically, and a model's judgement does not provide that.
- D. Incorrect: acceptEdits approves file edits, but this job is meant to read and run only the test and lint scripts. It also leaves other prompts to the permission flow rather than turning them into immediate denials the way dontAsk does.
3.Where guardrails hold: hooks, deny rules and canUseTool
A guardrail survives a permissive mode only if it is checked before the mode approves the call. In the Agent SDK every tool call passes through these steps in order, and the first step that settles the call wins:
- Hooks, which run custom code that can allow, deny or modify the call.
- Deny rules.
- Ask rules.
- The permission mode.
- Allow rules.
- The
canUseToolcallback, used only when no earlier step settled the call.
Under bypassPermissions, two mechanisms enforce a hard limit. The first is a scoped deny rule passed through disallowedTools. Bash(rm *) keeps Bash available but denies matching calls in every permission mode, bypassPermissions included. A bare name such as Bash removes the tool definition from the request altogether. Deny rules also accept globs: "*" matches every tool and "mcp__*" matches every MCP tool. The second is a PreToolUse hook registered in the SDK options. It returns permissionDecision set to "deny", which can also be "allow", "ask" or "defer", and it can rewrite the input. Because hooks come first in the chain, they also see calls that bypassPermissions would approve. Logic first written for canUseTool belongs in a PreToolUse hook when the agent runs under bypassPermissions.
Two details decide whether a deny rule matches. The first is the path form. Edit(/secrets/**) matches the secrets directory inside the working directory, while Edit(//secrets/**) means /secrets on disk. The second is scope. A file-path deny rule blocks Claude's file tools and shell redirections such as tee and >. A script Claude runs that opens files itself can still write there, so OS-level enforcement needs the sandboxed Bash tool. An allowlist alone, such as allowedTools: ["Read", "Grep", "Glob"], restricts nothing under bypassPermissions, because that mode approves unlisted tools anyway. Least-privilege design in general is covered under least-privilege tool configuration.
Checkpoint 4 of 7· Check yourself
Under bypassPermissions in a disposable container, an SDK agent must keep using Bash for builds and tests, but rm commands must be refused. Which configuration does that?
Deny rules come before the permission mode in the chain. A scoped rule like Bash(rm *) blocks matching calls even under bypassPermissions, and Bash stays available for other commands. Under bypassPermissions an allowlist restricts nothing. A bare Bash deny removes the whole tool, which breaks the builds. canUseTool runs only after bypassPermissions has already approved the call.
“Bash stays available. Calls matching rm * as written are denied in every permission mode, including bypassPermissions.”Source: code.claude.com
Checkpoint 5 of 7· Exam question
A team runs the Agent SDK in a throwaway container with permissionMode: "bypassPermissions" to avoid stalls. Security now requires that the agent can never write under secrets/ in the working directory and can never run git push. Choose two.(Select 2)
Correct answers: A, B — Pass disallowedTools: ["Edit(/secrets/**)", "Bash(git push *)"] in the query() options to deny edits under secrets/ and git push commands.; Register a PreToolUse hook in the query() options that returns permissionDecision: "deny" for edits under secrets/ and git push commands.
- A. Correct: deny rules from disallowedTools are evaluated before the permission mode, so they still apply under bypassPermissions. A scoped Edit rule for secrets/ and a Bash rule for git push cover both prohibited actions.
- B. Correct: hooks run at the start of the evaluation order, and a deny returned by a PreToolUse hook blocks the call even in bypass mode. The hook can match edits under secrets/ and git push commands in code.
- C. Incorrect: allowedTools only pre-approves the listed tools; it does not limit what bypassPermissions approves. Write, Edit and Bash are still approved by the mode, so neither secrets/ nor git push is protected.
- D. Incorrect: canUseTool is consulted last, after the permission mode. Under bypassPermissions, Edit and Bash calls are approved at the mode step and never reach the callback, so its checks do not run for the writes and pushes that matter.
- E. Incorrect: a CLAUDE.md rule is context the model reads and may or may not follow; it is not an enforced control. A restriction that must never be broken needs a deny rule or a hook.
4.Subagent definitions and how their permission mode meets the parent's
A subagent is a named configuration with its own system prompt, tool set, model and optional hooks. Claude can delegate to it, or the whole session can run as it with --agent. Definitions are markdown files with YAML frontmatter, or JSON passed through --agents or the SDK agents option. When two definitions share a name, priority decides which one loads: managed settings first, then the --agents flag, then .claude/agents/ in the project, then ~/.claude/agents/, then a plugin's agents/ directory. Committing to .claude/agents/ is how a team shares one reviewer definition. Deciding how to split work across agents is a separate design question, covered in orchestrator and subagent decomposition.
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---tools is an allowlist. If it is omitted, the subagent inherits every tool available to subagents. disallowedTools removes tools from the inherited or listed set. In subagent frontmatter, an entry with a specifier such as Bash(git push *) still removes the whole tool, unlike a scoped SDK deny rule. Hooks can live in two places. Hooks in frontmatter run only while that subagent is active. Hooks in settings.json are session-wide, fire for the subagent's tool calls too, and add the SubagentStart and SubagentStop events. The validation script in the example blocks SQL writes by exiting with code 2. Plugin subagents ignore hooks, mcpServers and permissionMode, so a guardrail shipped in a plugin's agent file does nothing. How plugins are packaged is covered in plugin packaging and distribution.
A subagent's permissionMode applies only when the parent is in default or dontAsk mode. Even then, bypassPermissions is refused, and so is auto when auto mode isn't available to the subagent. When the parent runs bypassPermissions, acceptEdits or auto, the subagent runs in that same mode and its own setting is ignored. When the parent runs plan, the subagent stays in plan. In the Agent SDK, plan mode sends edits made with Claude's file tools to the canUseTool callback even when an allow rule matches them. The result is that a subagent asking for acceptEdits under a plan-mode parent cannot edit source files on its own. Each edit goes to the callback for a decision.
Checkpoint 6 of 7· Match them up
A team shares one set of subagent definitions, but each subagent can start under a parent session in a different mode. For each parent-and-subagent combination, pick the mode the subagent actually runs in.
Tap a term, then the definition that fits it.
A subagent's own permissionMode applies only when the parent is in default or dontAsk, and even then a request for bypassPermissions is refused. A parent in bypassPermissions, acceptEdits or auto passes its own mode to the subagent. A parent in plan keeps its subagents in plan.
“When the main conversation is in default or dontAsk mode, the subagent runs in the permission mode you set.”Source: code.claude.com
Checkpoint 7 of 7· Exam question
A tech lead runs an Agent SDK session in plan mode so that engineers review the plan before any source change. A subagent defined in agents sets permissionMode: "acceptEdits", and the lead worries it will edit source files before the plan is approved. What happens?
Correct answer: A — The subagent runs under the parent's plan mode, and its Edit and Write calls on source files are routed to the canUseTool callback for a decision.
- A. Correct: while the parent session is in plan mode, a subagent takes on that mode instead of its own definition's value. Handing work to a subagent therefore cannot bypass plan review, and its source-file Edit and Write calls still reach the canUseTool callback.
- B. Incorrect: a subagent's permissionMode does not override a parent running in plan mode. The definition's value only takes effect under a default or dontAsk parent, so these edits are not approved without reaching canUseTool.
- C. Incorrect: the SDK has no rule rejecting a subagent mode that is broader than the parent's. The configuration loads without error and the query starts; the definition's acceptEdits is just not applied while the parent is in plan mode.
- D. Incorrect: the subagent's own mode is not applied under a plan-mode parent, whatever allowedTools contains. Plan mode does not queue edits for later release either; the file edits are sent to the canUseTool callback.
Practise it for real
Run a headless Claude Code job that runs only the listed tools and denies everything else instead of prompting
1.Run claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read" in a repository with an npm test script.
Why: dontAsk turns every prompt into a denial, and the allowlist names exactly what may run.
You should see: The tests run, and the run finishes without waiting for input.
2.Run the same command again, but ask it to also commit the result with git.
Why: git commit is not on the allowlist, so under dontAsk it should be denied rather than prompting.
You should see: The git commit call is denied, and the run still exits instead of hanging.
3.Add --output-format json and pipe the output to jq -r '.result'.
Why: CI scripts need structured output with the result and session ID in order to act on the run.
You should see: Only the final text result is printed.
Stuck? Get a nudge
If the run stalls, check whether you dropped --permission-mode dontAsk. Without it, claude -p starts in default mode.
Sources
(6)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/permission-modesOfficial docs
“Isolated containers and VMs only”
↩︎ Six permission modes and what each runs without asking“Everything, with background safety checks”
↩︎ Six permission modes and what each runs without asking“Block bypassPermissions: set permissions.disableBypassPermissionsMode to”
↩︎ Six permission modes and what each runs without asking“Cloud sessions ignore dontAsk from settings files”
↩︎ Headless runs and CI: allowlists that fail closed“Block bypassPermissions: set permissions.disableBypassPermissionsMode to”
↩︎ Exam trap 4“Sessions you start in a terminal honor every value except auto and bypassPermissions”
↩︎ Prediction“File reads inside your working directories and pre-approved tools; anything that would prompt is denied”
↩︎ Checkpoint - 2.https://code.claude.com/docs/en/headlessOfficial docs
“dontAsk: Claude Code denies every call that would otherwise prompt, which is useful for locked-down CI runs”
↩︎ Headless runs and CI: allowlists that fail closed“Actions covered by your --allowedTools entries or permissions.allow rules also run.”
↩︎ Headless runs and CI: allowlists that fail closed“json: structured JSON with result, session ID, and metadata”
↩︎ Headless runs and CI: allowlists that fail closed - 3.https://code.claude.com/docs/en/agent-sdk/agent-loopOfficial docs
“no callback means deny”
↩︎ Headless runs and CI: allowlists that fail closed“Edits made with Claude’s file tools go to your canUseTool callback even when an allow rule matches them”
↩︎ Subagent definitions and how their permission mode meets the parent's“Runs tool calls without asking for approval, including calls to tools you didn’t list in allowedTools.”
↩︎ Exam trap 2 - 4.
“Calls matching rm * as written are denied in every permission mode, including bypassPermissions.”
↩︎ Where guardrails hold: hooks, deny rules and canUseTool“Edit(/secrets/**) matches the secrets directory inside the working directory.”
↩︎ Where guardrails hold: hooks, deny rules and canUseTool“Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules.”
↩︎ Key concept“To check the approved calls too, put your callback’s checks in a PreToolUse hook”
↩︎ Exam trap 1“Tool calls are approved before canUseTool is consulted”
↩︎ Prediction“Bash stays available. Calls matching rm * as written are denied in every permission mode, including bypassPermissions.”
↩︎ Checkpoint - 5.https://code.claude.com/docs/en/agent-sdk/hooksOfficial docs
“For PreToolUse hooks, this is where you set permissionDecision”
↩︎ Where guardrails hold: hooks, deny rules and canUseTool - 6.https://code.claude.com/docs/en/sub-agentsOfficial docs
“When the main conversation is in plan mode, the subagent stays in plan mode whichever permissionMode you set”
↩︎ Subagent definitions and how their permission mode meets the parent's“define session-wide hooks that also fire inside subagents”
↩︎ Subagent definitions and how their permission mode meets the parent's“An entry with a specifier, such as Bash(git push *), still removes the whole tool”
↩︎ Subagent definitions and how their permission mode meets the parent's“the subagent runs in that same mode and Claude Code ignores the permissionMode you set”
↩︎ Exam trap 3“When the main conversation is in default or dontAsk mode, the subagent runs in the permission mode you set.”
↩︎ Checkpoint