AI-assisted — drafted and iterated with Claude Code (claude-sonnet-4-6). Lightly tested: unit tests pass, pnpm tsgo clean, pnpm check passes; fallback retry path validated by code review; not exercised against live quota exhaustion. I have personally reviewed all code changes prior to this commit and take responsibility for their correctness.

Summary

• Problem: when compaction hits a quota or rate-limit error on the primary model, the error surfaces directly to the session with no recovery path.
• Why it matters: users with aggressive compaction thresholds on paid tiers hit quota limits mid-session; without a fallback, the session stalls until quota resets.
• What changed: new agents.defaults.compaction.fallbackModel key. Set to "fallback" to retry compaction using the agents.defaults.model.fallbacks chain in order, skipping the current model. Defaults to "off".
• What did NOT change: auth errors and timeouts use their own retry mechanisms; fallback only activates on HTTP 429 / 402 billing errors.

Schema

agents.defaults.compaction.fallbackModel: "off" (default) | "fallback"

• "off": quota/rate-limit errors surface as-is.
• "fallback": retries each model in agents.defaults.model.fallbacks in order, skipping the current model. Re-throws after exhausting all candidates.

Renders as a two-button segmented control in the config UI, with a help tooltip.

UI — Before / After

Before (upstream main — no Compaction Fallback Model field):

After — new Compaction Fallback Model field with off / fallback segmented control:

Change Type

• Feature
• Docs

Scope

• Gateway / orchestration
• API / contracts
• UI / DX

Linked Issue/PR

• Discussion: #33431
• Companion: feat(compaction): disable thinking by default; add compaction.thinking override #34554 (compaction.thinking)

Key Changes

• compaction-fallback.ts (new) — resolveCompactionFallbackCandidates() resolves the ordered candidate list from config; filters out the current model
• compaction-fallback.test.ts (new) — 6 unit tests covering all states
• compact.ts — outer model-fallback loop wrapping the thinking-retry inner loop; transcriptPolicy and sanitizeSessionHistory re-resolved per candidate; before_compaction hook guarded by hookFired (fires exactly once per compaction event)
• compaction-overrides.ts — also ships resolveCompactionThinkLevel (companion to feat(compaction): disable thinking by default; add compaction.thinking override #34554); both features share this helper
• types.agent-defaults.ts / zod-schema.agent-defaults.ts — both fallbackModel and thinking fields narrowed to their 2-option unions

Notes for Reviewers

• The outer loop breaks on rate_limit/billing errors with remaining candidates; after exhausting all candidates the last quota error is re-thrown.
• before_compaction hook: guarded by hookFired so it fires exactly once regardless of model or thinking retry depth.
• transcriptPolicy and sanitizeSessionHistory re-resolved per candidate — provider-specific flags correct for cross-provider fallbacks.
• This PR includes the compaction-overrides.ts helper from companion feat(compaction): disable thinking by default; add compaction.thinking override #34554. If feat(compaction): disable thinking by default; add compaction.thinking override #34554 merges first, this diff will shrink accordingly.

User-visible / Behavior Changes

• New config key agents.defaults.compaction.fallbackModel (opt-in; defaults to "off", no change in behaviour).
• When set to "fallback" and compaction hits a quota error, it retries silently with the next model in the fallbacks chain.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No — uses existing auth resolution per candidate
• New/changed network calls? Only when a fallback is triggered (same API surface as primary)
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

1. Set agents.defaults.compaction.fallbackModel: "fallback" with a model.fallbacks chain
2. Exhaust primary model quota or simulate a 429 response
3. Trigger compaction → expect silent retry on next fallback model

Evidence

• 6 unit tests covering all resolveCompactionFallbackCandidates cases
• Live quota-exhaustion trace (not yet available)

Human Verification

• Verified: unit tests pass, pnpm tsgo clean, pnpm check passes
• Edge cases: absent config, "off", "fallback" with empty fallbacks, "fallback" filtering current model, hookFired guard across model and thinking retry loops
• Not verified: live quota exhaustion

Compatibility / Migration

• Backward compatible: fallbackModel is optional; default is "off" (no behaviour change)
• To enable: agents.defaults.compaction.fallbackModel: "fallback" with agents.defaults.model.fallbacks populated

Failure Recovery

• To disable: remove or set agents.defaults.compaction.fallbackModel: "off"
• Bad symptom: compaction retries when it shouldn't — check fallbackModel config value

Risks and Mitigations

• Risk: fallback model may produce a lower-quality compaction summary.
  • Mitigation: "fallback" is opt-in; users configure their own fallbacks chain.
• Risk: cross-provider fallback (e.g. anthropic → openai) could fail on provider-specific message formats.
  • Mitigation: transcriptPolicy and sanitizeSessionHistory are re-resolved per candidate.