@ferris1225/pi-subagents 0.29.0 → 0.32.2

package/README.md

@@ -17,30 +17,44 @@ on its own — no prompt engineering, no babysitting.
   into the main system prompt, so the main model automatically sends broad searches
   to `explore`, self-contained implementations to `worker`, and pre-commit reviews
   to `reviewer`. You just use pi; delegation happens by itself.
-- **Vision-capable image tasks** — a task that may need to view screenshots,
-  mockups, or design files is flagged `vision: true`; the sub-agent then runs on
-  the vision model you configure in `/subagents-setup`. Not configured? It falls
-  back to the main session's current model. Configured model unavailable? You are
-  asked to pick a replacement, which is persisted. The agents know they can `read`
-  image files when the brief asks.
+- **Vision-capable image tasks** — flag screenshot/mockup/design work with
+  `vision: true`. The configured vision primary is followed by that agent's
+  backup and the current main-window model. The setup picker offers only
+  image-capable models (while clearly marking an incompatible stale saved ref),
+  and runtime failures never silently rewrite your configuration.
 - **Results come back on their own** — completions are delivered as messages that
   wake the main agent automatically, even mid-turn. No polling, no `sleep`, no
   "go check" step. `subagent_wait` is a **non-blocking** in-turn lookup by default
   (pass `timeoutMs` to block); `subagent_status` inspects runs; `subagent_stop`
   cancels one and delivers its partial output.
+- **Results are not re-narrated** — a sub-agent's completion is shown to you
+  verbatim, and the main agent is told not to paraphrase it back. It replies with
+  only its own conclusion or next step, so the same findings are never paid for
+  twice in tokens.
 - **A quality gate that closes the loop** — when a reviewer returns `REVIEW_FAIL`,
   the extension dispatches a worker briefed with the concrete findings, then a
   re-review, up to `maxFixRounds` times — and only then wakes the main agent.
-- **Self-healing model management** — unavailable configured models are repaired
-  and persisted automatically; a provider hiccup retries the same model up to 5×
-  with backoff, then falls back once to the main window's model; terminal errors
-  (quota/auth) short-circuit straight to the main agent; an idle watchdog kills
-  runs that go silent; startup races are retried with backoff.
+  Every round stays in the triggering reviewer's cwd, and chains that target the
+  same repository are serialized so shared-checkout edits cannot race.
+- **Ordered model pools without config churn** — each agent can have a primary
+  and backup; the current main-window model is the final candidate. Transient
+  provider failures retry the same candidate with backoff, while permanent stale
+  model/config errors and quota/auth errors advance immediately. Saved refs are
+  never rewritten behind your back.
+- **Resumes, retargets, and forks preserve context** — every run is session-backed.
+  `subagent_control` can steer active work, retarget it after a stable abort,
+  park/resume it under the same run id, or fork a parked/settled checkpoint into
+  a new independent run. Concurrent resume calls are serialized.
 - **Honest completions** — a run that ended with failed tool calls (e.g. a broken
   build) is reported as `completed with N failed tool call(s)` with the errors
   attached — a cheerful final text can never hide a failure.
-- **Parallel fan-out** — independent tasks run concurrently up to a configurable
-  limit (default 4).
+- **Parallel fan-out with filesystem isolation** — independent tasks run up to a
+  configurable limit (default 4). Parallel workers default to detached Git
+  worktrees; tracked, deleted, untracked, and binary changes are applied back
+  without touching the parent index. Failed integration keeps recovery artifacts.
+- **Live inspector** — `/subagents-inspect` opens a master/detail
+  overlay with thread state, model chain, usage, transcript, recent tools,
+  worktree/fork relations, and the append-only control trajectory.
 - **Live progress widget** — each run's status, current activity, model, token
   usage, and elapsed time; auto-fix chain rounds hang under their triggering
   review as a tree, each finished round keeping a one-line outcome.
@@ -113,32 +127,68 @@ subagent({
 });
 ```
 
-The sub-agent reads the images with its `read` tool. Model selection for
-vision-flagged runs: configured `visionModel` → main session's current model →
-agent's own model. When a configured vision model is no longer available, the
-TUI asks you to pick a replacement (persisted); outside the TUI it warns and
-falls back. A vision-flagged auto-fix chain keeps its worker/re-review rounds on
-the vision model too, since they re-read the same images.
+The sub-agent reads images with its `read` tool. Runtime order for a
+vision-flagged run is configured `visionModel` → that agent's configured backup
+→ current main-window model (deduplicated). A stale configured ref is attempted
+once, then skipped as a permanent candidate error; it is not rewritten. A
+vision-flagged auto-fix chain keeps the flag for worker/re-review rounds because
+they may need to inspect the same images.
 
-### Waiting, inspecting, stopping
+### Controlling, inspecting, and stopping
 
+- `subagent_control` — `steer`, `retarget`, `park`, `resume`, or `fork` a logical
+  thread by stable run id. Resume accepts an optional replacement objective;
+  fork creates a new id and leaves the source unchanged. Park active work before
+  forking it.
 - `subagent_wait` — in-turn result lookup. **Non-blocking by default**: a settled
-  run returns its result immediately; a still-active run tells the model to end
-  its turn (the wake-up message arrives on its own). Pass `timeoutMs` only when
-  you must stay in the turn.
-- `subagent_status` — what is running now, what finished this session, full
-  result by run id.
-- `subagent_stop` — cancel a run (or all); the child is terminated and an aborted
-  result with partial output is delivered.
+  run returns immediately; an active run tells the model to end its turn. Pass
+  `timeoutMs` only when you must stay in the turn.
+- `subagent_status` — active/parked/finished runs and full result by run id.
+- `/subagents-inspect` — interactive live thread/transcript/tool/trajectory
+  overlay; press `p` to park or resume the selected thread.
+- `subagent_stop` — destructive cancellation. It retires that thread's retained
+  session (independent forks survive) and delivers exactly one aborted partial
+  result after the run and any worktree integration have quiesced.
+
+Examples:
+
+```ts
+subagent_control({ action: "steer", id: 7, instruction: "Check the Windows path too." });
+subagent_control({ action: "park", id: 7 });
+subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
+subagent_control({ action: "fork", id: 7, objective: "Try the smaller alternative." });
+```
+
+### Worktree isolation
+
+Single tasks default to `isolation: "shared"`. Parallel `worker` tasks default
+to `isolation: "worktree"`; opt into shared mode only when a worker must see the
+caller's live uncommitted tree. Worktree mode requires a Git repository with a
+committed `HEAD` and is rejected for read-only agents.
+
+A parked isolated thread keeps its current worktree. Resume it there; fork is
+available after that isolated checkpoint settles and its seed is integrated.
+Resuming or forking a settled isolated thread creates a fresh worktree, merges a
+recorded checkpoint onto the current `HEAD` (including when the seed was already
+committed), and clones the Pi session with the new cwd. Forks then integrate only
+their unique follow-on edits, so a shared seed is applied once. A run remains
+active while final Git integration is in progress and becomes `done` only after
+that boundary finishes.
+
+Every Git operation has a 120-second deadline and process-tree cleanup; captured
+Git output and binary patches are capped at 64 MiB. Setup/bound failures surface
+instead of hanging. Finalization failures retain the patch/worktree when
+available and are recorded in `~/.pi/agent/pi-subagents-recovery.json`; later
+sessions show the recovery paths again until the artifacts are removed.
 
 ## Configuration
 
 Stored at `~/.pi/agent/pi-subagents.json` (follows `PI_CODING_AGENT_DIR` when
-set). The `/subagents-setup` wizard drives every field interactively — models,
-thinking levels, the vision model, concurrency, fix rounds, idle timeout, scope,
-and injection — with a per-agent "configure one" menu when the config already
-exists. `notifyOnReviewPass` and `maxResultLines` are edited directly in the
-file.
+set). The `/subagents-setup` wizard drives every field interactively — models, the
+default plus each enabled agent's thinking level, the vision model, concurrency,
+fix rounds, idle timeout, scope, and injection — with a per-agent "configure
+one" menu when the config already exists. `notifyOnReviewPass` and
+`maxResultLines` are edited directly in the file.
 
 ```json
 {
@@ -146,6 +196,9 @@ file.
   "agentModels": {
     "explore": "anthropic/claude-haiku-4-5"
   },
+  "agentBackupModels": {
+    "explore": "openai/gpt-5-mini"
+  },
   "agentThinkingLevels": {
     "explore": "low"
   },
@@ -164,7 +217,8 @@ file.
 | Field | Description |
 | --- | --- |
 | `enabledAgents` | Agent names exposed to discovery and prompt injection. An empty array disables all agents. |
-| `agentModels` | Optional `provider/model-id` override per agent. |
+| `agentModels` | Optional primary `provider/model-id` override per agent. |
+| `agentBackupModels` | Optional backup per agent, tried after its primary and before the current main-window model. |
 | `agentThinkingLevels` | Optional thinking level per agent; agents without an entry use the agent's frontmatter `thinking`, then `thinkingLevel`. |
 | `thinkingLevel` | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default `high`). |
 | `visionModel` | Optional vision-capable model for `vision: true` tasks (screenshots/mockups/designs). Unset = falls back to the main session's current model. |
@@ -176,24 +230,41 @@ file.
 | `maxFixRounds` | Auto-fix rounds when a reviewer returns `REVIEW_FAIL` (default 2; `0` disables the loop). |
 | `idleTimeoutSec` | Idle watchdog: a sub-agent whose stdout goes silent for this long is terminated and retried. `0` disables it. Default 90. |
 
-### Model precedence
+### Model precedence and fallback
+
+Normal run pool:
 
 ```text
-per-agent override → current main-session model → agent frontmatter model
+configured agent primary → configured agent backup → current main-window model
 ```
 
-For vision-flagged runs:
+If no primary is configured, the current main-window model is primary; the
+agent frontmatter model is used only when no current main model exists. For
+vision runs, `visionModel` replaces the first slot while the selected agent's
+backup and current main model remain the fallbacks. Duplicate refs are removed.
 
-```text
-visionModel (configured) → current main-session model → agent model
+Each candidate gets startup-race retries. Provider failures retry the same
+candidate up to five times only when transient (timeouts, network, 429, 5xx).
+Permanent model/config failures (`model not found`, unknown provider, 404) and
+quota/auth/billing failures skip that delay and advance immediately. No runtime
+outcome rewrites `pi-subagents.json`. If the whole pool fails, the result is
+handed to the main window with its retained run id and session.
+
+### Resuming retained context
+
+Every run stores its Pi session in a private temp directory. Same-model retries
+and pool fallbacks resume that session, so searches, reads, reasoning, and edits
+remain in context. A parked, completed, or failed thread can later be resumed
+under its stable id:
+
+```ts
+subagent_control({ action: "resume", id: 7 });
+subagent_control({ action: "resume", id: 7, objective: "Continue with the repaired credentials." });
 ```
 
-Unavailable configured models are replaced with a usable current-session model
-and the repaired config is saved. At runtime, a model that fails at the provider
-level before producing output is retried (same model up to 5× on transient
-errors, then once with the main window's model — per-run only, never persisted);
-if everything fails, the task is handed back to the main window with
-instructions to execute it directly.
+Use `fork` when both paths should remain available. `subagent_stop` is the
+explicit destructive operation that retires a retained session; otherwise
+sessions live until the parent Pi session shuts down.
 
 ### Configuration migration
 
@@ -206,7 +277,8 @@ after an update via a toast (marker persisted in `announcedFeatures`).
 ## Agent discovery and overrides
 
 - Built-in agents ship with the package; user agents live in `~/.pi/agent/agents/`;
-  project agents in the nearest `.pi/agents/` directory.
+  project agents in the nearest `.pi/agents/` directory are loaded only when Pi
+  trusts that project.
 - For duplicate names: project overrides user overrides built-in. Keep the
   matching filename and `name` field to replace a built-in agent.
 - Optional frontmatter: `model` (default model reference), `thinking` (default
@@ -215,16 +287,17 @@ after an update via a toast (marker persisted in `announcedFeatures`).
 
 ## How it stays reliable
 
-- **Three-layer model resilience** — same-model retry with backoff on transient
-  provider errors (503/429/timeout/network), then a one-shot fallback to the main
-  window's model. Terminal errors (quota/billing/invalid key/auth) never retry.
+- **Ordered model resilience** — transient failures retry the same candidate,
+  then advance through configured backup and current-main candidates. Permanent
+  stale-model/config and quota/auth/billing errors skip same-model backoff.
 - **Startup-race retries** — a silent zero-activity child exit (concurrent pi
   startup lock contention) is relaunched with backoff; only clean silent exits
   qualify, so real work is never duplicated.
 - **Idle watchdog** — a stalled provider stream (no output for `idleTimeoutSec`)
   terminates the child and retries via the normal fallback path.
-- **Dispatch crashes surface** — an exception in the dispatch layer produces a
-  failed result with a notification, never a silent hang.
+- **Dispatch failures surface** — partial parallel startup reports every failed
+  item and reason; if none start, the tool throws so Pi records a real tool error.
+  Dispatch crashes likewise produce a failed result instead of a silent hang.
 - **Leaf children** — no nested delegation, no runaway trees.
 
 ## Development
@@ -235,30 +308,13 @@ npm run check
 npm test
 ```
 
-The source is modular: `dispatch.ts` (subagent tool + auto-fix chain + vision
-model), `tools.ts` (wait/status/stop), `widget.ts` (widget + announcements),
-`runtime.ts` (shared session state), `spawn.ts` (child process layer),
-`monitor.ts` (run tracking), `setup.ts` (wizard), `prompt.ts` (delegation
-directive). No runtime dependencies beyond pi peer dependencies.
-
-## Acknowledgments
-
-- The official [pi subagent example](https://github.com/earendil-works/pi)
-  (`examples/extensions/subagent`) — the child-process dispatch and
-  event-stream handling build on it.
-- [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) — the
-  live widget and parallel fan-out follow its design.
-- [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) — the
-  result-delivery design is learned from it: prompt **steer** delivery, a
-  non-blocking `subagent_wait`, status inspection, and stop/interrupt
-  management. Its status-file and workflow-script orchestration are deliberately
-  out of scope: this extension stays a focused 3-agent delegation tool with a
-  configuration wizard.
-- The sub-agent pattern itself, popularized by
-  [Claude Code](https://github.com/anthropics/claude-code).
-
-The agent prompts and extension code are written independently for this
-project; the projects above served as design references.
+The source is modular: `dispatch.ts` (dispatch, controls, isolation, auto-fix),
+`rpc-run.ts` / `spawn.ts` (persistent child transport + model pools),
+`worktree.ts` / `session-fork.ts` (filesystem/session branching),
+`trajectory.ts` / `inspector*.ts` (safe live inspection), `tools.ts`
+(wait/status/control/stop), `widget.ts` (widget + recovery announcements), and
+`runtime.ts` (session-scoped ownership). No runtime dependencies beyond pi peer
+dependencies.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.29.0",
+  "version": "0.32.2",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/agents.ts

@@ -123,16 +123,16 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 export interface DiscoverOptions {
 	/** Which directories to read from. Default: "user". */
 	scope?: AgentScope;
-	/** If provided and non-empty, only agents whose name is listed are returned. */
+	/** If provided, only agents whose name is listed are returned. */
 	enabledNames?: readonly string[];
-	/** Per-agent model override ("provider/model-id"), keyed by agent name. */
-	modelOverrides?: Record<string, string>;
+	/** Project-controlled prompts are loaded only after Pi trusts the project. */
+	projectTrusted?: boolean;
 	/** Override the built-in agents directory (used by tests). */
 	builtinDir?: string;
 }
 
 /**
- * Discover agents across scopes, apply enable-filter and model overrides.
+ * Discover agents across scopes and apply the enabled-name filter.
  * Override priority for the same name: project > user > builtin.
  */
 export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
@@ -143,7 +143,9 @@ export function discoverAgents(cwd: string, options: DiscoverOptions = {}): Agen
 	const builtin = loadAgentsFromDir(builtinDir, "builtin");
 	const user = scope === "project" ? [] : loadAgentsFromDir(join(getAgentDir(), "agents"), "user");
 	const project =
-		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+		scope === "user" || !projectAgentsDir || options.projectTrusted !== true
+			? []
+			: loadAgentsFromDir(projectAgentsDir, "project");
 
 	// Merge with override priority builtin < user < project.
 	const byName = new Map<string, AgentConfig>();
@@ -153,18 +155,11 @@ export function discoverAgents(cwd: string, options: DiscoverOptions = {}): Agen
 
 	let agents = Array.from(byName.values());
 
-	if (options.enabledNames && options.enabledNames.length > 0) {
+	if (options.enabledNames !== undefined) {
 		const enabled = new Set(options.enabledNames);
 		agents = agents.filter((agent) => enabled.has(agent.name));
 	}
 
-	if (options.modelOverrides) {
-		agents = agents.map((agent) => {
-			const override = options.modelOverrides?.[agent.name];
-			return override ? { ...agent, model: override } : agent;
-		});
-	}
-
 	return { agents, projectAgentsDir };
 }
 

package/src/background.ts

@@ -14,6 +14,7 @@ export type BackgroundTask = (signal: AbortSignal) => Promise<void>;
 interface PendingTask {
 	task: BackgroundTask;
 	controller: AbortController;
+	complete: () => void;
 	/** Called when a queued task is aborted before its body ever runs (drain skips
 	 * an already-aborted entry; cancelAll aborts every pending entry), so the
 	 * task body never produces a result. Callers that resolve waiters on a run id
@@ -23,13 +24,15 @@ interface PendingTask {
 	onCancelled?: () => void;
 	/** Invoked when the task throws and was not cancelled (cancellation is not a
 	 * failure — e.g. session shutdown races must never be reported as errors). */
-	onError?: (error: unknown) => void;
+	onError?: (error: unknown) => void | Promise<void>;
 }
 
 export class BackgroundTaskQueue {
 	private concurrency: number;
 	private readonly pending: PendingTask[] = [];
 	private readonly active = new Set<AbortController>();
+	private readonly completions = new WeakMap<AbortController, Promise<void>>();
+	private readonly idleWaiters = new Set<() => void>();
 	private stopped = false;
 
 	constructor(concurrency: number) {
@@ -46,19 +49,55 @@ export class BackgroundTaskQueue {
 		this.drain();
 	}
 
-	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void): AbortController {
+	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void | Promise<void>): AbortController {
 		const controller = new AbortController();
+		let complete!: () => void;
+		const completion = new Promise<void>((resolve) => {
+			complete = resolve;
+		});
+		this.completions.set(controller, completion);
 		if (this.stopped) {
 			controller.abort();
 			this.runCancelled(onCancelled);
+			complete();
 			return controller;
 		}
 
-		this.pending.push({ task, controller, onCancelled, onError });
+		this.pending.push({ task, controller, complete, onCancelled, onError });
 		this.drain();
 		return controller;
 	}
 
+	/** Resolve after this exact task has left the pending/active sets. This is
+	 * stronger than waiting for its task body: callers may safely reuse a
+	 * concurrency slot or the task's persisted checkpoint after it resolves. */
+	waitForTask(controller: AbortController | undefined): Promise<void> {
+		if (!controller) return Promise.resolve();
+		return this.completions.get(controller) ?? Promise.resolve();
+	}
+
+	/** Cancel one queued/running task. Queued entries are removed immediately;
+	 * active entries resolve waitForTask only after their body and error handler
+	 * have quiesced and the concurrency slot has been released. */
+	cancel(controller: AbortController | undefined): void {
+		if (!controller) return;
+		controller.abort();
+		const index = this.pending.findIndex((entry) => entry.controller === controller);
+		if (index !== -1) {
+			const [entry] = this.pending.splice(index, 1);
+			this.runCancelled(entry.onCancelled);
+			entry.complete();
+			this.drain();
+			this.resolveIdleWaiters();
+		}
+	}
+
+	/** Resolve once no queued or running task remains. */
+	waitForIdle(): Promise<void> {
+		if (this.pending.length === 0 && this.active.size === 0) return Promise.resolve();
+		return new Promise<void>((resolve) => this.idleWaiters.add(resolve));
+	}
+
 	/** Stop queued work and request cancellation for running work. */
 	cancelAll(): void {
 		if (this.stopped) return;
@@ -67,8 +106,10 @@ export class BackgroundTaskQueue {
 		for (const entry of this.pending.splice(0)) {
 			entry.controller.abort();
 			this.runCancelled(entry.onCancelled);
+			entry.complete();
 		}
 		for (const controller of this.active) controller.abort();
+		this.resolveIdleWaiters();
 	}
 
 	/** Cancellation callbacks are user-supplied: a throw must never break the queue
@@ -85,28 +126,40 @@ export class BackgroundTaskQueue {
 	private drain(): void {
 		while (!this.stopped && this.active.size < this.concurrency) {
 			const entry = this.pending.shift();
-			if (!entry) return;
+			if (!entry) {
+				this.resolveIdleWaiters();
+				return;
+			}
 			if (entry.controller.signal.aborted) {
 				this.runCancelled(entry.onCancelled);
+				entry.complete();
 				continue;
 			}
 
 			this.active.add(entry.controller);
 			void entry.task(entry.controller.signal)
-				.catch((error: unknown) => {
+				.catch(async (error: unknown) => {
 					// Cancellation is not a failure: aborted work (e.g. session
 					// shutdown) must never be reported as an exception.
 					if (entry.controller.signal.aborted) return;
 					try {
-						entry.onError?.(error);
+						await entry.onError?.(error);
 					} catch {
 						/* error reporting must never break the queue */
 					}
 				})
 				.finally(() => {
 					this.active.delete(entry.controller);
+					entry.complete();
 					this.drain();
+					this.resolveIdleWaiters();
 				});
 		}
 	}
+
+	private resolveIdleWaiters(): void {
+		if (this.pending.length > 0 || this.active.size > 0) return;
+		for (const resolve of this.idleWaiters) resolve();
+		this.idleWaiters.clear();
+	}
 }

package/src/completion.ts

@@ -151,3 +151,31 @@ export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass:
 		reviewVerdict(getResultOutput(result)) === "pass"
 	);
 }
+
+/** Minimal shape of an active run, for the "others still running" footer. Kept
+ * decoupled from the monitor's RunView so this stays a pure, easily tested
+ * formatter; the caller maps its live runs into this shape. */
+export interface ActiveRunFoot {
+	id: number;
+	agent: string;
+	/** Optional content label (task-derived) shown next to the agent name. */
+	label?: string;
+}
+
+/**
+ * Footer appended to a completion message when OTHER runs are still active, so
+ * the main agent does not declare the overall task done prematurely. A result
+ * arriving for one run does not mean sibling runs are finished; naming them
+ * gives the main agent concrete, in-context awareness to keep waiting.
+ *
+ * Returns "" when nothing is active (the common, single-run case stays quiet).
+ */
+export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
+	if (runs.length === 0) return "";
+	const listed = runs.slice(0, maxListed);
+	const items = listed
+		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
+		.join(", ");
+	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
+	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
+}

package/src/config.ts

@@ -25,7 +25,7 @@ export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explore", "worker", "
 
 /**
  * Agents that used to ship but were removed. normalizeConfig strips them from
- * enabledAgents/agentModels so upgraded installs clean their config automatically
+ * enabledAgents/model mappings so upgraded installs clean their config automatically
  * (the schema-upgrade save in loadConfig then persists the cleanup).
  */
 export const REMOVED_AGENT_NAMES: readonly string[] = ["plan"];
@@ -70,8 +70,10 @@ export const IDLE_TIMEOUT_SEC_LIMIT = 600;
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
 	enabledAgents: string[];
-	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
+	/** Per-agent primary model override, keyed by agent name, as "provider/model-id". */
 	agentModels: Record<string, string>;
+	/** Optional per-agent backup model, tried after the primary and before the current main-window model. */
+	agentBackupModels: Record<string, string>;
 	/** Per-agent thinking-level override, keyed by agent name. */
 	agentThinkingLevels: Record<string, ThinkingLevel>;
 	/** Thinking level for sub-agents without a per-agent override or frontmatter default. Default: "high". */
@@ -125,6 +127,7 @@ export interface SubagentsConfig {
 export const DEFAULT_CONFIG: SubagentsConfig = {
 	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
 	agentModels: {},
+	agentBackupModels: {},
 	agentThinkingLevels: {},
 	thinkingLevel: DEFAULT_THINKING_LEVEL,
 	notifyOnReviewPass: false,
@@ -172,6 +175,7 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	const config: SubagentsConfig = {
 		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
 		agentModels: {},
+		agentBackupModels: {},
 		agentThinkingLevels: {},
 		thinkingLevel: DEFAULT_CONFIG.thinkingLevel,
 		notifyOnReviewPass: DEFAULT_CONFIG.notifyOnReviewPass,
@@ -202,6 +206,13 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		}
 	}
 
+	if (isRecord(raw.agentBackupModels)) {
+		for (const [key, value] of Object.entries(raw.agentBackupModels)) {
+			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
+			if (isModelReference(value)) config.agentBackupModels[key.trim()] = value.trim();
+		}
+	}
+
 	if (isRecord(raw.agentThinkingLevels)) {
 		for (const [key, value] of Object.entries(raw.agentThinkingLevels)) {
 			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
@@ -272,6 +283,7 @@ function defaultConfig(): SubagentsConfig {
 		...DEFAULT_CONFIG,
 		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
 		agentModels: {},
+		agentBackupModels: {},
 		agentThinkingLevels: {},
 		announcedFeatures: [],
 	};