Skip to main content
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.
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. 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, Token route permissions. Next: Tool authorization, durable events.

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: 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 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 documents the separate race checks; the dated dual-SDK cloud journey 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, credential and trust boundaries, HTTP API.