ADR 0207: Allow Three Same-Path Mutation Recovery Failures

• Status: Accepted
• Date: 2026-09-10
• Related: D186, D379, ADR 0087, E2E-140, E2E-141

Context

The line-anchored mutation guard previously terminated a prompt after two counted failures for the same path. The first failure often exposes a syntax, range, or provenance correction, while the second failure can still be the agent applying that correction. Stopping at that point makes a bounded editing mistake harder to recover from than necessary.

Decision

Amend D186 and ADR 0087: a prompt may make three counted failed Edit calls on one path before the repeat guard terminates the turn. A recognized shell patch command uses the same three-failure limit under its patch-command key. The first and second counted failures return their normal error-specific recovery hints and leave the turn running; the third carries terminate: true and finalizes the assistant row with MUTATION_RETRY_BUDGET_EXHAUSTED.

The existing rules remain unchanged: recoverable error codes each receive one per-code grace, counters are scoped to the prompt and path, and a successful mutation clears that path's failure history. Provider retry budgets and other tool concurrency limits are unaffected.

Delegate ownership correction (2026-10-07)

The prompt scope means the individual executing agent, not the whole session. Sharing path keys caused concurrent delegates to spend one another's attempts and report exhaustion on the parent. Recovery keys now include the parent or delegation owner; parent restarts do not reset detached work. Settlement releases the delegate's counters and graces. A terminal tool error is carried to the delegate result so earlier prose cannot classify an exhausted run as completed. The failed chain and its report remain resumable through the existing Task flow.

Consequences

• The model gets one additional bounded opportunity to correct an Edit or recognized shell patch failure.
• Persistent or guessing mutation loops still terminate deterministically.
• The runtime error message and every shipped locale must say three failures.
• No IPC, storage, host protocol, or tool result shape changes.

Alternatives considered

• Keep the two-failure limit: rejected because the second correction attempt can still be an honest recovery after a distinct first error.
• Remove the limit: rejected because malformed or blind mutation loops must not consume an unbounded turn.

Verification

• Runtime unit tests cover Edit, shell patch, per-code grace, reset after a successful mutation, and the visible terminating error row.
• E2E-140 and E2E-141 document the third-failure boundary.