Skip to content

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.

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).

For a write, aidy runs these steps in order, and stops at the first failure:

  1. Validate the arguments against the operation’s input schema.
  2. Form: when the operation names a form, collect input from the user (Forms).
  3. Resolve names to ids (Resolve).
  4. Look up the resource name for the card (confirmation.lookup).
  5. Ask for approval: the run finishes with an aidy:approval interrupt.
  6. 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.

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"]
}
}
}
}

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 argsHash must 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, or status: "cancelled", never executes the write. A user who sends a new message instead sends cancelled for 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})

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.

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.