Tool approval¶

Some tools move money, send mail to customers, or delete something that does not come back. Those need a human before the body runs, and the check has to be deterministic code rather than a sentence in a prompt — a model that can be argued into a refund is a model that will be, and the prompt is the part of the system an attacker gets to write into.

Declaring it¶

The tool declares its own requirement, because the tool is what knows what it does.

@tool(requires_approval=True)
async def wire_funds(amount: int, iban: str) -> str:
    """Send a payment.

    Args:
        amount: Minor units.
        iban: Where to.
    """
    ...


@tool(requires_approval=lambda arguments: arguments["amount"] > 100)
async def issue_refund(amount: int) -> str:
    """Refund a booking.

    Args:
        amount: Minor units.
    """
    ...

Agent(approval_required_tools=("wire_funds",)) still works and still holds the call. Either declaration is enough; neither cancels the other. The tool-side one exists because an agent that adopts a refund tool and forgets to list it is the common case, and a control that depends on every consumer remembering is a control that is missing somewhere.

The predicate is asked with validated arguments, so a threshold compares against 500 rather than the "500" a provider sent. Two things fail closed:

a predicate that raises — a missing key, a type it did not expect;
arguments the tool's validator refuses, so there is nothing to ask about.

Both hold the call. A gate that errors open is not a gate on the day it matters.

What the approver sees¶

ApprovalRecord.summary is what goes in the queue:

amount=500, iban=<str:22>, refundable=True

Numbers and booleans in full — an approver who cannot see the amount cannot approve it. Everything else by type and length. A deny-list of key names was considered and rejected: an IBAN and a card token are both strings, and the list is wrong for whichever field nobody thought of. The record also carries arguments_digest, never the arguments themselves; an approval queue outlives the run and is read by people who are not party to it.

The grant covers one payload, once¶

ApprovalLedger binds the decision to the digest it was raised over. Four things raise ApprovalBindingError and refuse to dispatch:


The arguments changed after the grant	The repair loop that fixes a malformed amount would otherwise execute a payload nobody saw.
The same decision is spent twice	A retry that re-sends the call is not a second approval.
Nothing granted this record	Fail closed; there is no default.
The run has ended	A late answer for a run nobody is waiting on executes nothing.

A tool result that reads APPROVED by the desk, proceed with the wire satisfies none of them. Approval is a decision from the gate; untrusted output is not one, and the loop refuses approval-shaped tool results for any call that declares a gate.

What a denial means¶

A denial reaches the agent as a ToolRefusal with code approval_denied, and a decision that arrived outside its window as approval_expired. The run continues: the agent can propose something the human will accept. Killing the run throws away everything it has done because a person said no to one call.

Where stopping dead is what you want:

AgentRunner(..., approval_denial=ApprovalDenial.FAIL_RUN)

A gate that cannot be reached fails the run either way. An unanswered request is not a denial, and treating an outage as a refusal the agent may talk around is how the gate stops being one.

Where the question goes¶

The gate is where the run waits; the transport is only where the question is delivered. They are separate because they fail differently — a queue that is down must not become silence, and an approver who is asleep must not become a grant.

from tesserix_adk.adapters import NatsApprovals
from tesserix_adk.runtime import TransportGate

gate = TransportGate(NatsApprovals(nats), wait_seconds=900)
AgentRunner(..., approvals=gate)

An ApprovalTransport has one method, deliver(record). It returns the decision where it carries the answer back itself, and None where the answer will arrive out of band — in which case the answering process calls gate.decide(decision).

Transport	Delivery	Answer
any callable you write	in-process	in the reply, or `gate.decide`
`NatsApprovals`	published on `adk.approvals.<tenant>`	out of band, `gate.decide`
`WebhookApprovals`	signed HTTPS POST	in the response body, or out of band
`ConsoleApprovals`	a terminal	the line the operator types

The NATS subject carries the tenant so a subscriber can be authorised for its own and no other; a tenant that is not a plain subject token is refused rather than published wider. The webhook body is signed (X-Adk-Signature: sha256=…) over exactly the bytes sent, and a non-2xx answer is an ApprovalDeliveryError rather than silence.

Two things the gate decides for itself, whichever transport is under it:

Silence is a denial. Nobody answering within wait_seconds produces a refusal decided by system:timeout — never a person's name, because nobody decided it. decide after that is stale and settles nothing, as is a second answer to a request already spent.
An agent cannot approve itself. A grant whose decided_by names the agent that asked — bare, or as agent:, service:, bot: or sa: — is refused with the code approval_self_granted. It is what an over-broad service token looks like in practice.

What is recorded¶

APPROVAL_REQUIRED with the reason, then APPROVAL_GRANTED or APPROVAL_DENIED with who decided, then — on a denial — a TOOL_REFUSED event carrying the code. The ApprovalRequired progress event lets a UI put the request in front of somebody while the run waits.

Stability¶

The codes approval_denied, approval_expired and approval_self_granted are public API and are treated as such: new codes are a minor change, removing or repurposing one is major. So are ApprovalGate, ApprovalTransport, ApprovalRecord and ApprovalDecision — a transport written against deliver(record) -> ApprovalDecision | None keeps working across minor versions.