Operation approval and business uniqueness
This guide prepares the next build, under local qualification. Published distributions retain their current contracts.
Declare the requirement on the tool
module examples.protected_payment
type Payment
invoice_id is Text
vendor is Text
amount is Int
tool Pay
takes payment as Payment
gives Text
human.approve
with role as "finance"
with timeout_ms as 3600000
with distinct_from as "initiator"
strategy Execute
takes payment as Payment
gives Text
uses Pay
do
Pay
with payment as payment
into result
give result
Each call to Pay requires approval of its exact arguments. Imports, skills and
agent selection retain this requirement. The host attests identity and roles
through the adapter in Roles and deadlines.
The reviewer receives request.review_context.operation: tool, run, caller,
active agent and arguments. This information stays in the private decision record.
Approval releases one invocation. Rejection, expiry, checkpoint modification and
replay prevent dispatch. Grants, secrets, memory scopes and budgets remain
required. A human.approve checkpoint inside a strategy controls its continuation;
a tool requirement also covers other call paths.
A protected call consumes one max_tool_calls unit, retained through the wait
and resume. A limit of 1 allows one approved operation; a second call reaches
the limit. Parallel branches share the run budget. After changing tool imports
or policies, regenerate the artifacts with touba prepare --mode write.
Complementary checks
| Check | Implementation |
|---|---|
| Who may approve this exact operation? | Touba contract and trusted host identity adapter |
| Does the vendor and amount match the order? | Handler or service, against trusted business data |
| Was this invoice paid in another run? | Unique business key and atomic service transaction |
For SQL services, validate and write in the same transaction. A
UNIQUE(invoice_id) constraint protects overlapping submissions, even when each
has its own approval. For a remote payment service, send its idempotency key and
use its reconciliation protocol after an interruption. A local SQL transaction
does not make a network call atomic.
Retain provenance
Handlers receive context.executionContext in JavaScript and
context["execution_context"] in Python. Fields match:
run_id, caller_ref, agent_ref, agent_invocation_id.
Store this context and the call ID alongside the written record. Reads should
return that record's retained provenance. When no agent is active, the context
keeps the structural caller.
const provenance = context.executionContext;
const callId = context.request.call_id;
// Store provenance and callId with the write in the business transaction.
provenance = context["execution_context"]
call_id = context["request"]["call_id"]
# Store provenance and call_id with the write in the business transaction.
Memory scopes read and write are independent. A read-only agent cannot invoke
a write tool; an agent granted both scopes can write. Content validation and
separating published policies from agent-generated information belong to the
business service.
Execute and resume
touba run --project . --human-approval-host host/approval.mjs --effect-journal .touba/run.effect-journal.sqlite --human-checkpoint-out .touba/pending.json
Keep the host-custodied checkpoint, effect journal and business data together.
The CLI and SDKs apply the same approval checks. Server restarts retain the
pending request. The advanced linear RESUME-1 profile uses a different format
and rejects these nested continuations before effects; use human checkpoints
here. Reconcile an interrupted external effect with the service before retrying.