commit_action

Gatekeeper — verifies the user actually approved a destructive action.

commit_action

The paired tool for confirm_action. Verifies that the user has explicitly confirmed a destructive action with a matching commit_token. Required gatekeeper before performing the destructive call.

commit_action only succeeds when:

• A matching confirm_action (same commit_token) was completed for this agent and subscriber
• AND the user explicitly clicked Confirm (not Cancel)
• AND the confirmation has not expired

Otherwise it returns a structured error and the destructive call must not happen.

Parameters

Name	Type	Required	Description
commit_token	string (8-64)	yes	The same commit_token passed to confirm_action.
side_effect	string (1-300)	yes	Brief description of the destructive call you’re about to make, for the audit log.

Returns

On success:

{
  "ok": true,
  "commit_token": "cancel_order_4231",
  "interaction_id": "...",
  "confirmed_at": "2026-05-18T10:32:00.000Z",
  "side_effect_recorded": "cancel order via Stripe refund"
}

On refusal:

{
  "error": "No confirmed user approval exists for this commit_token.",
  "details": {
    "commit_token": "...",
    "hint": "Either you never called confirm_action with this commit_token, the user has not yet clicked confirm, the user clicked cancel, or the confirmation expired. ..."
  }
}

Call from your own custom tool

export async function handle(input, ctx) {
  // Step 2: verify approval before the destructive call.
  const approval = await ctx.tools.commit_action({
    commit_token: `cancel_order_${input.order_id}`,
    side_effect: `cancel order ${input.order_id}, refund $${input.amount}`,
  });
  if (!approval.ok) {
    return { error: 'User has not approved this action.' };
  }
  // ...do the destructive thing here, e.g. POST to your refund endpoint.
  return { ok: true, refunded: true };
}

Notes

• Always registered.
• Cannot be bypassed by LLM narration — there is no path by which commit_action returns ok without server-side proof of consent.
• Scoped to the calling subscriber (or owner in preview).