Implement a bounded tool workflow with authorization and human approval

Implement a workflow that may draft and send a customer refund request. The model may propose a tool call, but application code must validate arguments, load authoritative order data, authorize the actor, and require human approval before the external side effect. The workflow must resume safely after a crash or duplicate delivery without issuing the refund twice.

Model proposes refund(order_id=812, amount=50, reason="duplicate charge")
Application loads order 812, derives refundable amount, checks actor permission, and stores a pending action
Approver sees the exact normalized action and approves action version 3
Worker executes with idempotency key workflow-44:action-3; duplicate delivery returns the same outcome.

• Treat tool arguments as an untrusted proposal, never as authorization or authoritative state.
• Use allowlisted tools with strict schemas and server-derived tenant, actor, and financial values.
• Persist workflow and action state before requesting approval or performing side effects.
• Bind approval to an immutable action version so later changes require new approval.
• Use a stable idempotency key and reconcile ambiguous external outcomes.
• Limit steps, tool calls, elapsed time, and spend, with explicit terminal states.

1. Parse the model proposal into a closed tool contract and reject unknown tools or fields.
2. Resolve trusted context, run authorization and business validation, then normalize the action.
3. Persist a versioned pending action and present its exact effect to an authorized approver.
4. On approval, atomically claim the action and execute it with a stable idempotency key.
5. Persist the external result before advancing workflow state; reconcile timeouts instead of guessing.
6. Stop on terminal outcome or budget exhaustion and record a safe audit trail for every transition.

async def handle_proposal(workflow_id: str, proposal: ToolProposal, actor: Principal):
    contract = TOOL_REGISTRY.require(proposal.name)
    arguments = contract.schema.validate(proposal.arguments)
    order = await orders.load_for_tenant(arguments.order_id, actor.tenant_id)
    authorization.require(actor, "refund:propose", order)
    normalized = refund_policy.normalize(order, arguments)
    return await workflows.store_pending_action(workflow_id, normalized)

async def execute_approved(action_id: str, approval: Approval):
    action = await workflows.claim_if_approved(
        action_id,
        approved_version=approval.action_version,
        approver_id=approval.actor_id,
    )
    if action.is_terminal:
        return action.result

    key = f"{action.workflow_id}:action:{action.version}"
    try:
        result = await payments.refund(
            payment_id=action.payment_id,
            amount=action.amount,
            idempotency_key=key,
            timeout_seconds=8,
        )
    except AmbiguousTimeout:
        await workflows.mark_reconciliation_required(action.id)
        raise
    return await workflows.complete_once(action.id, result.external_id)

Each transition performs bounded indexed reads/writes plus at most one external action attempt. Step, time, and spend budgets cap workflow growth; durable history grows O(number of transitions).

• The order changes after proposal creation but before approval.
• An approver approves version two while the workflow has already produced version three.
• The provider accepts the refund and the worker times out before recording success.
• Two workers receive the same approved action concurrently.
• The model proposes a valid tool with an order from another tenant.

• Modify an action after approval and require a new approval for the new version.
• Deliver the execution message twice and verify one external refund identity.
• Use a cross-tenant order ID and ensure it fails before any provider call.
• Simulate an ambiguous timeout and require reconciliation rather than immediate re-execution.
• Exhaust the tool-call budget and verify a clear terminal state with no side effect.

• A model selecting a tool does not mean the user is authorized to run it.
• Approving a vague natural-language plan does not bind approval to the actual side effect.
• Keeping workflow state only in conversation history cannot recover safely after a crash.
• Generating a new idempotency key on every retry can repeat the refund.
• An autonomous retry after an ambiguous outcome can turn uncertainty into a duplicate action.