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

    Domain 5 · Lesson 31/39

    Human-in-the-loop approval gates for agent tool calls

    Human-in-the-Loop Checkpoints

    17 min read
    2.67% of exam
    7 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Decide which tool calls in an agent workflow need a human checkpoint and which should run without one
    • Configure an Agent SDK agent so read-only tools are pre-approved and consequential tools pause for a reviewer through canUseTool
    • Sequence permission modes so a plan is approved first and only the out-of-scope command still prompts
    • Gate an irreversible step in a headless run without stalling the unattended stages before it
    • Set always_ask, always_allow and auto policies per tool in Managed Agents and handle the paused session

    Key concept

    Per-call approval gate — A checkpoint attached to specific tool calls, not to the whole session. Irreversible or external-facing calls pause until a human allows or denies them. Every other call is pre-approved so it never waits on a person.

    1.Where a checkpoint belongs

    A human-in-the-loop checkpoint is a point where an agent's tool call stops and waits for a person to allow or deny it. It earns its cost at calls whose effects cannot be taken back or that reach outside your system: a refund, an email to a customer, a dropped table, a schema change on shared staging. Reads, searches and edits that a reviewer will see in a diff anyway gain nothing from a pause. Making them wait only teaches reviewers to click through prompts.

    Gates can fail in two ways. A missing gate lets one bad call do permanent damage. A gate on everything stalls the safe work and buries the one prompt that matters among dozens that don't. Deciding which actions count as high-stakes is the job of risk assessment and ranking. This lesson is about placing the gate exactly where that ranking points, and nowhere else.

    Claude Code and the Agent SDK express gates with three kinds of permission rule. A rule can name a whole tool, such as Bash, or a specific call, such as Bash(git push *). That is why one dangerous command can be gated while its harmless siblings run freely.

    Permission rule kinds and their role in a checkpoint design
    Rule kindEffectRole in a checkpoint design
    AllowClaude Code uses the tool without manual approvalPre-approve read-only and low-risk calls so they never wait
    AskPrompts for confirmation when Claude tries to use the toolThe checkpoint itself, for irreversible or external calls
    DenyPrevents Claude Code from using the toolActions no reviewer should ever be asked to approve

    A gate has to sit in the permission flow, where it pauses the call whatever the model decides. A sentence in the system prompt asking Claude to check first is not a gate. Guardrail placement covers why an enforced control beats one that relies only on the prompt.

    Checkpoint 1 of 9· Match them up

    An agent investigates support tickets and can issue refunds. Match each permission rule kind to its job in the agent's checkpoint design.

    Tap a term, then the definition that fits it.

    Sources12

    2.Pausing consequential calls with canUseTool

    In the Agent SDK, each tool call passes through a fixed sequence of checks. The first check that settles the call wins. Approval only reaches your canUseTool callback, where a human can be asked, if nothing earlier has already allowed or denied it.

    Agent SDK permission evaluation order
    StepWhat it can do
    HooksRun custom code to allow, deny or otherwise decide the call
    Deny rulesBlock matching calls
    Ask rulesSend matching calls on for approval
    Permission modebypassPermissions approves most calls; acceptEdits approves listed file operations; default and dontAsk pass the call to the allow rules
    Allow rulesApprove listed calls, such as allowedTools entries
    canUseTool callbackYour code decides, typically by asking a person

    This order tells you how to split a toolset. Take a support agent with read-only search_orders and get_customer, an irreversible refund_payment and a customer-facing send_email. List the two read-only tools in allowedTools. Their calls are approved at the allow-rule step and never reach the callback, so lookups don't wait on anyone. Leave the other two unlisted. Their calls fall through to canUseTool, which can hold each one until a reviewer answers.

    A canUseTool callback that holds a call until a person decidestypescript
    canUseTool: async (toolName, input) => {
      console.log(`Claude wants to use ${toolName}`);
      const approved = await askUser("Allow this action?");
    
      if (approved) {
        return { behavior: "allow", updatedInput: input };
      }
      return { behavior: "deny", message: "User declined" };
    };

    A denial does not crash the agent. The tool doesn't run, Claude receives your message, and it carries on. A reviewer has more than yes and no to work with:

    • approve the call as requested
    • approve with changes, rewriting the input before it runs, for example capping an amount or sanitising a path
    • approve and remember, sending back a suggested rule so that matching calls skip the prompt next time
    • reject, with a reason Claude can act on, or suggest an alternative

    Approve-and-remember suits repetitive, low-stakes calls. On an irreversible tool it turns one reviewer's sign-off into permanent approval for every later refund. Adding refund_payment to allowedTools after the first approval does the same thing. The opposite mistake is a PreToolUse hook that returns ask for every tool. That treats every tool the same, so search_orders waits on a human as long as a refund does.

    Checkpoint 2 of 9· Check yourself

    After a reviewer approves the first refund, the support team says the agent feels slow. Which change cuts the waiting and still keeps a human checkpoint on every refund?

    Checkpoint 3 of 9· Exam question

    A support agent built on the Agent SDK exposes two read-only lookup tools (orders, customer profile), an irreversible refund tool, and a customer-facing email tool. The compliance owner requires a reviewer decision before any refund or email goes out. The support lead requires that lookups never wait on a person. Which two design elements satisfy both stakeholders? Choose two.(Select 2)

    0 of 2 selected

    Sources34

    3.Moving the gate as a task changes phase

    Sometimes a reviewer should approve the approach once and then stay out of the way. Permission modes let a session move its gate as the work changes phase. Each mode decides which calls run without asking. Ask rules and the canUseTool callback still catch whatever the mode doesn't cover.

    Permission modes compared by what runs without asking
    ModeRuns without askingFits
    defaultReads onlyReviewing every action, sensitive work
    planReads; edits are blocked until you approve a planAgreeing the approach before anything changes
    acceptEditsReads, file edits and common filesystem commands such as mkdir, touch, mv, cpIterating on code you will review as a diff
    dontAskReads in working directories and pre-approved tools; anything that would prompt is deniedLocked-down CI and scripts
    bypassPermissionsEverythingIsolated containers and VMs only

    Take an authentication migration across 40 files. Start in plan. Claude reads and proposes, and Claude Code blocks edits until the plan is approved, so stakeholders sign off on the approach rather than on one sample edit. Then switch to acceptEdits. In-directory edits now run without prompts. The command that applies the schema to shared staging is neither a file edit nor one of the listed filesystem commands, so it goes on to the allow rules and the callback and still needs approval. Switching to bypassPermissions instead would let that staging command through unreviewed. Staying in default produces 40 edit prompts, and edit diffs are a poor way to judge an overall design.

    Switching an Agent SDK session's permission mode mid-session (Python)python
            await client.query("Help me refactor this code")
    
            # Change mode dynamically mid-session
            await client.set_permission_mode("acceptEdits")

    Checkpoint 4 of 9· Check yourself

    Stakeholders have just approved the plan for a 40-file authentication migration. The task ends with a command that applies the schema to shared staging. What should the session do next?

    Checkpoint 5 of 9· Exam question

    A team is migrating an authentication module across 40 files in an agent session. Stakeholders want to sign off on the approach before anything changes. After that, they don't want to be interrupted for routine in-project edits. The command that applies the schema change to shared staging must still need a human approval. Which permission sequence fits?

    Sources513

    4.Gating an irreversible step when nobody is online

    Headless runs make checkpoints harder, because a prompt has nobody to answer it. Take a nightly job that migrates customer records and ends by dropping a legacy table. The migration stages should run unattended. The drop should wait for a human, even if that means waiting until morning.

    Neither unattended mode gives you a checkpoint. dontAsk fails the drop outright and leaves nothing for a reviewer to approve later. Running claude -p with --dangerously-skip-permissions belongs inside a container or VM, and the few calls that would still prompt are denied there too. Writing the drop to an audit log for someone to read the next morning is a record of what happened, not a gate, because the table is already gone.

    A PreToolUse hook can defer the call. When the hook on the drop tool returns permissionDecision: "defer", the tool doesn't execute. The turn ends with stop_reason: "tool_deferred" and the pending call stays in the transcript. Your process picks up deferred_tool_use from the result and brings in a reviewer. It then runs claude -p --resume <session-id> with the same permission host. The same call fires PreToolUse again, and this time the hook can return allow. Everything before the drop has already run unattended.

    Defer has fallbacks, and your design must hold up when one applies. In interactive sessions the hook result is ignored. If several tool calls arrive at once, defer is ignored with a warning and the call goes through the normal permission flow. That flow must not approve the drop on its own, which rules out running the job under bypassPermissions. A structural alternative avoids the problem: put the drop in its own stage that starts only after a reviewer has recorded approval. A second model call that judges whether the table is unused is not a substitute. It replaces the human decision the checkpoint exists to collect.

    Checkpoint 6 of 9· Check yourself

    Suppose the nightly job runs under bypassPermissions, and its PreToolUse hook returns defer for the drop. Claude issues the drop in the same batch as another tool call, so the defer is ignored. What happens to the drop?

    Checkpoint 7 of 9· Exam question

    Your team runs a nightly headless migration agent that ends with an irreversible drop of a legacy customer table. The data owner requires a human decision before the drop. No reviewer is online overnight, and the earlier migration stages must still finish unattended. Which two designs satisfy the data owner? Choose two.(Select 2)

    0 of 2 selected

    Sources65

    5.Approval policies for Managed Agents tools

    Managed Agents set checkpoints with a permission policy on each server-executed tool. Policies cover the prebuilt agent toolset and MCP toolsets. Custom tools run in your own application, so policies don't apply to them and any gate for them is yours to build. The agent toolset defaults to always_allow. MCP toolsets default to always_ask, so a tool newly added to an MCP server can't run without approval.

    Managed Agents permission policies
    PolicyBehaviourUse it for
    always_allowExecutes automatically with no confirmationTools whose calls are safe whenever they occur
    always_askThe session pauses and waits for your approval before executingIrreversible or external actions
    autoThe server runs the call, denies it, or pauses for your approvalTools where risk depends on the specific input

    A per-tool override keeps the gate narrow. The toolset stays on always_allow and one tool is singled out for review:

    Allow the agent toolset by default, but require confirmation for bashyaml
    ---
    name: Coding Assistant
    model: claude-opus-5-5
    tools:
      - type: agent_toolset_20260401
        default_config:
          permission_policy:
            type: always_allow
        configs:
          - name: bash
            permission_policy:
              type: always_ask
    ---

    A paused call shows up as a session.status_idle event whose stop_reason.type is requires_action, and the session waits indefinitely. Your client answers each blocking event with a user.tool_confirmation that sets result to allow or deny, optionally with a deny_message. A denied tool doesn't run, and the agent is told why. Policy changes take effect only for sessions created afterwards, because running sessions keep the toolset configuration they started with.

    Under auto, the server weighs the tool, its input, earlier calls and your intent, so it can treat two calls to the same tool differently. A call it judges high-risk is denied, and confirming it anyway gets a 400 error from the API. Intent is read only from user.message events, never from tool results or fetched pages. If you relay untrusted end-user text as user messages, that text counts as intent too. Put always_ask on any tool you wouldn't let that end user run unreviewed. The injection side of this is covered in prompt injection controls.

    Checkpoint 8 of 9· Fill the gap

    Which policy goes in the blank so that the agent toolset runs freely but every bash command pauses for a human?

    ---
    name: Coding Assistant
    model: claude-opus-5-5
    tools:
      - type: agent_toolset_20260401
        default_config:
          permission_policy:
            type: always_allow
        configs:
          - name: bash
            permission_policy:
              type:  ? 
    ---

    Checkpoint 9 of 9· Check yourself

    A Managed Agents support bot passes each customer's chat text into the session as user.message events. Its MCP tool refund_payment uses the auto policy. What should the team change?

    Sources7

    Sources

    (7)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Ask rules prompt for confirmation when Claude tries to use the specified tool.”
      ↩︎ Where a checkpoint belongs
      “Automatically accepts file edits and common filesystem commands such as mkdir, touch, mv, and cp for paths in the working directory or additionalDirectories”
      ↩︎ Moving the gate as a task changes phase
    2. 2.
      “Require human approval for sensitive actions like database writes or API calls”
      ↩︎ Where a checkpoint belongs
    3. 3.
      “Calls to a listed tool are approved before canUseTool is consulted, apart from the calls an allow rule never approves.”
      ↩︎ Pausing consequential calls with canUseTool
      “In default and dontAsk mode, the call goes on to the allow rules.”
      ↩︎ Pausing consequential calls with canUseTool
      “Change mode dynamically mid-session”
      ↩︎ Moving the gate as a task changes phase
      “Tool calls are approved before canUseTool is consulted, so your callback runs for only a few calls”
      ↩︎ Exam trap 1
      “Calls to a listed tool are approved before canUseTool is consulted, apart from the calls an allow rule never approves.”
      ↩︎ Exam trap 2
      “Tool calls are approved before canUseTool is consulted, so your callback runs for only a few calls”
      ↩︎ Prediction
    4. 4.
      “Approve and remember: echo a suggested permission rule back so matching calls skip the prompt next time”
      ↩︎ Pausing consequential calls with canUseTool
      “Approve with changes: modify the input before execution (for example, sanitize paths, add constraints)”
      ↩︎ Pausing consequential calls with canUseTool
      “Deny: tool doesn't execute, Claude sees the message”
      ↩︎ Pausing consequential calls with canUseTool
      “Tool needs approval: Claude wants to use a tool that isn’t auto-approved by a permission rule or permission mode.”
      ↩︎ Key concept
      “Tool needs approval: Claude wants to use a tool that isn’t auto-approved by a permission rule or permission mode.”
      ↩︎ Checkpoint
    5. 5.
      “Claude Code blocks edits until you approve a plan”
      ↩︎ Moving the gate as a task changes phase
      “In this -p run, the few calls that would still prompt are denied instead”
      ↩︎ Gating an irreversible step when nobody is online
      “File reads inside your working directories and pre-approved tools; anything that would prompt is denied”
      ↩︎ Exam trap 3
      “acceptEdits | Reads, file edits, and common filesystem commands (mkdir, touch, mv, cp, etc.)”
      ↩︎ Checkpoint
      “File reads inside your working directories and pre-approved tools; anything that would prompt is denied”
      ↩︎ Prediction
      “bypassPermissions | Everything | Isolated containers and VMs only”
      ↩︎ Checkpoint
    6. 6.
      “The turn ends with a result carrying stop_reason: "tool_deferred", and the pending tool call stays in the transcript.”
      ↩︎ Gating an irreversible step when nobody is online
      “The calling process runs claude -p --resume <session-id> with the same permission host.”
      ↩︎ Gating an irreversible step when nobody is online
      “In interactive sessions: it logs a warning and ignores the hook result”
      ↩︎ Gating an irreversible step when nobody is online
      “Several tool calls at once: "defer" is ignored with a warning and the tool proceeds through the normal permission flow”
      ↩︎ Exam trap 4
    7. 7.
      “Custom tools run in your application, under your control, so permission policies don’t apply to custom tools.”
      ↩︎ Approval policies for Managed Agents tools
      “This ensures that new tools added to an MCP server do not run in your application without approval.”
      ↩︎ Approval policies for Managed Agents tools
      “The session waits indefinitely for a response.”
      ↩︎ Approval policies for Managed Agents tools
      “Send a user.tool_confirmation event for each blocking event, passing the event ID in the tool_use_id parameter.”
      ↩︎ Approval policies for Managed Agents tools
      “As a result, the server can treat two calls to the same tool differently.”
      ↩︎ Approval policies for Managed Agents tools
      “Configure always_ask on the tools you would not let that end user run without review.”
      ↩︎ Approval policies for Managed Agents tools
      “The session keeps running, and your client cannot override the denial.”
      ↩︎ Exam trap 5

    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.