0026. Escalate on outcomes through the tree¶
- Status: Accepted
- Date: 2026-10-09
- Source: PR #64 (commit cc59a32), recorded as D-26 in
DESIGN_DECISIONS.md
Decision¶
Some failures are signals about the model, not the request: structured output that never validates, or a sub-agent that fails.
An OutcomePolicy observes these outcomes and may return a Switch to another model.
The agent records an accepted switch as ConfigPart{Target, Reason} on the branch and sends a RouteDelta with the reason.
Recording it in the tree makes the switch hold for later turns, survive a reload, and appear in the audit trail.
A sub-agent failure is observed after the turn's tool results are recorded, so a switch never separates a call from its result.
Structured observes schema_invalid after its repairs run out, then repairs again on the new model, at most three switches per call.
A Switch can also carry dials, recorded as ConfigPart{Dials}, so a policy can raise reasoning depth on the same model before it moves to another one.
A switch is ignored only when it changes neither the model nor the dials, so a ladder that has reached its top ends the escalation.
Cancellation is not a failure and is never reported. A policy should be deterministic, because a durable run replays its outcomes.
The policy is not inherited by sub-agents. The parent observes a child's failure and decides for itself.