Human approvals

You added a human gate for exactly this reason: somebody should look before an agent moves money. The failure mode is not that nobody approved — it is that the thing approved and the thing that ran were different things. An approval that authorises a refund, rather than this refund of £240 on this order to this account, is a standing licence for every refund that agent proposes afterwards — and the agent proposing them is the component most likely to have been talked into it by a paragraph of retrieved text. The same holds for an approval that can be replayed: if the record survives its first use, one human decision authorises an unbounded number of executions of the action it was granted for, which is the shape of an incident rather than a control.

The second failure is quieter, and it is the one that makes your team switch the gate off. An agent waiting on a human has no callback to wait for, so it re-submits; a gateway that mints a fresh approval per re-submission buries your reviewer under duplicates of the single thing they are being asked to decide, and an approval nobody can find is an approval nobody spends. The queue then fills with rows that are individually valid and collectively unusable, and the honest response to that is to stop gating anything, which is where most human-in-the-loop features end up.

The third is money. A request parked on a human has been priced but not spent, and both obvious treatments are wrong: forget the estimate and an agent can queue a thousand expensive calls past its ceiling while somebody deliberates, or hold it forever and a denied or abandoned approval counts against that agent’s budget until someone edits the database by hand. Token Observe reserves the estimate for exactly as long as the decision is outstanding, and the transfer of that reservation onto the retry is a state machine rather than a convention.

An approval is bound to the SHA-256 of one canonical JSON object containing the governed action and the execution context it was proposed in, and to nothing else. Canonicalisation is what makes the comparison meaningful across two separate HTTP attempts: role grants are emitted with their permissions sorted and their action lists deduplicated and sorted, teams and on-behalf-of identities are lower-cased, tag sets are sorted, and header names are trimmed and lower-cased, so a retry that differs only in map ordering still hashes identically while a retry that differs in substance does not.

The context half is in the hash because changing any of it after a human reviewed the action changes what was approved. An approval granted to an agent holding one set of roles must not still be redeemable after that agent is granted more; an approval granted for a call made on behalf of one person must not be redeemable for the same call made on behalf of another; an approval granted at the end of a two-hop delegation chain must not be redeemable when the chain is different. Each of those is a fact about who is acting, and each of them is in the object that is hashed.

What is deliberately excluded is as load-bearing. Request ids, trace ids, credentials and generated transport session ids never enter the hash, because they change between the attempt that raised the approval and the attempt that redeems it. The proposed-tool-call path once salted the hash with the trace id, and because a trace id is minted fresh per request, every approval raised there was unredeemable: the operator approved, the agent retried, the hash no longer matched the stored one, and the guard raised a second approval — reproduced as a third on a third attempt. It failed closed, so nothing unsafe ever ran, but the documented feature had never once worked and the queue filled with rows nobody could spend.

Because the binding is a property of the action rather than of the attempt, the same envelope is computed by the model gateway and by the tool gateway — on the way in, and again on the retry. The offline seat hook is the one place it is not computed: that module is deliberately pure and holds no hasher, so it compares a hash the caller supplied against the frozen copy of the approval inside the signed bundle. An empty or wrong hash can never equal a granted approval’s, so a caller that omits it fails closed rather than open. An approval is a statement that this subject, with these grants, through this chain, may make this call with these arguments — once.

The agent sees a 403 in the error envelope of whichever dialect it speaks — OpenAI, Anthropic or Gemini — carrying the trace id, the typed code, the approval id, a retryable flag, a status URL and a resume object that states that the payload must match and that the approval is single-use. Those last two fields exist so the contract is machine-readable rather than folklore: an SDK integration reads the resume object instead of a paragraph of documentation, and the whole client-side change is one catch block that re-sends the identical request with the approval id.

The status URL is a read-only, agent-authenticated endpoint that returns lifecycle data only: the status, whether it is ready, retryable and terminal, the next action to take, the timestamps, and — once approved and unspent — the retry instruction. It never returns the payload hash or the human-facing action summary, it is served no-store, and a missing approval and an approval belonging to another agent collapse into the same 404 so the endpoint cannot be used as an approval-id oracle across the organisation. The next action is poll while pending, retry once ready, and stop when the matter is closed, which is the whole state machine an agent needs.

On the tool gateway the same contract arrives inside the protocol the model already speaks: a tool result flagged as an error, carrying the code, the retryable flag and the approval id in machine-readable metadata beside prose that names the approval id, its expiry and the instruction to repeat the exact call with that id attached. The refusal for an unknown or ungranted tool carries the same object in its protocol error, so a client can tell a pending approval from a kill switch, a budget stop or a policy block without parsing English.

Presenting an approval issued to another agent is treated as an escalation attempt rather than a typo: it is logged as an error and refused as a mismatch. On the tool gateway that refusal deliberately happens after the trace is opened rather than before, because it is the one refusal on that path with a named actor behind it — a probe or a replay — and it used to be the only refusal invisible to the flight recorder while every other one had already opened a trace.

The approvals queue defaults to what is awaiting a decision, and each card carries the action summary, the requesting agent, the policy that paused it, when it was requested, when it expires, a live countdown that turns amber at twenty minutes and red at five, the first sixteen characters of the payload fingerprint, and a link to the trace that led there. The queue is the critical read and is treated as such: the display-name lookups for agents and policies are independent requests, so a failed registry call degrades a name to a stable id rather than blanking approvals that still need a human, and decisions are disabled while the queue is showing a stale snapshot so an old pending state cannot be mistaken for a current one.

Deciding requires the operator role or above and an evidence scope covering the trace’s team, and a reason of at least five characters is mandatory — both buttons stay disabled until one is typed. Be precise about where that minimum lives: it is the console that insists on it, while the decision endpoint takes the reason as an optional field of up to 2,000 characters, so an install driving decisions through the API directly should enforce the same rule at whatever is calling it. The decision is written as a compare-and-set on the pending state, which matters more than it looks: without it, two people choosing the same outcome at the same moment would both be told they had decided and both be written into the audit ledger as the decider. The loser is told what the approval is now, and the decision that stands is recorded in the hash-chained audit log with the decider’s identity, the decision, the reason, the agent, the policy, the trace and the action summary, alongside an event published to whatever webhook, Slack, Teams or email receivers the deployment has configured.

The console is explicit that a decision is not an instruction. Approving tells the operator that the agent has to retry for it to take effect, because nothing calls the agent back; it used to say the agent had been told, which was not true of any channel the product has. An approved approval that has not yet been spent is shown as such, in its own pill, because the alternative is a queue reading approved while the work has not happened and an operator reasonably concluding that it did.

One disclosure belongs beside all of this rather than in a data-protection appendix. Where the approval was raised on a tool call the model proposed, the action summary is built from the tool name plus up to 160 characters of that proposal’s arguments, and it is built before egress redaction has run on the response — so the approvals table and the approval webhook can carry that much unredacted model-generated text, and should be treated at the same sensitivity as trace content. Approvals raised on the request path and on the tool gateway carry no arguments at all, only the tool or model name and the policy reason, and the summary is capped at 240 characters in every case.