What your agent should do after a checker says no.

The page is the resource. Free to read, print, and run against a system you already own. There is a runnable simulation behind it: two orchestrators, the same injected faults, and the twelve tests below.

Published 16 September 2026

An illustrative case, not a real incident. A customer uploads a receipt and asks for a refund of ₹1,200.

1. The receipt lookup times out and returns an empty result. The system records “no receipt”.
2. The agent recommends a refund. The checker rejects it: missing evidence.
3. The orchestrator retries the model three times. Each attempt is more confident. All three are rejected and the task escalates. The lookup itself is never retried.
4. On Monday a human opens the case, finds the receipt was there all along, and approves.
5. The payment call times out. The same retry policy fires three times. Every call reached the provider.
6. The customer is refunded ₹3,600. The orchestrator reports that the refund failed.

Plus two terminal outcomes. escalate — a named human or other owner must decide. stop — no justified path remains.

The root cause is a tool contract. The receipt lookup returned an empty value for both “there is no receipt” and “I could not look”. One return value, two different facts about the world, opposite correct responses. Every other failure in the story follows from that single collapse.

1. Q1

   Could an action with side effects already have executed?

   yes → uncertain_action

   Reconcile by idempotency key. Re-issue nothing.

2. Q2

   Is required evidence genuinely absent?

   yes → missing_evidence

   Ask the requester once. Do not regenerate.

3. Q3

   Is a dependency temporarily unavailable?

   yes → temporary_failure

   Retry the tool, inside the task budget.

4. Q4

   Can a named owner resolve it?

   yes → escalate / stop

   An owner, or an honest halt. Never a queue nobody reads.

Question 1 has two halves. A confirmed prior execution is not uncertainty — it is a policy conflict, and confirmed state beats any approval. Only an unconfirmed outcome is uncertain_action.

Side effects are asked about first, and the asymmetry is the argument. Misclassifying an uncertain action as a temporary failure invites a bounded retry, and retrying something that already ran is how one refund becomes three. The mistake in the other direction costs you a person looking at a case that did not need one. One is expensive and silent. The other is slow and visible.

The tempting column is not a straw man. Each one is the shortest correct-looking line of code at that branch, which is why it is what gets written.

A rejection that says “error” tells the next reader nothing, and the next reader is usually a retry loop. A record is what turns a rejection into a decision somebody else can make.

A record from the worst case in the kit

The refund timed out after the money moved, and the provider’s status endpoint is down. This is what the corrected design wrote.

{
  "record_id": "task-CASE-7731-R02",
  "task_id": "task-CASE-7731",
  "attempt": 2,
  "timestamp": "2026-09-16T09:00:00+05:30",
  "stage": "action.refund",
  "failure_class": "uncertain_action",
  "detected_by": { "type": "rule", "name": "reconciliation" },
  "reason": "the action may have executed and provider state cannot be read",
  "missing_evidence": [],
  "side_effects": [
    {
      "action": "refund",
      "target": "payment-provider",
      "idempotency_key": "task-CASE-7731:refund",
      "state": "unknown"
    }
  ],
  "permitted_next_actions": [
    "escalate with the idempotency key so a human can reconcile"
  ],
  "prohibited_actions": [
    "re-issue the action",
    "report the refund as failed",
    "report the refund as complete"
  ],
  "retry": {
    "attempts_used": 1,
    "max_attempts": 8,
    "deadline": "2026-09-16T09:02:00+05:30"
  },
  "next_step": "escalate",
  "owner": "refunds-duty-officer",
  "escalation": {
    "queue": "refunds-manual-review",
    "reason": "refund outcome unknown and the provider status endpoint is unavailable; reconcile by idempotency key before any re-issue",
    "respond_by": "2026-09-16T10:00:00+05:30"
  }
}

• The three prohibitions are the useful part. Two of them forbid reporting an outcome, in either direction, because both would be a guess.
• The idempotency key travels with the record. Without it the person who picks this up has nothing to reconcile against.
• state is “unknown”, not “failed”. The money did move. The system simply cannot see that yet, and says so.

Starting points, to be tuned against your own latency and cost budgets. None of these is a universal number, and a kit that handed you one would be lying about how much it knows about your system.

Retries multiply across layers, and nobody writes the product down.

Run this the moment a side-effecting call ends without a confirmed outcome. In order, and without skipping the first one.

1. Do not re-issue the action.

   Nothing you know yet justifies it. This is the step people skip under time pressure, and it is the one that costs money.

2. Query provider state by idempotency key.

   Not by customer, not by amount, not by timestamp. The key is the only handle on the specific thing that might have run. Most providers expire keys after a day or so, so keep your own reference beside it for anything reconciled later than that.

3. Decide on the confirmed state, not on the timeout.

   Confirmed executed: close against the existing reference. Confirmed not executed: re-issue under the same key.

4. If state cannot be read, stay uncertain and escalate.

   An unreadable status does not turn an unknown outcome into a known one. Escalate carrying the key, and report neither success nor failure.

5. Record the outcome, including the unresolved ones.

   The record is what makes the next attempt at this task, by a machine or a person, start from what is already known.

6. Make the action idempotent before the next incident.

   Reconciliation is the workaround. An idempotency key on every write is the fix, and it is a smaller change than it looks.

Inspect this instead, before any external call

• Provider state for this idempotency key, immediately before the call.
• The task’s own record of side effects, including any marked unknown.
• Whether another task holds a claim on the same case.
• Whether the action is inside its deadline and its budget.

Test T09 is the one to steal. It approves a refund the ledger already holds, and a design that issues it fails. Confirmed state beats a verdict, every time.

The cost is honest: checking state before every external call is one extra read on every call. Relying on the idempotency key alone is cheaper, safe within a task, and blind to what another task already did.

Twelve injections, each stating what it injects, the behaviour a correct design shows, and the smell a failure points at. Run against both designs. Every verdict below is a real run.

The naive design passed none of the thirteen. The corrected design passed all thirteen. T06 is split into two halves because the behaviour differs either side of the task deadline.

The failures are worth reading as assertions rather than as a column. T08 reported nine calls against a budget of four. T06a slept on its own guessed backoff and ignored the Retry-After the provider sent. T09 left two refunds in the ledger where the checker had approved one. T12 never retried the email, and a shared retry wrapper would have re-issued the refund to fix it.

Every assertion reads the payment provider’s own record of what happened, never what the orchestrator believed. The naive design believes it refunded nobody. That gap is the story.

It produces a list, not a refactor, and it needs no planning meeting to start. Bring the page, a whiteboard and whoever knows the tool surface.

1. 5 min

   Pick one agent and list its tools.

   The one in production, not the one you are proud of. Write every tool it can call.

2. 10 min

   Classify each tool by type.

   Read, write with an idempotency key, write without one, or irreversible and external. Most lists have more in the last two categories than the team expects.

3. 15 min

   Check each tool’s contract against three questions.

   Can the caller tell “not found” from “could not look”? Can it tell “did not run” from “may have run”? Does a failure ever arrive as an empty value or a bare exception?

4. 10 min

   Run T01, T04 and T08 against it.

   A read that times out while the data is present. A write that times out after it commits. A retry configured at two layers. Three injections, whatever your test harness is.

5. 5 min

   Write down what you found.

   One line per tool that cannot distinguish an outcome, and one line per retry you cannot account for. That list is the work, and it is usually shorter than the team fears.

The most common finding is not a missing retry. It is a tool that has been returning an empty value for two different situations since the day it was written, and a caller that has been treating them the same ever since.