Approval & Confirmation UX

6 min read

H2
Playbook · Agent UX & Human Interaction

An approval is worth whatever record it leaves of what the human saw.

A dialog the user clears in under a second is not oversight, and you cannot prove it was — which is the same defect twice. Design the gate to emit a binding artefact instead of a boolean: the exact payload, its digest, who approved, what they were shown, how long they looked. That single artefact is simultaneously the control that stops payload drift, the evidence an auditor will ask for, and the only measurement that tells you whether anyone is reading.

Step 1Tier gates by consequence and reversibility, not by action type.

"Confirm before any write" is the anti-pattern that manufactures fatigue. What matters is not what kind of action it is but how bad the worst case is and how cheaply it can be undone:

  • Auto — reversible, low blast radius, in-distribution. Execute and log; no prompt. (Drafting, read-only queries, idempotent retries.)
  • Notify — consequential but reversible. Execute, surface prominently, offer one-click undo. (An internal message, a ticket.)
  • Gate — irreversible or high blast radius. Block on explicit human approval. (Money movement, external email, deletes, production deploys.)

Run the arithmetic on your own trace before arguing about the tiers. A forty-step coding or ops run with a confirm-every-write policy typically produces eight to twelve gates. If a reviewer spends a median of about a second on each — which is what a reflexive click looks like in your own latency data — you have bought roughly ten seconds of human attention spread so thin that none of it landed on the one step that mattered. Tier the same run to two gates and the same reviewer can spend thirty seconds on each and still finish faster. The quantity you are managing is a budget, and it is small.

The tier is a property of the decision, computed from risk and context, not a static flag on the tool — which is why it belongs in the same policy layer as everything else in blast radius, and why progressive autonomy treats the ladder as per-scope rather than per-agent.

Step 2Pin the payload, or you are confirming a different action than the one that runs.

The most common human-in-the-loop bug in production: the approval UI shows one set of arguments, the agent re-plans on resume, and the args mutate between approval and execution. The user approved an email to alice@; the executed call went to all-staff@. The fix is structural — freeze the exact payload at interrupt time, show that, and refuse to execute if the digest drifts.

# Approve the bytes that will run, not a regenerated paraphrase
payload = tool_call.freeze()
h = sha256(payload)
decision = await human.review(payload, digest=h)
if decision.approved and sha256(payload) == h:
    await execute(payload)
else:
    await abort("payload drifted or rejected")

This is where the shipping harnesses differ, and as of October 2026 none of them does it for you. LangGraph's interrupt() persists the graph state through a checkpointer and resumes with a Command; the OpenAI Agents SDK marks a tool needs_approval, surfaces a tool-approval interruption, and resumes from serialised run state; the Claude Agent SDK asks inline through a canUseTool callback behind hooks, allow/ask/deny rules and a permission mode (default, acceptEdits, plan, bypassPermissions). Every one of them pins the pause. None of them pins the arguments to the thing the human was shown — that comparison is the subject of the four-way approvals comparison, and the general failure is the approval was never bound.

Two consequences of resume semantics that bite in production. Treat a digest mismatch as a hard failure, never as a re-prompt. And make every gated tool idempotent before you ship approvals at all: resuming a run that had parallel interrupts has been a reported source of duplicated side effects in more than one framework, so "approved once" must survive being executed twice.

Step 3Emit an approval record, and make it the artefact — not a log line.

This is the step almost everyone skips, and it is the one that makes the other five provable. A boolean tells you the dialog closed. A record tells you what the oversight actually was, and it is the only version you can show an auditor, replay in an incident, or compute a metric from.

# The artefact the gate produces. Append-only, outside the agent's write surface.
{
  "approval_id":    "apr_01HQ…",
  "run_id":         "run_8f2c",       # which run, which step
  "step":           17,
  "tool":           "payments.transfer",
  "payload_digest": "sha256:9b1f…",    # the bytes, not a paraphrase
  "rendered_view":  "sha256:4c70…",    # what the human was SHOWN
  "tier":           "gate",
  "decided_by":     "u_4471",         # a person, not a service account
  "decision":       "approve",
  "dwell_ms":       860,              # the fatigue signal
  "policy_version": "tiers@2026-10-24"
}

Two fields do the unusual work. rendered_view is a digest of the presentation, not the payload: it is how you later answer "was the destination account visible, or was it collapsed behind a disclosure triangle?" — a question that decides liability and that no payload hash can answer. And dwell_ms turns fatigue from a hunch into a number you can alert on. Keep the stream append-only and outside anything the agent can write, for the same reason decision receipts and audit trails insist on it: a record the subject can edit is not a record.

Step 4Drive down the count; protect the dwell. Both come off the same record.

Once gates emit records, the two metrics that matter are computable on day one, and they move in opposite directions on purpose.

  • Approvals per completed task — drive it down. Batch homogeneous low-stakes actions into one reviewable list ("approve all twelve label changes"), and defer interrupts so the agent finishes the parallelisable safe work first and presents one consolidated decision instead of stuttering. A plan-level gate, as in plan review and editing, often replaces five step-level ones.
  • Median dwell on gated payloads — protect it, and alert when it falls. A p50 under about two seconds on a gate-tier action means the tier is miscalibrated or the queue is too long; the content of the dialog is not the problem. Watch it per reviewer too, because fatigue concentrates: the person who clears thirty gates a day is the one whose approvals mean least.

The ratio is the thing to report upward. "We cut approvals per task from eleven to two and median dwell went from 0.9s to 24s" is a statement about oversight actually happening. "We shipped an approval dialog" is not. Where approvals arrive as a queue rather than inline, the throughput design in review queues is the companion piece.

Step 5Defaults are the policy; irreversible actions need a different gesture, not a louder one.

Whatever the dialog pre-selects is what a fatigued user chooses, so the default is your safety policy regardless of what the docs say. Two rules: the default must be the safe, reversible option even though that costs a click on the common path; and never put a destructive primary action under the keyboard-Enter or muscle-memory position. The same logic condemns a blanket mode: a session-wide "accept everything" setting is a default applied to actions nobody has seen yet, which is why those modes belong to throwaway sandboxes and not to anything with production credentials.

For genuinely unrecoverable actions a yes/no modal is structurally too weak — it is the same gesture the reviewer has been clearing all day. Escalate the modality instead: re-type the target ("type the table name"), enforce a cool-down that makes the consequence concrete, or require a second approver for the top tier (the separation argument in separation of duties). Better still, engineer reversibility first.

Before adding a scarier confirmation, ask whether you can make the action reversible instead. A thirty-second send delay with undo converts most "irreversible" actions into reversible ones and removes the heavy gate entirely — the full argument is in undo and reversibility. A soft-delete plus undo beats the strongest modal that still gets reflex-clicked.

Step 6When not to add a gate at all.

If the action is cheaply reversible and low blast radius, a gate does not add safety — it adds fatigue that you then pay back on the gate that actually mattered. Delete it and spend the attention elsewhere.

Three more cases where the gate is the wrong instrument. When the reviewer cannot evaluate the payload — a diff of four hundred lines, a SQL statement nobody on the rota reads — the honest answer is a policy check on the arguments, not a human rubber stamp. When the approval is a grant rather than a single action ("let it use this connector"), it belongs in permission grants and revocation, where it can be reviewed and withdrawn, rather than in a modal that disappears. And when the action is routine and high-volume, the gate is a staffing decision in disguise — price the reviewer time before you ship it, as human-in-the-loop argues, because an approval queue nobody funds degrades into automatic approval within a fortnight.