CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards· Lessons

    Domain 7 · Lesson 38/39

    Configuring Claude Code and the Agent SDK: permission modes, hooks, subagents and CI

    Agent SDK and Claude Code Configuration

    16 min read
    2.67% of exam
    6 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    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.

    What each permission mode runs without asking, and where it fits
    ModeRuns without askingBest for
    defaultReads onlyReviewing every action yourself, sensitive work
    acceptEditsReads, file edits, and common filesystem commands (mkdir, touch, mv, cp)Iterating on code you're reviewing
    planReads, plus classifier-approved commands when auto mode is availableExploring a codebase before changing it
    autoEverything, with background safety checksLong tasks, reducing prompt fatigue
    dontAskFile reads in working directories and pre-approved tools; anything that would prompt is deniedLocked-down CI and scripts
    bypassPermissionsEverythingIsolated 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.

    Setting the starting mode in a settings filejson
    {
      "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.

    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.

    An Agent SDK allowlist under dontAsk: these three tools run, and anything else that would prompt is deniedtypescript
    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?

    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?

    Sources231

    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:

    1. Hooks, which run custom code that can allow, deny or modify the call.
    2. Deny rules.
    3. Ask rules.
    4. The permission mode.
    5. Allow rules.
    6. The canUseTool callback, 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?

    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)

    0 of 2 selected

    Sources45

    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.

    A subagent with a scoped PreToolUse hook that validates every Bash callyaml
    ---
    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.

    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?

    Sources63

    Practise it for real

    Run a headless Claude Code job that runs only the listed tools and denies everything else instead of prompting

    1. 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. 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. 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. 1.
      “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. 2.
      “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. 3.
      “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. 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. 5.
      “For PreToolUse hooks, this is where you set permissionDecision”
      ↩︎ Where guardrails hold: hooks, deny rules and canUseTool
    6. 6.
      “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

    Ready to test yourself?

    Practise Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.