Approvals
A write waits for the user. The decision is made in runtime code from the catalog, and the approval binds to a hash of the exact arguments the user saw. A resume cannot change them, and an approved call runs at most once.
Policy in code
Section titled “Policy in code”An operation needs approval when its approval is always. That is the default for every
effect other than read (Operations and effects). The model
cannot skip it: no prompt, tool description or model output takes part in the decision. Your
host checks it a second time, because an assertion for an approval: always operation must
carry the approval id apr (Delegation).
What happens before the card
Section titled “What happens before the card”For a write, aidy runs these steps in order, and stops at the first failure:
- Validate the arguments against the operation’s input schema.
- Form: when the operation names a
form, collect input from the user (Forms). - Resolve names to ids (Resolve).
- Look up the resource name for the card (
confirmation.lookup). - Ask for approval: the run finishes with an
aidy:approvalinterrupt. - Execute once the user approves.
Nothing reaches your API as a write before step 6. A failed lookup aborts the call before approval, and nothing runs.
Frozen arguments and argsHash
Section titled “Frozen arguments and argsHash”At step 5, aidy freezes the validated arguments and computes:
argsHash = base64url(SHA-256(JCS(arguments)))JCS is the JSON Canonicalization Scheme, RFC 8785: keys sorted, no whitespace, numbers in their shortest form, so every implementation produces the same bytes. aidy persists the approval with the frozen arguments and the hash, and puts both in the interrupt:
{ "id": "int_…", "reason": "aidy:approval", "message": "Stop server gpu-train-01?", "toolCallId": "call_…", "expiresAt": "2026-11-19T08:15:00Z", "responseSchema": { "type": "object", "properties": { "approved": { "type": "boolean" } }, "required": ["approved"] }, "metadata": { "aidy": { "op": "stop_vm", "arguments": { "vm_id": "vm-42", "forced": false }, "argsHash": "q2…", "impact": { "title": "Stop server gpu-train-01?", "target": "gpu-train-01", "effect": "update", "risk": "medium", "costHint": null, "changes": ["Force: No"] } } }}Resuming
Section titled “Resuming”The client answers in the next run’s resume[], echoing the hash it showed:
{ "interruptId": "int_…", "status": "resolved", "payload": { "approved": true }, "metadata": { "aidy": { "argsHash": "q2…" } }}- The echoed
argsHashmust equal the stored one. If it differs, nothing executes. - aidy executes the frozen arguments. A resume cannot substitute arguments.
- Each approval executes at most once, even when two workers race: the approval is consumed with a compare-and-set on its status.
approved: false, orstatus: "cancelled", never executes the write. A user who sends a new message instead sendscancelledfor each open interrupt alongside it.- An approval expires after 15 minutes (
expiresAt).
A confirmed write always finishes and is recorded: a run outlives its HTTP response, and only
POST /aidy/v0/runs/{id}/cancel stops it.
The Python kit and @aidy-dev/spec expose the same hash for hosts and tests:
from aidy import args_hash
args_hash({"vm_id": "vm-42", "forced": False})The confirmation card
Section titled “The confirmation card”confirmation shapes the card. Templates take {argument} placeholders and
{resource_name}:
"confirmation": { "title": "Stop server {resource_name}?", "target": "{resource_name}", "fields": [{ "key": "forced", "label": "Force", "values": { "true": "Yes", "false": "No" } }], "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" }, "risk": "medium", "costHint": "Billing continues for disks."}| Key | Meaning |
|---|---|
title |
Required. The card’s question. |
target |
The resource acted on. Defaults to {resource_name} when there is a lookup. |
fields |
Arguments to show, with a label and optional display values. Each becomes a line in impact.changes (Force: No). |
lookup |
An authenticated GET, made as the user before the card is shown. labelPath in its response becomes {resource_name}. |
risk |
low, medium or high. |
costHint |
A short note on cost. |
The lookup path must be served by a GET operation in the catalog, because every call aidy
makes names the operation it calls. Lookups let the card say “Stop server gpu-train-01?” when
the model only passed vm-42.
Impact
Section titled “Impact”metadata.aidy.impact is what the card shows: title, target, effect, risk,
costHint and changes, rendered from confirmation and the frozen arguments.
@aidy-dev/react’s ApprovalCard renders it. MCP clients see the same title, target and
changes in their elicitation prompt, and the CLI prints them on the terminal.
Related
Section titled “Related”- Delegation: the
aprclaim your host checks. - AG-UI profile: interrupts and resume.
- React guide:
ApprovalCard.