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

# Add human approval to your product

Present a pending external write and let an authorized person explicitly approve or deny it. Hexagon records the decision against the original Run; the worker delivers the Tool result. Your frontend must not also issue the external operation itself.

You need a Tool approval policy, a Run waiting for a decision, and a management identity permitted to decide. Ordinary application Tokens can read approvals but cannot submit decisions. This is not general organizational RBAC; your backend must authorize the business approver.

## Present the actual operation

Python `client.approvals(run_id)` and TypeScript `await client.approvals(runId)` return `approvals` containing id, run\_id, action, state, decision, and created\_at. Correlate Tool calls through approval\_id to inspect the invocation, arguments, and request hash.

Show the target account/service, operation, material arguments, task, and current state. Model-generated descriptions must not replace the actual parameters. Do not preselect approval or treat an account-authorization action as consent to a write.

## Build the approval card from persisted records

Fetch both the Run's approvals and Tool calls. Join a call's `approval_id` to an approval's `id`; do not select whichever approval happens to appear first. Use the approval's `action` snapshot for the binding, operation, arguments, connection ID and connection version being decided. Use Tool call details to show the request hash and execution state. Look up a display name through authorized connection metadata, without substituting its current configuration for the approval snapshot.

Show an actionable approval card only for a currently pending approval. `waiting_approval` on the Run alone is insufficient: a call with `state: unknown` requires an investigation view, and may have no new pending approval. A recorded approval means permission was granted, not that the external write succeeded. Continue observing the call and its `is_error` result.

If the bound connection version changes, the broker expires the prior approval and creates a new one when it reprocesses that operation. Refresh the card from the server and require a new explicit decision. Never copy an old decision onto a new approval ID automatically. Repeated clicks on the same decision may return its stored result; that does not bypass this new-version review.

## Submit an explicit decision

These backend functions assume an initialized, appropriately authorized client. Check business ownership first, and derive `approved` from the authenticated person's explicit choice.

```python theme={null}
def decide_selected(run_id, approval_id, approved):
    rows = client.approvals(run_id)['approvals']
    selected = next((row for row in rows if row['id'] == approval_id), None)
    if selected is None or selected['state'] != 'pending':
        raise RuntimeError('Refresh the approval state before deciding')
    return client.decide(approval_id, approved)
```

```typescript theme={null}
async function decideSelected(runId: string, approvalId: string, approved: boolean) {
  const { approvals } = await client.approvals(runId);
  const selected = approvals.find((row: { id: string }) => row.id === approvalId);
  if (!selected || selected.state !== 'pending')
    throw new Error('Refresh the approval state before deciding');
  return client.decide(approvalId, approved);
}
```

State can change between reading and deciding. The server is authoritative. On `stale_approval`, refresh the approval and Run; do not create a replacement to evade the guard.

## Repetition, expiry, and cancellation

An identical recorded decision returns its prior result. An opposite decision or invalid state cannot overwrite it. These example functions conservatively require pending state before calling; after a lost response, query stored state/decision to determine whether the original choice was recorded.

Cancellation expires pending approvals; late approval cannot revive the Run. An approved request already dispatched may have external effects that cancellation cannot reverse. Denial returns a Tool refusal for the Harness to handle; it does not automatically cancel the entire task.

Waiting can also represent an unknown Tool outcome. If a write was sent but its response was lost, inspect calls and [reconcile](https://github.com/NexusFox88/docs/blob/main/resources/docs/tool-reconciliation.md). Approving again is not a safe replay mechanism. Operator resolution requires actual external evidence.

## Verify the complete flow

With an authorized disposable test object, prove zero writes before approval, exactly one afterward with correct contents, zero after denial, no duplicate after repeated decisions, and no revival after cancellation. Refresh the page to confirm decisions survive independently of browser memory.

Audit the business actor, request, and returned decision without logging credentials. Separate simulated broker checks, actual third-party operations, and cloud Harness journeys; contract checks do not prove the entire production path.

Sources: [decision transaction](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/runs.ts), [Token route permissions](https://github.com/NexusFox88/docs/blob/main/resources/modules/credentials/application-tokens.ts). Next: [Tool authorization](https://docs.hexagon.autos/en/build/tool-authorization.md), [durable events](https://docs.hexagon.autos/en/build/stream-events.md).

## Recover a lost decision response

Keep the approval ID and the person's original choice in your application request record. After a timeout, query that Run's approvals again before presenting another action:

| Stored result | Interpretation and action |
| - | - |
| Same ID is `approved` and original choice was approve | Decision was recorded. Observe the Tool call; do not send the external write yourself. |
| Same ID is `denied` and original choice was deny | Refusal was recorded. Observe delivery to the Harness. |
| Same ID remains `pending` | The original choice can be submitted again after confirming current business authority; state may still race. |
| Opposite decision, `expired`, or no matching ID | Refresh and investigate. Do not reverse a recorded choice or copy it to another approval. |
| Run is cancelling or terminal | Do not revive execution. A repeated stored decision response is a receipt, not a new permission to dispatch. |

The server can return an identical historical decision even after the Run changes state. That idempotent response does not imply the operation just ran. Inspect the current call and any external outcome. A changed connection can invalidate the original approval while this recovery is in progress.

## Evidence for side-effect and cancellation boundaries

The [broker regression](https://github.com/NexusFox88/docs/blob/main/resources/modules/tools/broker.test.ts) counts writes to a controlled HTTP service: zero while unauthorized, zero while waiting for approval, one after valid approval, unchanged on cached replay and unchanged after denying a separate invocation. It also covers credential invalidation and replacement approval after connection changes. The [cancellation-race record](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-15-cancellation-races.md) documents the separate race checks; the [dated dual-SDK cloud journey](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-16-current-dual-sdk-journey.md) records approval during actual cloud execution with a controlled report service. These scopes do not constitute live acceptance for arbitrary third-party accounts or a fresh run of this page's snippets.

Next: [uncertain outcomes and recovery](https://docs.hexagon.autos/en/build/recovery.md), [credential and trust boundaries](https://docs.hexagon.autos/en/concepts/security-boundaries.md), [HTTP API](https://docs.hexagon.autos/en/reference/http.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.