Handle an approval

Detect that a Run is waiting on a human, present the decision, and resume.

When governance requires review, the Run parks instead of failing. Your product has to notice, show someone the decision, and answer. This guide implements that loop.

The loop

CHECKFU_API_KEY and CHECKFU_WORKSPACE_ID come from Get access, and APPROVAL_ID is the approval_… the wait event carried. The TypeScript snippets below use the TypeScript SDK with this client:

import { Checkfu } from "@checkfu/sdk"

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

1. Detect the wait

   Watch the Session stream for run.requires_action. Key off the action payload, not the Session status. session.status_waiting tells you the Session is parked, but only the action tells you what it is parked on.

   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,
           customToolAfterActionApproval:
             action.on_approve?.kind === "custom_tool",
         })
         break
       case "custom_tool":
         // This tool needs a result, but governance did not require review.
         await answerCustomTool(action.tool_use_id)
         break
       case "question":
         // Ordinary input, not authority. It also needs a human, and the
         // Session parks indefinitely until one posts user.question_answer.
         await answerQuestion(action.question, action.items)
         break
       // outcome_evaluation resumes on its own.
     }
   }
   
2. Show the reviewer what was frozen

   action_approval.pending carries the frozen context, and GET /v1/action-approvals/{id} returns the full record including context_summary.

   Branch on that context before rendering it:

   • A ToolInvocation ActionApproval names the Connection, tool and source versions, outbound scheme, host, port, method and path, Session, Run, and acting Principal. It carries no query string, headers, body, or argument values; arguments appear only as arguments_hash.
   • A Custom-tool ActionApproval has context_summary.kind === "custom_tool". It names the admitted agent definition and version, nullable installation and surface, tool_use_id, and logical tool name. It has no Connection, ToolSource, or outbound request. Read the exact arguments from the preceding agent.tool_use event when building the review; execute them only after authority is granted.

   Do not force both variants into one review-card shape. The ActionApprovals concept lists the complete frozen contract for each.

3. Respond

   cURL

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

   A CapabilityGateway approve response carries one deterministic, single-use proof token. A Custom-tool approval and every denial return no proof. Idempotency-Key is optional, but using a stable value preserves an encrypted copy of the exact HTTP response for retries.

   GET /action-approvals/{id} never reveals a CapabilityGateway proof. Preserve a CapabilityGateway approve response. If delivery is lost, retry the exact same decision and reuse the Idempotency-Key when supplied. The keyed receipt can replay the captured response for up to 24 hours, but it does not extend proof expiry or make a consumed proof usable. This warning does not turn a proof-free Custom-tool response into a bearer credential.

4. Continue the correct branch

   For a CapabilityGateway decision or a Custom-tool denial, action_approval.resolved lands in the log, followed by run.resumed; the normal continuation tells the harness whether the tool action was approved or refused. Do not treat a denial as a Session failure.

   An approved Custom-tool action is different. Wait for run.action_authorized, correlate its tool_use_id to the exact preceding agent.tool_use, execute that recorded tool action in your application, and post its result:

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

   ActionApproval alone does not start a Run, dispatch, lease, or Sandbox for this branch. The same compute-closed Run stays parked after run.action_authorized; the matching user.custom_tool_result is what closes that wait and admits the ordinary continuation Run.

Handling the awkward cases

Situation	What you see	What to do
Two reviewers open the same item	The second POST fails on expected_version	Re-read the ActionApproval; if it is already resolved, show the outcome
The reviewer took too long	Status expired	Nothing is redeemable. The Run must re-request the tool action
A CapabilityGateway tool source re-synced mid-review	Redemption refused on context mismatch	Re-request; the reviewed tool action no longer matches what would execute
A CapabilityGateway Connection was reauthorized mid-review	Redemption refused on context mismatch	Same: re-request

The last two are the freeze doing its job. An approval is a decision about one exact tool action, and any change to that tool action invalidates it rather than approximating consent.

Building the queue

For a live queue, drive off the event log rather than polling GET /v1/action-approvals. action_approval.pending tells you an item appeared; action_approval.resolved tells you it was answered, including when someone else answered it first. That is what keeps two open review tabs from fighting.

Use the list endpoint for backfill and reconciliation, not as the primary signal.

Next steps

ActionApprovals

The freeze, the proof token, and the governance checks that produce a review.

Resume a stream

Make sure you never miss the wait event in the first place.