Handle an approval

When ActionPolicy returns require_approval, Checkfu parks the Run and creates an ActionApproval. Your application notices the wait, shows an authorized reviewer the exact frozen action, and answers it. Connected ToolInvocations and Custom tools share the human-decision resource but not the same surrounding authorization or execution path. The examples use the TypeScript SDK:

Plain HTTP against the Checkfu API needs no private package. The Checkfu CLI and TypeScript SDK are optional private-alpha artifacts; the HTTP requests work without them. Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it. Confirm capability status before making availability part of your application’s contract.

import {
  Checkfu,
  canonicalArgumentsHash,
  respondToToolConfirmation,
  submitCustomToolResult,
} from "@checkfu/sdk"

const checkfu = new Checkfu({
  apiKey: process.env.CHECKFU_API_KEY,
})

Detect the wait

Drive a live review queue from the Session event stream. session.status_waiting says the Session is parked; run.requires_action says why.

for await (const event of stream) {
  if (event.type !== "run.requires_action") continue

  const action = event.payload.action
  switch (action.kind) {
    case "action_approval":
      await queueForReview({
        approvalId: action.approval,
        toolUseId: action.tool_use_id,
        customToolAfterApproval:
          action.on_approve?.kind === "custom_tool",
      })
      break
    case "custom_tool":
      // ActionPolicy already allowed this Custom tool.
      await queueAuthorizedCustomTool(action.tool_use_id)
      break
    case "question":
      // Ordinary input, not authority.
      await queueQuestion(action.question, action.items)
      break
  }
}

A direct custom_tool wait needs an application result but no human decision. A Question grants no authority and is answered with user.question_answer.

Read the frozen decision

Fetch GET /v1/action-approvals/{id} or use the overlapping authority carried by action_approval.pending.Render the context by kind:

A connected ToolInvocation can name the acting Principal, Agent version, Session, Run, Connection revision, ToolSource and Tool versions, schema hash, and outbound destination. It follows PermissionAssignment → ActionPolicy → ActionApproval.
A Custom-tool ActionApproval names the admitted Agent, logical Tool, tool_use_id, Session, Run, and optional surface coordinate. It has no Connection, ToolSource, provider request, PermissionAssignment in the Tool invocation path, or child-thread coordinate in context_summary.

Both resource variants carry top-level arguments_hash, not argument values. For a Custom tool, read the exact arguments from the preceding agent.tool_use event and prove that the displayed payload matches:

const matches =
  (await canonicalArgumentsHash(recordedArguments)) ===
  approval.arguments_hash

if (!matches) throw new Error("review payload does not match the frozen action")

Do not ask a reviewer to paste a provider token into the decision. Checkfu never returns a custodied Credential value in the ActionApproval resource or Session event. Your application must also keep its own secrets out of arbitrary Tool arguments, results, and reviewer instructions.

Respond once

For a primary-thread ActionApproval, send the current version as expected_version. Retain one idempotency key for this logical response and reuse it only for an exact retry.

curl --request POST \
  "https://api.checkfu.com/v1/action-approvals/$APPROVAL_ID/responses" \
  --header "Authorization: Bearer $CHECKFU_API_KEY" \
  --header "Checkfu-Version: 2026-08-31" \
  --header "Idempotency-Key: approval-$APPROVAL_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "expected_version": 1,
    "decision": "approve",
    "instructions": "Approved for this action only."
  }'

const resolution = await checkfu.actionApprovals.decide(
  approvalId,
  {
    expected_version: approval.version,
    decision: "approve",
    instructions: "Approved for this action only.",
  },
  { idempotencyKey: `approval-${approvalId}` },
)

Two reviewers racing on one item are serialized by expected_version; the loser re-reads and shows the durable outcome. A stale response returns 409 validation.conflict. Re-read the approval instead of silently approving its new version or changed arguments. Responder authorization is checked separately and can return 403 policy.denied.A ToolInvocation ActionApproval is the CapabilityGateway branch. Its CapabilityGateway approve response carries one deterministic, single-use proof token. Managed-tool, Custom-tool, browser, harness-tool, and Automation-step approvals carry no provider-effect proof, and every denial carries none. Idempotent replay does not extend expiry or make a consumed proof usable again.

Continue the correct path

Branch on the approval context.Connected ToolInvocation through platform MCP: Resolving ActionApproval records the decision; it does not dispatch the operation or automatically resume or create a Run. Retry the identical original tools/call, preserving its original ToolInvocationId and the returned requestState where applicable. Checkfu rechecks current Connection, grant, policy, approval, and other required authority before execution. A completed identical retry is refused as already_executed rather than dispatched again. A denial is not permission to execute elsewhere.Connected ToolInvocation parked in a native Session: On a route that supports native approval waits, Checkfu can wake the original parked call after recording the decision. It rechecks the original caller, acting Principal, Connection, Tool, policy and retained Skill inputs. The resumed call still needs fresh execution authorization before using its single-use approval proof. The original account, arguments, frozen context and expiry remain bound. Do not create a replacement call to work around a refusal. A missing, expired or erased original call prevents the wake; a recorded continuation does not prove provider completion or result delivery. Do not assume restart or duplicate recovery is supported on the selected route.Custom tool: PermissionAssignment is not part of the Tool-call path. After approval, wait for run.action_authorized, correlate it to the preceding agent.tool_use, execute the handler in your application, and post the exact result. ActionApproval itself does not execute the handler or start a new Run.

Custom-tool approval continuation and proof custody

When approval.context_summary.kind === "custom_tool", the preceding agent.tool_use is the frozen customer-handled call. After approval, run.action_authorized records the exact authorization. The same compute-closed Run stays parked until the application executes the handler and posts user.custom_tool_result; approval itself does not execute the Tool or start another Run. Accepting the matching user.custom_tool_result continues the original waiting Run under current authority with its retained context pins. It does not create a new Run or resolve newer latest context. The result records the handler’s output for the original tool_use_id; retry with the same result payload and idempotency key to recover that same accepted event. Follow the original Run’s recorded outcome to determine when its work settles. Input acceptance, an Agent message, or session.status_idle with stop_reason: "requires_action" does not establish completion. That idle event is an intermediate wait. A provider-effect receipt remains separate from result acceptance and Run settlement.

await checkfu.sessions.events.send(
  sessionId,
  {
    type: "user.custom_tool_result",
    payload: {
      tool_use_id: toolUseId,
      result,
      caused_by: { kind: "api", request_id: `tool-result-${toolUseId}` },
    },
  },
  { idempotencyKey: `tool-result-${toolUseId}` },
)

Authenticated server context supplies durable actor attribution. GET /action-approvals/{id} never reveals a CapabilityGateway proof. Preserve a CapabilityGateway approve response only long enough to present its proof to the immediate trusted effect; do not log it, put it in Session content, reuse it after expiry, or treat it as authority for another action. This proof rule applies only to the ToolInvocation branch; the Custom-tool result carries causal attribution, not a bearer credential.

Tool confirmations

For CMA-shaped clients, a Tool wait can instead be answered through the Session’s event endpoint, not the ActionApproval resource response route. Echo the exact tool_use_id from agent.tool_use.

await respondToToolConfirmation(checkfu, {
  sessionId,
  toolUseId,
  result: "allow",
  actor: {
    requestId: `tool-confirmation-${toolUseId}`,
  },
  idempotencyKey: `tool-confirmation-${toolUseId}`,
})

Use result: "deny" and an optional nonempty denyMessage to refuse it. Checkfu still applies the frozen approval and responder-authority checks. An allowed Custom-tool wait then requires the matching user.custom_tool_result with the same Tool-use ID. Authenticated server context supplies durable actor attribution for this event too; the client does not supply authored_by.

Submit a Custom-tool result

Use the SDK interaction helper so the event contains only the currently permitted Tool result, request correlation, and optional scope. Authenticated server context supplies durable actor attribution; client event bytes do not supply authored_by.

await submitCustomToolResult(checkfu, {
  sessionId,
  toolUseId,
  result,
  actor: {
    requestId: `custom-tool-result-${toolUseId}`,
  },
  idempotencyKey: `custom-tool-result-${toolUseId}`,
})

Keep application credentials inside the handler runtime and return only the bounded business result the Agent needs.

Make the application effect safe

toolUseId is replay-stable for the exact recorded call, but a local receipt written after a remote provider call is not atomic with that provider. A crash after provider acceptance and before the local write can repeat the effect. Use one of these patterns:

pass a provider-supported idempotency key derived from toolUseId;
durably reserve an effect intent before provider contact and reconcile its state; or
use an outbox or effect ledger with pre-effect intent and post-effect settlement.

A timeout or lost response after provider dispatch is indeterminate. Reconcile it with the provider before retrying rather than assuming the effect failed.

Reconciliation cases

Situation	What to do
The approval is already resolved	Show the durable outcome instead of answering again
The approval expired	Let the Agent request a new action if current authority permits it
A connected Tool schema or Connection revision changed	Re-request; the old decision describes different provider work
A required connected PermissionAssignment or Connection was revoked	Do not work around the denial; restore authority through its owning control-plane flow
A Custom-tool policy now denies	Do not execute the customer handler
A provider result is indeterminate	Reconcile before retrying

Use GET /v1/action-approvals for queue backfill and periodic reconciliation. Use Session events as the primary live signal so multiple review surfaces converge on the same durable decision.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Handle an approval

Detect the wait

Read the frozen decision

Respond once

Continue the correct path

Custom-tool approval continuation and proof custody

Tool confirmations

Submit a Custom-tool result

Make the application effect safe

Reconciliation cases

Detect the wait

Read the frozen decision

Respond once

Continue the correct path

​Custom-tool approval continuation and proof custody

​Tool confirmations

​Submit a Custom-tool result

​Make the application effect safe

​Reconciliation cases

Custom-tool approval continuation and proof custody

Tool confirmations

Submit a Custom-tool result

Make the application effect safe

Reconciliation cases