Tool Approval & State Persistence

Not yet available. The Agent SDK is tracked to be built — today, use the Client SDKs against the live chat completions API. The docs below describe the intended design.

Some tool calls should not fire automatically — sending an email, writing to a database, making a payment. Tool approval lets you intercept a tool call before it executes, inspect it, and approve or reject it. State persistence lets you serialise the agent's item list so the loop can pause and resume across process restarts.

Approval callbacks#

Add an approval function to any tool definition. The SDK calls it with the ToolCallItem before dispatching execute. Return true to approve, false to reject.

const sendEmailTool = {
  name: "send_email",
  description: "Send an email to a recipient.",
  parameters: {
    type: "object",
    properties: {
      to: { type: "string" },
      subject: { type: "string" },
      body: { type: "string" },
    },
    required: ["to", "subject", "body"],
  },
  execute: async ({ to, subject, body }) => {
    await emailClient.send({ to, subject, body });
    return `Email sent to ${to}.`;
  },
  approval: async (call) => {
    // Prompt the human
    const approved = await promptUser(
      `Approve sending email to ${call.arguments.to}? (y/n)`
    );
    return approved;
  },
};

When approval returns false, the SDK injects a tool_result with an error: "rejected" field and continues the loop — the model can then decide to try a different approach or give up.

Shorthand approval modes#

For simpler cases, approval accepts a string:

approval: "always"  // Every call requires an explicit approval decision — the loop pauses until one is recorded
approval: "never"   // Never prompt — always execute automatically (the default)

Persisting state across approval gaps#

When approval requires human input that may not arrive synchronously — for example, via a web form, a Slack message, or a mobile notification — the agent loop cannot block. Persist the item list to a database, pause, and resume when the human responds.

// Before pausing — save items to your store
await db.agentSessions.upsert({
  id: sessionId,
  items: JSON.stringify(result.items),
  status: "awaiting_approval",
  pendingToolCall: JSON.stringify(pendingCall),
});

// When the human responds — load items and resume
const session = await db.agentSessions.findById(sessionId);
const items = JSON.parse(session.items);

const resumed = await client.callModel({
  model: "anthropic/claude-sonnet-5",
  inputItems: items,
  // Inject the approved or rejected result manually
  messages: [
    {
      role: "tool",
      tool_call_id: session.pendingToolCall.id,
      content: approved ? await executeTool(session.pendingToolCall) : "rejected",
    },
  ],
});

Approval state in the item list#

Rejected tool calls appear in the item list as tool_result items with error: "rejected". The model can see these and adjust its behaviour — it might try an alternative tool, ask the user for clarification, or give a graceful response.

Audit trail#

Because the item list is append-only and contains every tool call and result, it doubles as a complete audit trail. Persist it alongside your application data to meet compliance requirements (Algeria Law 18-07 for PII-touching operations).

Also see#

• Tools — tool definition and dispatch.
• Working with Items — the item list model.
• Stop Conditions — halting on rejected calls.
• Example: Skills Loader — dynamic tool loading with approval.