Skip to main content
Version: 1.4.0

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​

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