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.
| Rule kind | Effect | Role in a checkpoint design |
|---|---|---|
| Allow | Claude Code uses the tool without manual approval | Pre-approve read-only and low-risk calls so they never wait |
| Ask | Prompts for confirmation when Claude tries to use the tool | The checkpoint itself, for irreversible or external calls |
| Deny | Prevents Claude Code from using the tool | Actions 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.
The checkpoint itself is an ask rule on the irreversible or external call. Allow rules keep low-risk calls from stalling and stop reviewers from learning to click through prompts. Deny rules cover actions that should never run, so nobody has to approve or reject them.
“Ask rules prompt for confirmation when Claude tries to use the specified tool.”Source: code.claude.com
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.
| Step | What it can do |
|---|---|
| Hooks | Run custom code to allow, deny or otherwise decide the call |
| Deny rules | Block matching calls |
| Ask rules | Send matching calls on for approval |
| Permission mode | bypassPermissions approves most calls; acceptEdits approves listed file operations; default and dontAsk pass the call to the allow rules |
| Allow rules | Approve listed calls, such as allowedTools entries |
| canUseTool callback | Your 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.
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?
Listed tools are approved at the allow-rule step and never reach canUseTool. Listing only the read-only lookups means they stop waiting, while unlisted refunds still fall through to the reviewer. Listing refund_payment, or remembering a rule for it, turns one approval into permanent approval for later refunds. An ask hook that also covers the lookups makes them wait as long as refunds do.
“Tool needs approval: Claude wants to use a tool that isn’t auto-approved by a permission rule or permission mode.”Source: code.claude.com
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)
Correct answers: A, B — Add the orders and customer-profile lookup tools to the permission allow list, so those calls run straight away without reaching the reviewer approval step.; Route the refund and email tools to a permission callback that holds each call until a reviewer returns an explicit allow or deny, so those actions run only once that decision arrives.
- A. Correct. Allow-list entries pre-approve the two read-only lookup tools, so those calls execute immediately and no person is involved. This meets the support lead's requirement and leaves the checkpoint on the refund and email tools untouched.
- B. Correct. Refund and email calls are the consequential actions, so they are sent to a permission callback that suspends execution until a reviewer returns allow or deny. The platform enforces the compliance owner's reviewer decision before anything goes out.
- C. Incorrect. A mode that bypasses permission prompts approves every tool call without asking anyone, so the system prompt rule is only an instruction the model can fail to follow. Nothing enforces a reviewer decision, and an irreversible refund or customer email could go out unreviewed.
- D. Incorrect. A hook that sends the two lookup tools to a reviewer as well puts a person in front of the read-only calls, which breaks the requirement that lookups never wait on a person. Uniform handling and a single audit trail do not outweigh that, since the lookups carry no consequence.
- E. Incorrect. An allow-list entry approves every later call to the refund tool regardless of its arguments, so after one sign-off the checkpoint is gone. Each refund is irreversible and needs its own reviewer decision, so the compliance requirement stops being met.
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.
| Mode | Runs without asking | Fits |
|---|---|---|
| default | Reads only | Reviewing every action, sensitive work |
| plan | Reads; edits are blocked until you approve a plan | Agreeing the approach before anything changes |
| acceptEdits | Reads, file edits and common filesystem commands such as mkdir, touch, mv, cp | Iterating on code you will review as a diff |
| dontAsk | 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 |
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.
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?
acceptEdits auto-approves file edits and common filesystem commands. The staging schema command is neither, so it goes on to the allow rules and the callback and still needs approval. bypassPermissions approves the command before canUseTool runs. dontAsk denies anything that would prompt, so nobody gets to review the command. Staying in default stalls the work on 40 edit prompts.
“acceptEdits | Reads, file edits, and common filesystem commands (mkdir, touch, mv, cp, etc.)”Source: code.claude.com
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?
Correct answer: A — Start in plan mode, where Claude only reads and proposes, and have stakeholders review that plan; then switch to accept-edits mode, which applies file edits directly while the staging schema command keeps its prompt.
- A. Correct. Plan mode keeps Claude read-only, so stakeholders review the proposal before any file changes. Accept-edits mode then applies in-project file edits without prompts, while shell commands such as the schema change against shared staging still ask for a human decision.
- B. Incorrect. Accept-edits mode starts changing files immediately, so the first edit lands before stakeholders have approved anything. The instruction to stop after one file is only a request in the prompt, not an enforced checkpoint, so it does not guarantee a review point.
- C. Incorrect. Default mode prompts on each edit, so the team is interrupted 40 times for routine in-project changes it wanted to run freely. Approving edits piecemeal also means the first change is applied before anyone has reviewed the approach as a whole, so stakeholders never get the sign-off they wanted before anything changes.
- D. Incorrect. The planning step is right, but bypass-permissions mode removes the prompts altogether, including the one on the schema command for shared staging. That command would run with no human approval, which the team required to stay in place.
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.
A denial ends the attempt, so someone has to rerun the job. A deferred call stays pending in the transcript. When the session resumes, the same call reaches the hook again and can be allowed, with all the earlier work kept.
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?
When several tool calls arrive at once, defer is ignored and the drop goes through the normal permission flow. bypassPermissions approves almost everything at the permission-mode step, before canUseTool runs, so the drop executes with no review. This is why a job that relies on defer must not run under bypassPermissions.
“bypassPermissions | Everything | Isolated containers and VMs only”Source: code.claude.com
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)
Correct answers: A, B — Mark the drop step as deferred so the run ends at that point with its state saved, then resume the job once a reviewer has signed off on the drop.; Split the drop into its own stage that starts only after a reviewer records approval, and keep the earlier migration stages on the nightly schedule.
- A. Correct. Deferring just the drop step ends the run at that point with its state saved. The earlier stages complete without anyone present, a reviewer can sign off whenever they are online, and the job resumes afterward without a process being kept open.
- B. Correct. Putting the drop in its own stage that begins only after a reviewer records approval places a human decision before the destructive step. The reversible migration stages still run on the nightly schedule with nobody online.
- C. Incorrect. A mode that skips permission prompts lets the job run the drop with no human involved. The run finishes on time, but the data owner's requirement for a person to decide before the table is dropped is not met.
- D. Incorrect. A reviewer agent is another automated process, not a person, so nobody makes the decision the data owner requires before the drop. Its check of query logs can also miss usage the logs do not capture.
- E. Incorrect. Reviewing the executed statement the next morning happens after the drop has run, so no human decides beforehand. A backup may help recovery, but it does not supply the pre-drop decision the data owner requires.
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.
| Policy | Behaviour | Use it for |
|---|---|---|
| always_allow | Executes automatically with no confirmation | Tools whose calls are safe whenever they occur |
| always_ask | The session pauses and waits for your approval before executing | Irreversible or external actions |
| auto | The server runs the call, denies it, or pauses for your approval | Tools 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:
---
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: ?
---A per-tool override in configs gives bash the policy always_ask. The rest of the toolset stays on always_allow, so only bash pauses. The auto policy lets the server run or deny some bash calls without asking anyone. requires_action is the stop reason a paused session reports, not a policy.
Source: platform.claude.comCheckpoint 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?
Under auto, the server reads intent from user.message events, so customer text sent that way can get a refund approved. Setting always_ask makes every refund wait for a person. An auto denial is final, and confirming it anyway returns a 400 error. Permission policies do not apply to custom tools.
“Configure always_ask on the tools you would not let that end user run without review.”Source: platform.claude.com
Sources7
Sources
(7)
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/permissionsOfficial docs
“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.https://code.claude.com/docs/en/agent-sdk/hooksOfficial docs
“Require human approval for sensitive actions like database writes or API calls”
↩︎ Where a checkpoint belongs - 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.https://code.claude.com/docs/en/agent-sdk/user-inputOfficial docs
“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.https://code.claude.com/docs/en/permission-modesOfficial docs
“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.https://code.claude.com/docs/en/hooksOfficial docs
“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.
“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