Error Recovery and Retry Policy for the Agent Loop

The route

4 steps to Done

1. 01

   Build the error taxonomy

   Recovery starts with classification - each class gets a different answer.

   Preview prompt + verify gate ▾ Hide ▴

   Create an error taxonomy for my agent's tools. Classify every known failure into: TRANSIENT (timeouts, rate limits, flaky network - safe to auto-retry), CORRECTIVE (invalid arguments, file not found, lint failure - the model must adjust and retry), FATAL (permission denied at the harness level, missing credentials, unrecoverable environment issues - escalate to the user). For each tool, list its known failure modes and their classes, and mark which operations are non-idempotent (writes, sends, payments) and therefore need idempotency keys or read-back verification before any retry. Deliver the taxonomy table.

   • ✓ Every tool's failures classified
   • ✓ Non-idempotent operations flagged
   • ✓ Each class mapped to a recovery strategy
2. 02

   Implement retries and corrective feedback

   Machines handle transient noise; models handle their own mistakes.

   Preview prompt + verify gate ▾ Hide ▴

   Implement the first two recovery layers. Layer 1 (harness retries): wrap tool execution so TRANSIENT failures retry up to 3 times with exponential backoff plus jitter; retries are logged but do not consume model turns; non-idempotent operations verify state before retrying. Layer 2 (corrective feedback): CORRECTIVE failures return a structured error message to the model: what failed, the specific cause, and a suggested next step (e.g. 'file not found: src/auth.js - use find_file to locate the correct path'). Test both layers: a simulated flaky call that succeeds on retry 2, and a bad-args call that the model corrects on its next turn.

   • ✓ Backoff with jitter implemented
   • ✓ Retries logged without consuming turns
   • ✓ Corrective errors include cause + next step
3. 03

   Add the loop breaker

   The signature failure of autonomous agents is trying the same thing forever.

   Preview prompt + verify gate ▾ Hide ▴

   Implement loop detection. Track a rolling window of recent tool calls; if 3 near-identical calls (same tool, same or trivially varied arguments) all failed, interrupt before the next model call with a strategy-change message: 'You have attempted X three times with the same failure: [error]. Do not repeat it. Either take a different approach or report the blocker.' If the model attempts the same call again after the interrupt, block execution and force a plan revision. Also add a global error budget: after N total failures in a run, require the model to produce a status report before continuing. Test with a permanently failing command.

   • ✓ Near-identical detection tolerates trivial arg changes
   • ✓ Interrupt message names the repeated action and error
   • ✓ Second offense blocks execution
4. 04

   Build honest escalation and test the full ladder

   Ending well matters as much as running well.

   Preview prompt + verify gate ▾ Hide ▴

   Implement FATAL escalation and verify the whole ladder. Escalation produces a structured report: the goal, what was completed, what failed with final errors, what was attempted (including retry and loop-breaker history), and a recommended next action for the human. The run ends in a distinct 'escalated' state, never a fake success. Then run the full ladder test: a task that hits a transient failure (auto-recovers), a corrective failure (model recovers), a loop (breaker fires), and finally a fatal failure (escalates). Read the transcript and confirm each layer engaged in order and the final report matches reality.

   • ✓ Escalation report covers goal/done/failed/tried
   • ✓ Run state is 'escalated', not 'completed'
   • ✓ All four layers visible in one transcript

Research-backed

Sources behind this flow