pi-herdr-agents 0.0.3 → 0.1.0

package/README.md

@@ -314,7 +314,14 @@ exact IDs from your authenticated model catalog:
 `subagent({ agent: ... })`. Explicit `model` tool arguments take precedence,
 followed by agent frontmatter, per-agent config, the global default, and finally
 the parent model. Model values must be exact authenticated `provider/model-id`
-references.
+references. A value can contain an ordered comma-separated fallback list, for
+example `provider/preferred, provider/fallback`. The extension validates every
+candidate before launch, retries the preferred model normally, then launches
+later candidates only after a provider/agent request failure. A completed child
+result, including a negative task result, never switches models. Completion
+metadata and the status widget report the model actually used; an exhausted
+list reports every attempted model. Workflow metadata accepts one exact model
+only, to keep approved workflow runtimes deterministic.
 
 `config.json` is gitignored in the source tree so local overrides are not
 committed from a checkout. On an installed package root, treat it as disposable
@@ -356,7 +363,7 @@ subagent({
 | `agent`                | string  | —              | Load defaults from agent definition                                                               |
 | `fork`                 | boolean | `false`        | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter  |
 | `interactive`          | boolean | derived        | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
-| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`; resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
+| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, or an ordered comma-separated Pi fallback list; unavailable for Claude CLI and worktree spawns. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
 | `thinking`             | string  | parent level   | Pi thinking level (`off` through `max`); omit to inherit the parent                                |
 | `systemPrompt`         | string  | —              | Role/system-prompt text for a bare spawn; overrides the body for Claude CLI agents, while named Pi agents keep their definition body |
 | `resumeSessionId`      | string  | —              | Claude CLI session ID to resume; separate from the Pi `subagent_resume` tool                       |
@@ -683,7 +690,7 @@ and verify them with `/subagent list` plus a smoke launch.
 | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`        | string  | Optional explicit agent name used in `agent: "my-agent"`; defaults to the filename stem and must match it in role packs                                                                                                                                                                                            |
 | `description` | string  | Shown in `subagents_list` output                                                                                                                                                                                                                                            |
-| `model`       | string  | Optional exact authenticated Pi model default; omit to use per-agent config, global config, then the parent                                                                                                                                                                 |
+| `model`       | string  | Optional exact authenticated Pi model default or ordered comma-separated fallback list; omit to use per-agent config, global config, then the parent                                                                                                                       |
 | `cli`         | string  | Set to `claude` to launch the Claude CLI instead of Pi                                                                                                                                                                                                                       |
 | `cli-model`   | string  | Optional model name passed to a Claude CLI agent; separate from Pi model routing                                                                                                                                                                             |
 | `thinking`    | string  | Optional Pi thinking default (`off` through `max`); omit to inherit the parent. Thinking overrides are not supported for Claude CLI agents                                                                                                                                   |

package/docs/worktree-subagents.md

@@ -46,7 +46,7 @@ For a worktree launch:
 - Uncommitted and untracked files from the parent checkout are not copied. Commit anything the child must see before spawning it, or pass the needed context in the task.
 - Worktree creation does not steal terminal focus.
 
-`worktree` cannot be set in agent frontmatter and is not exposed by the `/subagent <agent> <task>` shorthand. It is selected per call to the `subagent` tool.
+`worktree` cannot be set in agent frontmatter and is not exposed by the `/subagent <agent> <task>` shorthand. It is selected per call to the `subagent` tool. Ordered model fallback lists are not supported for worktree subagents: a failed attempt retains its worktree and branch for review, so a retry cannot safely reuse the requested branch.
 
 ## Parent and worker responsibilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/claude.ts

@@ -0,0 +1,164 @@
+import { execFileSync } from "node:child_process";
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	unlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { shellQuote } from "./terminal.ts";
+
+const CLAUDE_SESSIONS_DIR = join(
+	process.env.HOME ?? "/tmp",
+	".pi",
+	"agent",
+	"sessions",
+	"claude-code",
+);
+
+export interface ClaudeWorkspace {
+	baseline?: Set<string>;
+	cwd?: string;
+}
+
+export interface ClaudeLaunchParams {
+	cwd: string;
+	sentinelFile: string;
+	pluginDir: string;
+	model?: string;
+	systemPrompt?: string;
+	resumeSessionId?: string;
+	task: string;
+}
+
+export interface ClaudeCompletionParams extends ClaudeWorkspace {
+	sentinelFile: string;
+	exitCode: number;
+	readTerminal: () => string;
+}
+
+export interface ClaudeCompletion {
+	summary: string;
+	sessionId?: string;
+}
+
+export function requireClaudeAdapter(cli?: string): void {
+	if (cli && cli !== "claude") {
+		throw new Error(`Unsupported subagent CLI ${JSON.stringify(cli)}.`);
+	}
+}
+
+export function captureClaudeWorkspaceBaseline(cwd: string): Set<string> | undefined {
+	try {
+		const output = execFileSync(
+			"git",
+			["status", "--porcelain=v1", "--untracked-files=all", "-z"],
+			{ cwd, encoding: "utf8" },
+		);
+		return new Set(
+			output
+				.split("\0")
+				.filter(Boolean)
+				.map((entry) => entry.slice(3)),
+		);
+	} catch {
+		return undefined;
+	}
+}
+
+export function cleanupClaudeWorkspace({ baseline, cwd }: ClaudeWorkspace): string | undefined {
+	if (!baseline || !cwd) return;
+
+	try {
+		const output = execFileSync(
+			"git",
+			["status", "--porcelain=v1", "--untracked-files=all", "-z"],
+			{ cwd, encoding: "utf8" },
+		);
+		const changed = output
+			.split("\0")
+			.filter(Boolean)
+			.map((entry) => ({ status: entry.slice(0, 2), path: entry.slice(3) }));
+		const cleaned: string[] = [];
+
+		for (const { status, path } of changed) {
+			if (baseline.has(path) || path.startsWith(".reviews/")) continue;
+			if (status === "??") {
+				rmSync(join(cwd, path), { recursive: true, force: true });
+			} else {
+				execFileSync("git", ["restore", "--staged", "--worktree", "--", path], {
+					cwd,
+					stdio: "ignore",
+				});
+			}
+			cleaned.push(path);
+		}
+
+		return cleaned.length > 0
+			? `Claude workspace guard reverted newly introduced paths: ${cleaned.join(", ")}`
+			: undefined;
+	} catch (error: any) {
+		return `Claude workspace guard failed: ${error?.message ?? String(error)}`;
+	}
+}
+
+export function buildClaudeLaunchCommand(params: ClaudeLaunchParams): string {
+	const parts = [
+		`PI_CLAUDE_SENTINEL=${shellQuote(params.sentinelFile)}`,
+		"claude",
+		"--dangerously-skip-permissions",
+	];
+	if (existsSync(params.pluginDir)) {
+		parts.push("--plugin-dir", shellQuote(params.pluginDir));
+	}
+	if (params.model) parts.push("--model", shellQuote(params.model));
+	if (params.systemPrompt) {
+		parts.push("--append-system-prompt", shellQuote(params.systemPrompt));
+	}
+	if (params.resumeSessionId) parts.push("--resume", shellQuote(params.resumeSessionId));
+	parts.push(shellQuote(params.task));
+	return `cd ${shellQuote(params.cwd)} && ${parts.join(" ")}; echo '__SUBAGENT_DONE_'$?'__'`;
+}
+
+function copyClaudeSession(sentinelFile: string): string | undefined {
+	try {
+		const transcriptFile = `${sentinelFile}.transcript`;
+		if (!existsSync(transcriptFile)) return;
+		const transcriptPath = readFileSync(transcriptFile, "utf-8").trim();
+		if (!transcriptPath || !existsSync(transcriptPath)) return;
+		mkdirSync(CLAUDE_SESSIONS_DIR, { recursive: true });
+		const filename = transcriptPath.split("/").pop() ?? `claude-${Date.now()}.jsonl`;
+		copyFileSync(transcriptPath, join(CLAUDE_SESSIONS_DIR, filename));
+		return filename;
+	} catch {
+		return undefined;
+	}
+}
+
+export function completeClaudeRun(params: ClaudeCompletionParams): ClaudeCompletion {
+	const guardMessage = cleanupClaudeWorkspace(params);
+	let summary = "";
+	try {
+		summary = readFileSync(params.sentinelFile, "utf-8").trim();
+	} catch {}
+	if (!summary) {
+		summary = params.readTerminal().replace(/__SUBAGENT_DONE_\d+__/, "").trimEnd();
+	}
+	if (!summary) {
+		summary =
+		params.exitCode !== 0
+			? `Claude Code exited with code ${params.exitCode}`
+			: "Claude Code exited without output";
+	}
+	if (guardMessage) summary += `\n\n${guardMessage}`;
+
+	const sessionId = copyClaudeSession(params.sentinelFile);
+	for (const file of [params.sentinelFile, `${params.sentinelFile}.transcript`]) {
+		try {
+			unlinkSync(file);
+		} catch {}
+	}
+	return { summary, ...(sessionId ? { sessionId } : {}) };
+}

package/pi-extension/subagents/index.ts

@@ -21,8 +21,6 @@ import {
 	writeFileSync,
 	existsSync,
 	mkdirSync,
-	copyFileSync,
-	unlinkSync,
 	rmSync,
 	renameSync,
 	statSync,
@@ -45,9 +43,17 @@ import {
 	waitForProcessesExit,
 } from "./terminal.ts";
 import { waitForCompletion } from "./completion.ts";
+import {
+	buildClaudeLaunchCommand,
+	captureClaudeWorkspaceBaseline,
+	cleanupClaudeWorkspace,
+	completeClaudeRun,
+	requireClaudeAdapter,
+} from "./claude.ts";
 import {
 	buildAuthenticatedModelCatalog,
 	resolveRuntimePlan,
+	resolveRuntimePlans,
 	wrapPiModelRegistry,
 	THINKING_LEVELS,
 	isThinkingLevel,
@@ -197,7 +203,7 @@ const SubagentParams = Type.Object({
 	model: Type.Optional(
 		Type.String({
 			description:
-				"Exact authenticated provider/model-id. Omit to inherit the parent model. Select another model only when task capability, speed, cost, modality, or context requirements warrant it.",
+				"Exact authenticated provider/model-id, or an ordered comma-separated fallback list. Omit to inherit the parent model. Fallbacks are Pi-backed only and cannot be used with worktrees.",
 		}),
 	),
 	thinking: Type.Optional(ThinkingLevelSchema),
@@ -804,69 +810,6 @@ function formatElapsed(seconds: number): string {
  * (for example direnv/devenv), so the delay is configurable for users who hit
  * dropped commands. Keep the historical default at 500ms.
  */
-function captureWorkspaceBaseline(cwd: string): Set<string> | undefined {
-	try {
-		const output = execFileSync(
-			"git",
-			["status", "--porcelain=v1", "--untracked-files=all", "-z"],
-			{ cwd, encoding: "utf8" },
-		);
-		return new Set(
-			output
-				.split("\0")
-				.filter(Boolean)
-				.map((entry) => entry.slice(3)),
-		);
-	} catch {
-		return undefined;
-	}
-}
-
-function guardClaudeWorkspace(running: RunningSubagent): string | undefined {
-	if (!running.workspaceBaseline || !running.workspaceCwd) return;
-
-	try {
-		const output = execFileSync(
-			"git",
-			["status", "--porcelain=v1", "--untracked-files=all", "-z"],
-			{ cwd: running.workspaceCwd, encoding: "utf8" },
-		);
-		const changed = output
-			.split("\0")
-			.filter(Boolean)
-			.map((entry) => ({
-				status: entry.slice(0, 2),
-				path: entry.slice(3),
-			}));
-		const newPaths = changed.filter(
-			({ path }) => !running.workspaceBaseline!.has(path),
-		);
-		const cleaned: string[] = [];
-
-		for (const { status, path } of newPaths) {
-			if (path.startsWith(".reviews/")) continue;
-			if (status === "??") {
-				rmSync(`${running.workspaceCwd}/${path}`, {
-					recursive: true,
-					force: true,
-				});
-			} else {
-				execFileSync("git", ["restore", "--staged", "--worktree", "--", path], {
-					cwd: running.workspaceCwd,
-					stdio: "ignore",
-				});
-			}
-			cleaned.push(path);
-		}
-
-		return cleaned.length > 0
-			? `Claude workspace guard reverted newly introduced paths: ${cleaned.join(", ")}`
-			: undefined;
-	} catch (error: any) {
-		return `Claude workspace guard failed: ${error?.message ?? String(error)}`;
-	}
-}
-
 function getShellReadyDelayMs(): number {
 	const raw = process.env.PI_SUBAGENT_SHELL_READY_DELAY_MS?.trim();
 	const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
@@ -1205,6 +1148,7 @@ function resolveResultPresentation(
 		| "summary"
 		| "sessionFile"
 		| "errorMessage"
+		| "fallbackAttempts"
 		| "worktree"
 	>,
 	name: string,
@@ -1231,6 +1175,9 @@ function resolveResultPresentation(
 				: `Sub-agent "${name}" completed (${formatElapsed(result.elapsed)}).\n\n${result.summary}`;
 	}
 
+	if (result.fallbackAttempts && result.fallbackAttempts.length > 1) {
+		body += `\n\nModels attempted: ${result.fallbackAttempts.join(", ")}`;
+	}
 	if (result.worktree) body += `\n\n${formatWorktreeHandoff(result.worktree)}`;
 	const runtimeWarning = runtimeMismatch
 		? `\n\nRuntime warning: ${runtimeMismatch}`
@@ -1273,6 +1220,8 @@ interface SubagentResult {
 	error?: string;
 	/** Provider/agent error message when auto-retry exhausted (overload, rate limit, etc.). */
 	errorMessage?: string;
+	/** Ordered models launched for this run, including failed fallback attempts. */
+	fallbackAttempts?: string[];
 	ping?: { name: string; message: string };
 	worktree?: WorktreeHandoff;
 }
@@ -2103,10 +2052,10 @@ async function launchSubagent(
 		};
 	},
 	parentThinking: ThinkingLevel,
-	options?: { surface?: string },
+	options?: { surface?: string; runtimePlan?: ResolvedRuntimePlan; id?: string },
 ): Promise<RunningSubagent> {
 	const startTime = Date.now();
-	const id = Math.random().toString(16).slice(2, 10);
+	const id = options?.id ?? Math.random().toString(16).slice(2, 10);
 
 	const agentDefs = params.agent
 		? loadAgentDefaults(params.agent, runtime.pi)
@@ -2119,21 +2068,24 @@ async function launchSubagent(
 			diagnostic?.message ?? `Agent "${params.agent}" was not found.`,
 		);
 	}
+	requireClaudeAdapter(agentDefs?.cli);
 	if (!ctx.model)
 		throw new Error("Subagent launch requires a resolved parent model");
-	const runtimePlan = resolveRuntimePlan(
-		{ model: params.model, thinking: params.thinking },
-		{
-			model: resolveModelDefault(params.agent, agentDefs?.model, modelConfig),
-			thinking: agentDefs?.thinking,
-		},
-		{
-			provider: ctx.model.provider,
-			modelId: ctx.model.id,
-			thinking: parentThinking,
-		},
-		wrapPiModelRegistry(ctx.modelRegistry),
-	);
+	const runtimePlan =
+		options?.runtimePlan ??
+		resolveRuntimePlan(
+			{ model: params.model, thinking: params.thinking },
+			{
+				model: resolveModelDefault(params.agent, agentDefs?.model, modelConfig),
+				thinking: agentDefs?.thinking,
+			},
+			{
+				provider: ctx.model.provider,
+				modelId: ctx.model.id,
+				thinking: parentThinking,
+			},
+			wrapPiModelRegistry(ctx.modelRegistry),
+		);
 	const effectiveModel = runtimePlan.model;
 	const effectiveTools = params.tools ?? agentDefs?.tools;
 	const effectiveSkills = params.skills ?? agentDefs?.skills;
@@ -2244,7 +2196,7 @@ async function launchSubagent(
 	);
 	const workspaceBaseline =
 		agentDefs?.cli === "claude" && !worktree
-			? captureWorkspaceBaseline(targetCwdForSession)
+			? captureClaudeWorkspaceBaseline(targetCwdForSession)
 			: undefined;
 
 	// Generate a deterministic session file path for this subagent.
@@ -2312,35 +2264,15 @@ async function launchSubagent(
 		const sentinelFile = `/tmp/pi-claude-${id}-done`;
 		const pluginDir = join(SUBAGENTS_DIR, "plugin");
 
-		const cmdParts: string[] = [];
-		cmdParts.push(`PI_CLAUDE_SENTINEL=${shellQuote(sentinelFile)}`);
-		cmdParts.push("claude");
-		cmdParts.push("--dangerously-skip-permissions");
-
-		if (existsSync(pluginDir)) {
-			cmdParts.push("--plugin-dir", shellQuote(pluginDir));
-		}
-
-		const cliModel = agentDefs.cliModel ?? effectiveModel;
-		if (cliModel) {
-			cmdParts.push("--model", shellQuote(cliModel));
-		}
-
-		const sp = params.systemPrompt ?? agentDefs.body;
-		if (sp) {
-			cmdParts.push("--append-system-prompt", shellQuote(sp));
-		}
-
-		if (params.resumeSessionId) {
-			cmdParts.push("--resume", shellQuote(params.resumeSessionId));
-		}
-
-		// Always pass the task as the prompt — even for resumed sessions,
-		// the caller's task is the follow-up instruction.
-		cmdParts.push(shellQuote(params.task));
-
-		const cdPrefix = `cd ${shellQuote(targetCwdForSession)} && `;
-		const command = `${cdPrefix}${cmdParts.join(" ")}; echo '__SUBAGENT_DONE_'$?'__'`;
+		const command = buildClaudeLaunchCommand({
+			cwd: targetCwdForSession,
+			sentinelFile,
+			pluginDir,
+			model: agentDefs.cliModel ?? effectiveModel,
+			systemPrompt: params.systemPrompt ?? agentDefs.body,
+			resumeSessionId: params.resumeSessionId,
+			task: params.task,
+		});
 
 		const launchScriptName = `${
 			(params.name || "subagent")
@@ -2561,29 +2493,65 @@ async function launchSubagent(
  * the summary from the session file, and closes ordinary panes. Worktree
  * workspaces are retained for parent review.
  */
-const CLAUDE_SESSIONS_DIR = join(
-	process.env.HOME ?? "/tmp",
-	".pi",
-	"agent",
-	"sessions",
-	"claude-code",
-);
+function resolveSubagentRuntimePlans(
+	params: typeof SubagentParams.static,
+	ctx: Parameters<typeof launchSubagent>[1],
+	parentThinking: ThinkingLevel,
+): ResolvedRuntimePlan[] {
+	const agentDefs = params.agent
+		? loadAgentDefaults(params.agent, runtime.pi)
+		: null;
+	if (params.agent && !agentDefs) {
+		const diagnostic = discoverAgentCatalog(runtime.pi).diagnostics.find(
+			(candidate) => candidate.agentName === params.agent,
+		);
+		throw new Error(
+			diagnostic?.message ?? `Agent "${params.agent}" was not found.`,
+		);
+	}
+	if (!ctx.model) throw new Error("Subagent launch requires a resolved parent model");
+	const plans = resolveRuntimePlans(
+		{ model: params.model, thinking: params.thinking },
+		{
+			model: resolveModelDefault(params.agent, agentDefs?.model, modelConfig),
+			thinking: agentDefs?.thinking,
+		},
+		{
+			provider: ctx.model.provider,
+			modelId: ctx.model.id,
+			thinking: parentThinking,
+		},
+		wrapPiModelRegistry(ctx.modelRegistry),
+	);
+	if (agentDefs?.cli === "claude" && plans.length > 1) {
+		throw new Error("Model fallbacks are supported only for Pi-backed subagents.");
+	}
+	if (params.worktree && plans.length > 1) {
+		throw new Error("Model fallbacks are not supported for worktree subagents.");
+	}
+	return plans;
+}
 
-function copyClaudeSession(sentinelFile: string): string | null {
-	try {
-		const transcriptFile = sentinelFile + ".transcript";
-		if (!existsSync(transcriptFile)) return null;
-		const transcriptPath = readFileSync(transcriptFile, "utf-8").trim();
-		if (!transcriptPath || !existsSync(transcriptPath)) return null;
-		mkdirSync(CLAUDE_SESSIONS_DIR, { recursive: true });
-		const filename =
-			transcriptPath.split("/").pop() ?? `claude-${Date.now()}.jsonl`;
-		const dest = join(CLAUDE_SESSIONS_DIR, filename);
-		copyFileSync(transcriptPath, dest);
-		return filename;
-	} catch {
-		return null;
+async function launchSubagentWithFallbacks(
+	params: typeof SubagentParams.static,
+	ctx: Parameters<typeof launchSubagent>[1],
+	parentThinking: ThinkingLevel,
+	plans: ResolvedRuntimePlan[],
+): Promise<{ running: RunningSubagent; index: number }> {
+	const failures: string[] = [];
+	for (const [index, plan] of plans.entries()) {
+		try {
+			return {
+				running: await launchSubagent(params, ctx, parentThinking, { runtimePlan: plan }),
+				index,
+			};
+		} catch (error) {
+			failures.push(`${plan.model}: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
+	throw new Error(
+		`Subagent could not launch with any configured model. Attempted: ${plans.map((plan) => plan.model).join(", ")}. ${failures.join("; ")}`,
+	);
 }
 
 async function watchSubagent(
@@ -2623,41 +2591,13 @@ async function watchSubagent(
 		const elapsed = Math.floor((detectedAt - startTime) / 1000);
 
 		if (running.cli === "claude") {
-			// Claude Code result extraction
-			const guardMessage = guardClaudeWorkspace(running);
-			let summary = "";
-
-			if (running.sentinelFile) {
-				try {
-					summary = readFileSync(running.sentinelFile, "utf-8").trim();
-				} catch {}
-			}
-
-			if (!summary) {
-				summary = readPane(surface, 200)
-					.replace(/__SUBAGENT_DONE_\d+__/, "")
-					.trimEnd();
-			}
-
-			if (!summary) {
-				summary =
-					result.exitCode !== 0
-						? `Claude Code exited with code ${result.exitCode}`
-						: "Claude Code exited without output";
-			}
-			if (guardMessage) summary += `\n\n${guardMessage}`;
-
-			// Copy Claude session transcript
-			let sessionId: string | null = null;
-			if (running.sentinelFile) {
-				sessionId = copyClaudeSession(running.sentinelFile);
-				try {
-					unlinkSync(running.sentinelFile);
-				} catch {}
-				try {
-					unlinkSync(running.sentinelFile + ".transcript");
-				} catch {}
-			}
+			const claudeCompletion = completeClaudeRun({
+				sentinelFile: running.sentinelFile!,
+				exitCode: result.exitCode,
+				baseline: running.workspaceBaseline,
+				cwd: running.workspaceCwd,
+				readTerminal: () => readPane(surface, 200),
+			});
 
 			const worktreeHandoff = finalizeSubagentSurface(
 				running,
@@ -2668,7 +2608,7 @@ async function watchSubagent(
 					? markCompleted(running.lifecycle, Date.now())
 					: markFailed(
 							running.lifecycle,
-							result.errorMessage ?? summary,
+							result.errorMessage ?? claudeCompletion.summary,
 							Date.now(),
 							result.exitCode,
 						);
@@ -2676,10 +2616,12 @@ async function watchSubagent(
 			return {
 				name,
 				task,
-				summary,
+				summary: claudeCompletion.summary,
 				exitCode: result.exitCode,
 				elapsed,
-				...(sessionId ? { claudeSessionId: sessionId } : {}),
+				...(claudeCompletion.sessionId
+					? { claudeSessionId: claudeCompletion.sessionId }
+					: {}),
 				...(worktreeHandoff ? { worktree: worktreeHandoff } : {}),
 			};
 		}
@@ -2761,7 +2703,12 @@ async function watchSubagent(
 		};
 	} catch (err: any) {
 		const guardMessage =
-			running.cli === "claude" ? guardClaudeWorkspace(running) : undefined;
+			running.cli === "claude"
+				? cleanupClaudeWorkspace({
+						baseline: running.workspaceBaseline,
+						cwd: running.workspaceCwd,
+					})
+				: undefined;
 		const worktreeHandoff = finalizeSubagentSurface(running, "failed", true);
 		running.lifecycle = markFailed(
 			running.lifecycle,
@@ -2799,6 +2746,64 @@ async function watchSubagent(
 	}
 }
 
+async function watchSubagentWithFallbacks(
+	initial: RunningSubagent,
+	initialPlanIndex: number,
+	params: typeof SubagentParams.static,
+	ctx: Parameters<typeof launchSubagent>[1],
+	parentThinking: ThinkingLevel,
+	plans: ResolvedRuntimePlan[],
+	signal: AbortSignal,
+): Promise<{ running: RunningSubagent; result: SubagentResult }> {
+	let running = initial;
+	let nextPlan = initialPlanIndex + 1;
+	const attempts = [running.runtimePlan?.model].filter(
+		(model): model is string => !!model,
+	);
+
+	for (;;) {
+		const result = await watchSubagent(running, signal);
+		const shouldRetry = !!result.errorMessage && nextPlan < plans.length;
+		if (!shouldRetry) {
+			return { running, result: { ...result, fallbackAttempts: attempts } };
+		}
+
+		runningSubagents.delete(running.id);
+		updateWidget();
+		const launchErrors: string[] = [];
+		let launchedFallback = false;
+		while (nextPlan < plans.length) {
+			const plan = plans[nextPlan++];
+			attempts.push(plan.model);
+			try {
+				running = await launchSubagent(params, ctx, parentThinking, {
+					runtimePlan: plan,
+					id: initial.id,
+				});
+				running.abortController = initial.abortController;
+				launchedFallback = true;
+				startWidgetRefresh();
+				startStatusRefresh(runtime.pi!);
+				break;
+			} catch (error) {
+				launchErrors.push(
+					`${plan.model}: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+		}
+		if (!launchedFallback) {
+			return {
+				running,
+				result: {
+					...result,
+					errorMessage: `${result.errorMessage}\n\nFallback launch failures: ${launchErrors.join("; ")}`,
+					fallbackAttempts: attempts,
+				},
+			};
+		}
+	}
+}
+
 export default function subagentsExtension(pi: ExtensionAPI) {
 	runtime.pi = pi;
 	let btwChild: BtwChild | undefined;
@@ -3727,7 +3732,17 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 						`Unsupported parent thinking level: ${parentThinking}`,
 					);
 				}
-				const running = await launchSubagent(params, ctx, parentThinking);
+				const runtimePlans = resolveSubagentRuntimePlans(
+					params,
+					ctx,
+					parentThinking,
+				);
+				const { running, index: initialPlanIndex } = await launchSubagentWithFallbacks(
+					params,
+					ctx,
+					parentThinking,
+					runtimePlans,
+				);
 
 				// Create a separate AbortController for the watcher
 				// (the tool's signal completes when we return)
@@ -3739,16 +3754,24 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				startStatusRefresh(pi);
 
 				// Fire-and-forget: start watching in background
-				watchSubagent(running, watcherAbort.signal)
-					.then((result) => {
-						if (!shouldDeliverSubagentCompletion(running)) {
-							running.lifecycle = markDelivery(running.lifecycle, "suppressed");
-							runningSubagents.delete(running.id);
+				watchSubagentWithFallbacks(
+					running,
+					initialPlanIndex,
+					params,
+					ctx,
+					parentThinking,
+					runtimePlans,
+					watcherAbort.signal,
+				)
+					.then(({ running: completedRunning, result }) => {
+						if (!shouldDeliverSubagentCompletion(completedRunning)) {
+							completedRunning.lifecycle = markDelivery(completedRunning.lifecycle, "suppressed");
+							runningSubagents.delete(completedRunning.id);
 							updateWidget();
 							return;
 						}
-						running.lifecycle = markDelivery(running.lifecycle, "delivered");
-						runningSubagents.delete(running.id);
+						completedRunning.lifecycle = markDelivery(completedRunning.lifecycle, "delivered");
+						runningSubagents.delete(completedRunning.id);
 						updateWidget();
 						const completionApi = selectCompletionApi(pi, runtime.pi);
 
@@ -3778,26 +3801,29 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
 						const presentation = resolveResultPresentation(
 							result,
-							running.name,
-							running.runtimePlan?.runtimeMismatch,
+							completedRunning.name,
+							completedRunning.runtimePlan?.runtimeMismatch,
 						);
 
 						sendSubagentResult(completionApi, presentation, {
-							name: running.name,
-							task: running.task,
-							agent: running.agent,
+							name: completedRunning.name,
+							task: completedRunning.task,
+							agent: completedRunning.agent,
 							exitCode: result.exitCode,
 							elapsed: result.elapsed,
 							sessionFile: result.sessionFile,
 							...(result.errorMessage
 								? { errorMessage: result.errorMessage }
 								: {}),
+							...(result.fallbackAttempts
+								? { fallbackAttempts: result.fallbackAttempts }
+								: {}),
 							...(result.claudeSessionId
 								? { claudeSessionId: result.claudeSessionId }
 								: {}),
 							...(result.worktree ? { worktree: result.worktree } : {}),
-							...(running.runtimePlan
-								? { runtimePlan: running.runtimePlan }
+							...(completedRunning.runtimePlan
+								? { runtimePlan: completedRunning.runtimePlan }
 								: {}),
 						});
 					})

package/pi-extension/subagents/runtime-routing.ts

@@ -190,6 +190,16 @@ function selectField(
   return { source: "parent" };
 }
 
+export function parseModelFallbacks(reference: string): string[] {
+  const candidates = reference.split(",").map((candidate) => candidate.trim());
+  if (candidates.some((candidate) => candidate === "")) {
+    throw new RuntimeResolutionError(
+      `model fallback list ${JSON.stringify(reference)} cannot contain an empty candidate`,
+    );
+  }
+  return candidates;
+}
+
 export function resolveRuntimePlan(
   request: RuntimeRequest,
   agentDefaults: RuntimeRequest,
@@ -272,6 +282,30 @@ export function resolveRuntimePlan(
   };
 }
 
+/** Resolve every configured fallback before launching the first child. */
+export function resolveRuntimePlans(
+  request: RuntimeRequest,
+  agentDefaults: RuntimeRequest,
+  parent: ParentRuntime,
+  registry: ModelRegistryAdapter,
+): ResolvedRuntimePlan[] {
+  const selection = selectField(request.model, agentDefaults.model);
+  if (!selection.value) {
+    return [resolveRuntimePlan(request, agentDefaults, parent, registry)];
+  }
+
+  return parseModelFallbacks(selection.value).map((model) =>
+    resolveRuntimePlan(
+      selection.source === "request" ? { ...request, model } : { ...request, model: undefined },
+      selection.source === "agent"
+        ? { ...agentDefaults, model }
+        : agentDefaults,
+      parent,
+      registry,
+    ),
+  );
+}
+
 function formatTokenCount(value: number | undefined): string | undefined {
   if (!value || value <= 0) return undefined;
   if (value >= 1_000_000) return `${Number((value / 1_000_000).toFixed(1))}m`;