approval architecture
Bind approval to the exact tool call that will execute
A human decision should authorize one reviewed action instance. Exact binding connects normalized inputs and policy evidence to a current, narrowly scoped execution authorization.
- For
- Developers and security engineers implementing human approval around AI agent tool calls
- Reviewed
- Jul 14, 2026
- Length
- 1,315 words
Turn the review decision into a narrow capability
“Approve the refund” is too broad for dispatch. A reviewer may have considered one order, amount, currency, and destination. Reusing that approval after substituting another order or amount breaks the connection between the human decision and the operation sent to the provider.
The approval object needs to identify the normalized tool call and the context that made the decision valid. At dispatch, the current request must match that binding, and its authorization must still be live and unused. This turns “a reviewer clicked approve” into a capability with a defined subject, action, payload, lifetime, and execution target.
What the approval binding needs to cover
- The tenant and requester identities derived for the supported request path.
- The normalized action or tool name and the identity of its input payload.
- The canonical request and policy decision identities where that adapter supplies them.
- The active policy, matched requirements, and review evidence used for the decision.
- Reviewer eligibility, required decision count, and separation-of-duties conditions when configured.
- A server-issued nonce, issuance time, and expiry so the decision is neither timeless nor interchangeable.
- The execution attempt and intended executor before authority crosses the dispatch boundary.
Define the action before computing its identity
A hash only identifies the bytes or fields you give it. Two adapters can represent the same operation differently, omit policy-relevant context, or accept caller fields that merely look trusted. Define the canonical action fields first, derive trusted identity and adapter context at the boundary, reject ambiguous input such as duplicate JSON keys, and then compute stable request and decision-input identities.
ActionProxy applies that normalization to HTTP, the JavaScript SDK over HTTP, authenticated stdio MCP, and the opt-in Streamable HTTP MCP adapter. Policy-relevant action and adapter context are derived at the server boundary. A caller-supplied agent identity is still an assertion rather than a cryptographically verified identity; adapters outside the documented Community surfaces are outside this guarantee.
Carry the binding from proposal to dispatch
- Build a canonical request from the concrete tool name, structured arguments, and trusted server or transport context.
- Evaluate deterministic policy and store the decision identity with the request rather than reducing the result to an unscoped approval-needed flag.
- Create the pending review with original input evidence, policy and decision identities, reviewer requirements, nonce, issuance time, and expiry.
- Present the meaningful structured fields to an eligible reviewer and record the decision against the same approval authorization.
- If a supported reviewer edits input, preserve the original identity, evaluate the edited payload, and make the approved identity the candidate for execution.
- Immediately before dispatch, reload current state, validate the request, decision, policy, payload, review, and expiry bindings, then reserve the execution attempt.
- Consume short-lived, one-use authority at the local executor or external-grant transition and record the reported outcome without an automatic retry for ambiguity.
Mismatches the executor should reject
- A different tool name or input identity from the reviewed action.
- A changed tenant, requester, decision, policy, approval, attempt, or executor identity.
- An expired approval, execution authorization, or external grant.
- A missing, foreign, replayed, or already consumed authority token.
- A stale pending record whose policy or review binding no longer validates.
- A second dispatch attempt disguised as recovery from an unknown first outcome.
One-use authority stops at the dispatch boundary
Consuming a grant once limits how ActionProxy crosses its dispatch transition. The downstream provider may still accept a request and lose the response, leaving the gateway with an unknown outcome. One-use authorization cannot make that provider operation repeatable or establish that a timed-out request had no effect.
ActionProxy authorizes one attempt for an action and does not automatically retry an unknown result. Provider-specific idempotency keys, status lookup, and reconciliation belong in the runner/operator integration around that provider. The runner may need to carry an idempotency key; the operator may need a lookup or takeover procedure. Neither should disguise an unresolved retry as a fresh action identifier.
Review the implementation with concrete tests
- Approve one payload, change each consequential field in turn, and verify that dispatch never invokes the executor.
- Change the active policy between review and finalization and verify that current policy is evaluated again.
- Exercise an authorized edit and confirm that both original and approved identities remain available in evidence.
- Attempt to reuse the same authorization against another action, attempt, executor, tenant, and process-local token consumer.
- Expire the review and external grant, then verify that neither can be revived by a stale queue worker.
- Simulate timeout after dispatch and verify that the outcome becomes unknown without an automatic second call.
Keep the same action identity across adapters and evidence
The AI agent approval gateway guide places exact binding inside the larger policy and execution lifecycle. For tool traffic using Model Context Protocol, MCP tool-call approval covers the stdio wrapper and opt-in HTTP adapter boundaries.
The same binding makes later investigation coherent: proposal, decision, human review, authority, attempt, and result can refer to one action identity. The AI agent tool-call audit trail guide follows that evidence path and explains the limits of ActionProxy's local hash chain.
Common questions
Questions developers ask
Which changes should invalidate a tool-call approval?
Reject changes to the tool or consequential input, tenant, requester, policy or decision evidence, approval requirements, attempt, executor, nonce, or expiry. An authorized edit should pass through an explicit revalidation flow and produce a new approved payload identity.
Should I hash the raw JSON request?
Define and validate the canonical action representation first. Raw adapter bodies can differ in field order, defaults, encoding, or trusted-context provenance. A stable identity is useful only when the normalized fields represent the authorization question you intend to ask.
What happens if policy changes after a reviewer approves?
ActionProxy reloads current state and validates the policy and decision binding before dispatch. If the request no longer satisfies current policy, the old review cannot silently authorize execution; the action must follow the resulting current lifecycle.
Who handles an unknown provider outcome?
ActionProxy records the unknown outcome and does not retry it automatically. Provider lookup, idempotency, reconciliation, and any explicit recovery procedure belong to the runner/operator integration, with care not to turn an unresolved operation into a seemingly new action.
