HITL gates for agent mutations

Agents are optimistic. They call a tool, see a JSON blob that looks success-shaped, and tell the user “refund sent.”

Sometimes the refund is pending. Sometimes the tool returned a structured error the model ignored. Sometimes the write never happened.

Human-in-the-loop (HITL) gates and post-mutation verification are how you stop early victory. The model can propose. Policy decides. The system checks reality before anyone celebrates.

This is the mutation half of MCP first: tools without judgment burn money.

Pair with idempotency, structured tool errors, auth and audit, and commerce paths in secure agentic commerce.

Which mutations need a gate

Not every tool needs a human. Read-only lookups should be fast. Mutations that move money, stock, or trust should slow down.

Thresholds are product decisions. A small shipping adjustment is not the same as a large refund. Encode ceilings in policy config, not prompt text.

For Shopify-style claims and refunds, the same idea shows up as queue triage with human resolution (claims pipeline). Auto-clear the easy half; keep edge cases for people.

Gate shapes that work

There are four shapes that hold up in production:

1. Pre-tool approval: agent prepares a proposed_action payload; UI or Slack asks a human to approve; only then does execute_refund run with the approval id.
2. Two-step tools: draft_refund (safe) then commit_refund (requires approval_token).
3. Async review queue: mutation creates a pending record; worker waits for approve/deny; agent polls status.
4. Policy auto-approve: small, low-risk, fully validated cases skip the human but still write audit + verification.

Bind every approval

Always bind approvals to:

• Actor (who asked)
• Tenant
• Exact action hash / idempotency key
• Expiry (stale approvals must not run tomorrow)

Do not let the model invent an approval_id. Issue it from your system after a real human (or policy engine) decision.

Anti early-victory: verify after tools

The failure mode is consistent across stacks:

1. Tool returns something the model interprets as success.
2. Model narrates completion to the user.
3. Downstream system never applied the change (validation, partial write, wrong environment).

What a second read looks like

Verification is a second read (or event) that proves the world moved:

• After refund: fetch order transactions / refund set; confirm amount and status.
• After inventory adjust: read InventoryLevel (or your source of truth); confirm quantity.
• After spend: read ledger entry or checkout status; confirm completed not open.
• After key rotate: confirm old key rejected and new key works in a dry probe.

Put verification in code the agent must call (or that your tool runner calls automatically), not only in a skill paragraph.

Pattern for a tool runner:

authorize -> idempotency begin -> mutate -> verify -> audit -> respond

If verify fails, return a recoverable structured error (verification_failed) with what was expected vs observed. Do not return a soft “ok” with a warning buried in prose.

Where HITL sits in MCP / UCP

• Your SaaS MCP: gate inside the tool or a preceding approval tool; never expose bare Admin credentials to the model (secure agentic commerce for the commerce variant).
• Shopify UCP checkout: complete_checkout already sits behind trust tiers and permissions (agent profiles, buyer-linked tokens). Still verify order state before telling the buyer “paid.”
• Laravel MCP: combine gates with idempotency so a double-approved click cannot double-refund.

Stateless servers (stateless MCP) make this cleaner: approval records live in your DB, not in a vanished MCP session.

Implementation checklist

1. Classify tools: read / low-risk mutate / high-risk mutate.
2. Define numeric ceilings per tenant for auto-approve.
3. Require approval_id (system-issued) on high-risk commits.
4. Expire approvals; bind them to idempotency keys.
5. Auto-verify after mutate; fail closed on mismatch.
6. Audit propose, approve, execute, verify as separate events.
7. Teach skills: “never claim success without verify tool result.”
8. UX: show the human the exact payload (amount, SKU, customer) before approve.

When your agent last said “all done,” did the ledger agree within a second, or did a human discover the gap in a support ticket two days later?