Approvals in the loop

Tools a human has to approve

Mark the tools an agent should not use unattended. The run parks on a reviewer before the tool runs, holding no worker while it waits:

const issueRefund = tool({
  name: "issue-refund",
  description: "Issue a refund to the customer",
  inputSchema: { type: "object", properties: { amount: { type: "number" } } },
  requiresApproval: true,
  handler: (input) => refunds.issue(input),
});

requiresApproval: true raises the gate and says nothing else about it. Say more with approval, and the same annotations a hand-written ctx.step.approval takes apply to the tool’s gate:

const issueRefund = tool({
  name: "issue-refund",
  requiresApproval: true,
  approval: {
    risk: "high",
    summary: "Refund a customer for a duplicate charge",
    allow: ["approve", "reject"],
    timeout: "30m",
    onTimeout: "reject",
  },
  handler: (input) => refunds.issue(input),
});

Declare a risk on anything you would not want cleared by a credential. A gate that states no risk is stored at the default, medium, and the human-decision floor reads the stored risk - so a floor of high cannot refuse a gate that never claimed to be high.

The reviewer sees the input the model proposed and can change it before approving - the tool then runs with their input, not the model’s. A denial is not an error: it comes back to the model as that tool’s result, so the agent can say what it could not do instead of the run failing.

Decision	What runs	What the model gets
Approved	The handler, with the decided input	The handler’s return value
Approved with edits	The handler, with the reviewer’s input	The handler’s return value
Denied	Nothing	`{ approved: false, tool, decidedBy }`

Each gate is its own durable step, so resuming the run replays the agent without asking anyone twice. Both the approval and the tool call show up under their turn in the console, so a parked agent reads as parked rather than as a tool that never finished.

Gating some calls and not others

requiresApproval is one bit for the whole tool, so a refund tool marked true wakes someone for a

2 refund and one marked `false` wakes nobody for a

50,000 one. approval.if and approval.minRisk are the third answer: a condition on this call, written as data and evaluated by Duraton.

const issueRefund = tool({
  name: "issue-refund",
  inputSchema: { type: "object", properties: { amount: { type: "number" } } },
  requiresApproval: true,
  approval: {
    risk: "high",
    // Small refunds go through; anything above the limit waits for a person. And after
    // three turns the agent is looping, so gate whatever it reaches for next.
    if: "args.amount > 1000.0 || iteration > 3",
  },
  handler: (input) => refunds.issue(input),
});

The expression reads four names and no others - tool, args, risk and iteration - and every JSON number in args reaches it as a double. A rule that cannot be evaluated raises the gate rather than skipping it, and one that declines completes the step as decidedBy: "system:rule" with no approval for anyone to answer. The full environment, the failure modes and when this beats a hand-written if are on Approvals.

Which rule applies to a tool

A rule can be declared in two places: on the tool, and on the agent as the default for every tool that has not answered for itself.

await agent(ctx, "support", {
  model: "claude-opus-4-8",
  prompt: `Resolve this ticket: ${ctx.event.data.ticket}`,
  tools: [searchPolicy, issueRefund],
  mcpServers: [{ name: "orders", transport: { kind: "http", url: process.env.ORDERS_MCP_URL } }],
  // Anything that did not answer for itself gates, and gates like this.
  approval: { risk: "high", summary: "A tool this agent was not told how to treat", timeout: "1h" },
  maxIterations: 6,
});

The two levels resolve in one order, and requiresApproval is tri-state on purpose - absent, true and false are three different answers rather than a boolean with a default:

The tool says	The agent has a default	The gate
`requiresApproval: false`	either way	none. An opt-out is an answer, and it beats the default
`approval: { ... }`	either way	raised, under the tool’s own rule
`requiresApproval: true`	yes	raised, under the agent’s default
`requiresApproval: true`	no	raised, with nothing said about it
nothing	yes	raised, under the agent’s default
nothing	no	none

Two rows are worth reading twice. requiresApproval: true on a tool the agent has a default for takes that default’s annotations rather than erasing them: true asks for a gate, it does not claim there is nothing to say about one. And a tool’s own approval replaces the default rather than merging with it - a rule is one policy, so a tool that states risk and no timeout has no timeout, whatever the default said.

A tool with no opinion at all inherits the default. That is the point: requiresApproval: false is how a tool says it never waits for anyone, and saying nothing is not the same as saying that.

The default is also what covers an MCP server’s tools that the server’s own predicate says nothing about. Those tools are attached here and discovered at runtime, so there is no declaration above to annotate and no list to enumerate ahead of time.

Capping the decisions an agent asks for

maxApprovals is a ceiling on how many human decisions one agent may ask for. When a turn’s tool calls would take it past the ceiling, the agent stops instead of running them, and returns stopReason: "approval-budget":

const result = await agent(ctx, "support", {
  model: "claude-opus-4-8",
  prompt: `Resolve this ticket: ${ctx.event.data.ticket}`,
  tools: [searchPolicy, issueRefund],
  maxIterations: 12,
  maxApprovals: 3,
});

if (result.stopReason === "approval-budget") {
  return { outcome: "handed-off", reason: "the agent asked for more sign-off than it was allowed" };
}

Omitted, there is no ceiling. Set one where an agent could plausibly keep reaching for a gated tool: maxIterations bounds how long it runs, and this bounds how much of a person’s attention it can spend doing so. Handle the stop like any other terminal reason - the agent returns rather than throwing, so the workflow decides what a run that ran out of sign-off does next.

Showing the model less than you record

A tool that returns a thousand rows costs a thousand rows of context on every turn after it. Give it a toModelOutput and the model reads the summary while the durable step keeps the whole thing:

const listOrders = tool({
  name: "list-orders",
  description: "Every order for a customer",
  outputSchema: { type: "object", properties: { orders: { type: "array" } } },
  toModelOutput: (output) => ({
    count: output.orders.length,
    ids: output.orders.slice(0, 5).map((o) => o.id),
  }),
  handler: (input) => orders.listFor(input.customerId),
});

The projection is not a truncation you can never undo. The tool’s step still holds all thousand orders, so the run’s history, a replay, and anything reading the timeline all see the full result - only the model’s context was spent on the summary.

toModelOutput must be pure. A replay re-projects the result the tool already returned rather than calling the tool again, so a projection that reads the clock or a counter makes a replayed turn disagree with the original.

It runs only on a result your tool actually produced. A denial from an approval gate is the loop telling the model about its own gate, so it reaches the model unprojected.

Checking the model’s tool arguments

The arguments a tool is called with are written by the model. Pass a guardrail and they are checked against the tool’s own inputSchema before the handler ever sees them; a refusal comes back to the model as that tool’s result, so it can correct itself.

import { createSchemaGuardrail } from "@duraton/sdk";

const result = await agent(ctx, "agent", {
  model: "claude-opus-4-8",
  prompt: `Resolve this ticket: ${ctx.event.data.ticket}`,
  tools: [searchPolicy],
  maxIterations: 6,
  guardrails: [createSchemaGuardrail()],
});

The verdict is its own durable step, so a replay reads what was decided instead of deciding again. Guardrails covers the placements, the actions, and how to write your own.

Start with code

Agent kit

AI

Durable runs

Integrations

TypeScript SDK

REST API

Protocol

Approvals in the loop

Tools a human has to approve

Gating some calls and not others

Which rule applies to a tool

Capping the decisions an agent asks for

Showing the model less than you record

Checking the model’s tool arguments

​Tools a human has to approve

​Gating some calls and not others

​Which rule applies to a tool

​Capping the decisions an agent asks for

​Showing the model less than you record

​Checking the model’s tool arguments

Tools a human has to approve

Gating some calls and not others

Which rule applies to a tool

Capping the decisions an agent asks for

Showing the model less than you record

Checking the model’s tool arguments