> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# commit_action

> Gatekeeper — verifies the user actually approved a destructive action.

# commit\_action

The paired tool for [confirm\_action](/builtin-tools/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```js theme={null}
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).