Fallback model chains — third review closing the 06-09 loopCapability

One flag — --fallback-model — lets a headless claude run swap to a backup model (up to a comma-separated chain) when the primary is overloaded. Today's hands-on check: run_plan_day.sh gained network-wait and retry this month, but the fallback flag is still not wired — because the Jul 26 card that would adopt it is sitting unanswered in TTR.

When you run claude -p "/plan-day" headlessly, the run depends on one specific model being up. If Anthropic's side returns 'overloaded' (HTTP 529) or the model is temporarily unavailable, the run fails — and in a launchd context there is no human to notice and re-run it. --fallback-model tells Claude Code: if the default model can't answer, automatically try this other one instead. Since the July CLI updates it accepts a comma-separated list — --fallback-model "sonnet,haiku" tries each in order — so one flag buys you a chain of up to three models (primary + two backups) before the run truly fails. Verified in your installed CLI (2.1.220): the help text confirms the list form, and notes it only works with --print, i.e. exactly your headless case.

The key distinction is retry versus fallback — they cover different failure classes. The run_with_retry loop that landed in run_plan_day.sh (commit a727e1b, 'network-wait + retry') re-runs the exact same command up to 3 times. That's the right net for network flakiness — your documented root cause was the 06:15 cron beating Wi-Fi wake-from-sleep, and a second attempt 45 seconds later succeeds. But a provider-side overload is correlated across attempts: if Opus is overloaded now, it's very likely still overloaded 45 seconds from now, so all three retries burn against the same wall. Fallback sidesteps the wall by changing models instead of re-queuing at it. The two compose: retry handles 'the pipe was down', fallback handles 'the model was down'.

Today's hands-on verdict, checked against the real file: run_plan_day.sh does NOT have the flag. The claude invocation (line ~180) carries --settings, --strict-mcp-config, and the permission flags — no --fallback-model. run_weekly_review.sh: zero matches too. Why? The Jul 26 weekly-review card — whose decision #2, runner-hardening-pick, is exactly 'wire --fallback-model + auth-expiry detection into both wrappers' — is still sitting unanswered in FOR TOM/TTR/weekly-review-2026-07-26.html, five days old. The wiring is one line; the blocker is the unanswered card. (This rhymes with Friction 3 from that same card: the 06-28 card sat four weeks and stalled July's curriculum. Cards that gate one-line fixes are the cheapest ones to answer.)

Worked example

The check you can run right now, and the one-line change the Jul 26 card proposes:

# 1. Verify the current state (this is today's hands-on — run it yourself)
grep -n "fallback-model" /Users/tom/Claude/PDB/scripts/run_plan_day.sh \
                         /Users/tom/Claude/PDB/scripts/run_weekly_review.sh
# → (no output: the flag is not wired in either wrapper)

# 2. Confirm your CLI supports the chain form
/Users/tom/.local/bin/claude --help | grep -A6 "fallback"
# → "Accepts a comma-separated list to try each in order" (v2.1.220)

# 3. The change, once the card is answered 'adopt' — inside run_with_retry:
run_with_retry "${MAX_ATTEMPTS:-3}" \
    "$CLAUDE_BIN" \
        --settings '{"enabledPlugins":{}}' \
        --strict-mcp-config \
        --fallback-model "sonnet,haiku" \
        --dangerously-skip-permissions \
        --permission-mode bypassPermissions \
        -p "/plan-day"

• The grep is the whole audit: if it prints nothing, no wrapper has a model-level net. As of this morning it prints nothing.
• The --help check matters because the list form is newer than your 06-17 lesson — back then the flag took one model; now it takes a chain.
• One added line, placed with the other claude flags. Order is cheapest-acceptable last: try Sonnet (near-parity for planning), then Haiku (a degraded plan beats a stale today.html). The primary stays whatever your default model is — with Opus 5 now the CC default, the chain is effectively opus → sonnet → haiku, three models deep.

Gotchas

• --fallback-model only works with --print (-p). It's a headless-only net — adding it to your shell alias for interactive sessions does nothing.
• Fallback does not replace run_with_retry — keep both. Retry covers network failures (uncorrelated across attempts); fallback covers model overload (correlated). Dropping the retry loop because 'fallback handles failures now' would reopen the wake-from-sleep hole.
• A fallback model actually authors the plan. On a Haiku morning, expect a thinner plan — that's the accepted trade (degraded beats absent), but don't be surprised by it.
• Don't wire the flag before answering the card. The decision is already staged on weekly-review-2026-07-26.html; editing the wrapper silently would fork the record. Answer, drag back, then edit — the ledger stays true.
• Model outages are not auth failures. --fallback-model won't save a run when the OAuth token expired (the four dead mornings from the 07-27 lesson) — that's the other half of the same runner-hardening decision, and it needs its own detection.