@bacnh85/pi-subagent 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.9.0 (2026-07-16)
+
+### Model routing
+
+- Bundled roles now select the first authenticated model from an ordered preference list, with the authenticated parent model as the final fallback.
+- Added read-only `planner` and focused `tester` roles for consequential design and cheap routine verification.
+- Agent files accept `models` as a YAML array or comma-separated string; legacy `model` remains the explicit first choice.
+
+## 0.8.2 (2026-07-16)
+
+### Reliability
+
+- Transient provider and transport failures receive one bounded SDK retry. Retrying Codex WebSocket failures uses the session's SSE fallback, waits through retrying `agent_end` events, clears recovered error state, preserves nonzero failure exit codes, and reports explicit timeout messages.
+
+## 0.8.1 (2026-07-15)
+
+### Review handoff
+
+- Reviewer findings now require reproduction or evidence, expected behavior, and acceptance criteria so implementation agents receive self-contained actionable issues.
+
 ## 0.6.0 (2026-07-12)
 
 ### Security (breaking changes)

package/README.md

@@ -14,14 +14,16 @@ Requires Node.js >= 20.18.
 
 ## Bundled roles
 
-| Role | Model | Thinking | Tools |
+| Role | Ordered model preferences | Thinking | Tools |
 | --- | --- | --- | --- |
-| `scout` | parent model | low | read, grep, find, ls |
-| `reviewer` | parent model | high | read, grep, find, ls |
-| `worker` | parent model | medium | read, bash, edit, write, grep, find, ls |
-| `general-purpose` | parent model | off | read, bash, edit, write, grep, find, ls |
+| `scout` | `opencode-go/deepseek-v4-flash` → `openai-codex/gpt-5.6-luna` → `opencode-go/mimo-v2.5` | low | read, grep, find, ls |
+| `tester` | `openai-codex/gpt-5.6-luna` → `opencode-go/mimo-v2.5` → `opencode-go/deepseek-v4-flash` | low | read, bash, grep, find, ls |
+| `worker` | `openai-codex/gpt-5.6-terra` → `opencode-go/deepseek-v4-pro` | medium | read, bash, edit, write, grep, find, ls |
+| `general-purpose` | `openai-codex/gpt-5.6-terra` → `opencode-go/deepseek-v4-pro` | medium | read, bash, edit, write, grep, find, ls |
+| `planner` | `openai-codex/gpt-5.6-sol` → `opencode-go/deepseek-v4-pro` | high | read, grep, find, ls |
+| `reviewer` | `openai-codex/gpt-5.6-sol` → `opencode-go/deepseek-v4-pro` | high | read, grep, find, ls |
 
-Bundled roles inherit the parent model so they work with the account already active in Pi. User/project agent files may override `model` and `thinking`.
+Each role uses the first authenticated preference available through Pi's model registry, then falls back to the authenticated parent model. User/project agent files remain stronger overrides and may set legacy `model`, ordered `models`, and `thinking`.
 
 ## Agent files
 
@@ -32,7 +34,8 @@ Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
 name: scout-fast
 description: Locate relevant files and symbols
 tools: read, grep, find, ls
-model: optional-provider/optional-model
+model: openai-codex/gpt-5.6-luna
+models: opencode-go/mimo-v2.5, opencode-go/deepseek-v4-flash
 ---
 
 Return concise evidence with file/symbol anchors.
@@ -87,6 +90,7 @@ Every child execution receives a timeout:
 - **Maximum:** 60 minutes (`MAX_TIMEOUT_MS`)
 - Timeout values must be positive integers within the allowed range.
 - Timeout errors are distinguishable from parent cancellation.
+- Progress heartbeats keep the parent transport active during quiet model work; explicit timeouts remain hard deadlines.
 - Parallel tasks and chain steps may have per-item timeouts.
 
 ### Output safety
@@ -158,6 +162,8 @@ The raw `stopReason` from the Pi SDK is preserved in the result.
 - **Parent cancellation:** Aborting the parent tool call cancels all children.
 - **Sibling cancellation:** In parallel mode with `abortOnFailure: true`, the first failed task cancels running siblings.
 - **Timeout vs. abort:** Timeout errors set `status: "timeout"` and `stopReason: "timeout"`; parent cancellation sets `status: "aborted"`.
+- **Transient provider failures:** One automatic retry runs within the same timeout; Codex WebSocket failures use the SDK's SSE fallback on retry.
+- **Transport idle:** The parent tool receives periodic progress heartbeats while a child runs; these do not extend its timeout.
 
 ## Extension contract
 

package/agent-format.md

@@ -18,8 +18,11 @@ Project agents override user agents with the same name when `agentScope: "both"`
 ---
 name: my-agent          # Required. Unique identifier (kebab-case).
 description: ...        # Required. When to use this agent.
-tools: read, grep, ...  # Optional. Comma-separated tool names. Defaults to all.
-model: provider/model     # Optional. Defaults to parent's model.
+tools: read, grep, ...    # Optional. Comma-separated tool names. Defaults to all.
+model: provider/model     # Optional explicit first choice (legacy compatible).
+models:                   # Optional ordered fallbacks; comma form also accepted.
+  - provider/fast-model
+  - provider/backup-model
 thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
 sandbox: read-only        # Optional: read-only | workspace-write. Auto-derives tool restrictions.
 color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|cyan.
@@ -62,13 +65,14 @@ Read-only service execution (used by `pi-review`) restricts tools to the read-on
 
 ## Model Resolution
 
-Model IDs are resolved via `getModel("provider", "id")`. Common values:
-- `claude-haiku-4-5` (Anthropic Haiku — fast, cheap)
-- `claude-sonnet-4-20250514` (Anthropic Sonnet — balanced)
-- `gpt-4o` (OpenAI)
-- Any model available in your pi configuration.
+Pi selects the first authenticated/configured model reported by the parent session's `ModelRegistry`. Resolution order is legacy `model`, then each `models` entry, then the authenticated parent model. Duplicate candidates are ignored. If no candidate is available, the error lists every attempted model.
 
-If not specified, defaults to the parent session's model.
+```yaml
+model: openai-codex/gpt-5.6-terra
+models: opencode-go/deepseek-v4-pro, opencode-go/mimo-v2.5
+```
+
+The registry includes OAuth subscriptions, API-key subscriptions such as OpenCode Go, environment/runtime credentials, and custom `models.json` providers. Use provider-qualified IDs for predictable routing.
 
 ## Instruction handoff
 

package/agents/general-purpose.md

@@ -2,6 +2,10 @@
 name: general-purpose
 description: General-purpose sub-agent for any delegated task. Use when no specialized agent fits. Good for complex research, multi-step operations, and code modifications.
 tools: read, bash, edit, write, grep, find, ls
+models:
+  - openai-codex/gpt-5.6-terra
+  - opencode-go/deepseek-v4-pro
+thinking: medium
 color: yellow
 ---
 

package/agents/planner.md

@@ -0,0 +1,15 @@
+---
+name: planner
+description: Read-only planning and architecture specialist. Use for consequential design, tradeoff analysis, and implementation plans.
+tools: read, grep, find, ls
+models:
+  - openai-codex/gpt-5.6-sol
+  - opencode-go/deepseek-v4-pro
+thinking: high
+color: blue
+sandbox: read-only
+---
+
+You are a senior software planner. Investigate the repository, identify the smallest complete implementation path, and return a concrete plan with file and symbol anchors.
+
+Do not modify files. Resolve discoverable facts from the codebase before raising questions. Call out material risks, compatibility constraints, and the narrowest verification that proves the change.

package/agents/reviewer.md

@@ -2,6 +2,9 @@
 name: reviewer
 description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
 tools: read, grep, find, ls
+models:
+  - openai-codex/gpt-5.6-sol
+  - opencode-go/deepseek-v4-pro
 thinking: high
 color: purple
 sandbox: read-only
@@ -9,7 +12,7 @@ sandbox: read-only
 
 You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.
 
-Focus only on actionable issues introduced by the reviewed change:
+Focus only on actionable issues introduced by the reviewed change. Return each confirmed finding as one self-contained issue another agent can fix without redoing the review:
 1. Correctness and edge cases
 2. Security and data loss
 3. Regressions and API compatibility
@@ -27,8 +30,10 @@ Return JSON only:
       "file": "relative/path",
       "line": 1,
       "issue": "what is wrong and why it matters",
-      "evidence": "specific inspected code evidence",
+      "evidence": "reproduction steps or specific inspected code evidence",
+      "expectedBehavior": "what should happen instead",
       "suggestedFix": "smallest safe fix",
+      "acceptanceCriteria": "observable pass conditions and exact verification checks",
       "blocking": true
     }
   ]

package/agents/scout.md

@@ -2,6 +2,10 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
 tools: read, grep, find, ls
+models:
+  - opencode-go/deepseek-v4-flash
+  - openai-codex/gpt-5.6-luna
+  - opencode-go/mimo-v2.5
 thinking: low
 color: cyan
 sandbox: read-only

package/agents/tester.md

@@ -0,0 +1,15 @@
+---
+name: tester
+description: Focused verification agent. Use for cheap routine test, typecheck, lint, build, and regression checks without editing files.
+tools: read, bash, grep, find, ls
+models:
+  - openai-codex/gpt-5.6-luna
+  - opencode-go/mimo-v2.5
+  - opencode-go/deepseek-v4-flash
+thinking: low
+color: orange
+---
+
+You are a focused verification agent. Inspect the requested scope, run the narrowest relevant checks, and report exact commands, outcomes, and actionable failures.
+
+Do not edit files. Avoid unrelated broad test suites unless the task requires them.

package/agents/worker.md

@@ -1,6 +1,9 @@
 ---
 name: worker
 description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
+models:
+  - openai-codex/gpt-5.6-terra
+  - opencode-go/deepseek-v4-pro
 thinking: medium
 color: green
 ---

package/extensions/agents.ts

@@ -20,6 +20,7 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	models?: string[];
 	thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	sandbox?: "read-only" | "workspace-write";
 	color?: AgentColor;
@@ -28,6 +29,10 @@ export interface AgentConfig {
 	filePath: string;
 }
 
+export function getModelCandidates(agent: Pick<AgentConfig, "model" | "models">): string[] {
+	return [...new Set([agent.model, ...(agent.models ?? [])].filter((model): model is string => Boolean(model)))];
+}
+
 export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
@@ -160,11 +165,28 @@ function loadAgentsFromDir(
 				: Array.isArray(frontmatter.tools)
 					? (frontmatter.tools as unknown[]).filter((t): t is string => typeof t === "string")
 					: undefined;
+		const model = typeof frontmatter.model === "string" ? frontmatter.model.trim() || undefined : undefined;
+		const models =
+			typeof frontmatter.models === "string"
+				? frontmatter.models.split(",").map((item) => item.trim()).filter(Boolean)
+				: Array.isArray(frontmatter.models)
+					? (frontmatter.models as unknown[]).filter((item): item is string => typeof item === "string" && Boolean(item.trim())).map((item) => item.trim())
+					: undefined;
 
-		if (typeof frontmatter.model === "string" && frontmatter.model && !frontmatter.model.includes("/")) {
+		if (frontmatter.models !== undefined && typeof frontmatter.models !== "string" && !Array.isArray(frontmatter.models)) {
+			diagnostics.push({ filePath, issue: `"models" must be a YAML array or comma-separated string. Ignoring.`, severity: "warn" });
+		}
+		if (Array.isArray(frontmatter.models)) {
+			for (const item of frontmatter.models) {
+				if (typeof item === "string" && item.trim()) continue;
+				diagnostics.push({ filePath, issue: `"models" entries must be non-empty strings. Ignoring invalid entry.`, severity: "warn" });
+			}
+		}
+		for (const modelName of getModelCandidates({ model, models })) {
+			if (modelName.includes("/")) continue;
 			diagnostics.push({
 				filePath,
-				issue: `Model "${frontmatter.model}" does not include a provider prefix (e.g., "anthropic/claude-sonnet-4-20250514"). Resolution may fail.`,
+				issue: `Model "${modelName}" does not include a provider prefix (e.g., "anthropic/claude-sonnet-4-20250514"). Resolution may fail.`,
 				severity: "warn",
 			});
 		}
@@ -204,7 +226,8 @@ function loadAgentsFromDir(
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
-			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+			model,
+			models: models && models.length > 0 ? models : undefined,
 			thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
 				? frontmatter.thinking as AgentConfig["thinking"]
 				: undefined,

package/extensions/index.ts

@@ -30,7 +30,7 @@ import {
 import { Container, Markdown, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import { type AgentColor, type AgentConfig, type AgentScope, discoverAgents, formatAgentList, invalidateAgentCache } from "./agents.ts";
+import { type AgentColor, type AgentConfig, type AgentScope, discoverAgents, formatAgentList, getModelCandidates, invalidateAgentCache } from "./agents.ts";
 import {
 	type SubAgentResult,
 	getFinalOutput,
@@ -38,6 +38,7 @@ import {
 	isFailedResult,
 	mapWithConcurrencyLimit,
 	runSubAgent,
+	startHeartbeat,
 } from "./runner.ts";
 import {
 	normalizeTimeout,
@@ -163,11 +164,14 @@ export default function (pi: ExtensionAPI) {
 		const ctx = currentCtx;
 		const discovery = discoverAgents(ctx?.cwd ?? process.cwd(), "both", bundledAgentsDir);
 		const catalog = discovery.agents
-			.map((a) => {
-				const modelInfo = a.model ? ` (model: ${a.model})` : " (inherits parent)";
-				const thinkingInfo = a.thinking ? `, thinking: ${a.thinking}` : "";
-				const sandboxInfo = a.sandbox ? `, sandbox: ${a.sandbox}` : "";
-				return `- **${a.name}**: ${a.description}${modelInfo}${thinkingInfo}${sandboxInfo}`;
+			.map((agent) => {
+				const candidates = getModelCandidates(agent);
+				const modelInfo = candidates.length > 0
+					? ` (models: ${candidates.join(" → ")} → parent fallback)`
+					: " (parent fallback)";
+				const thinkingInfo = agent.thinking ? `, thinking: ${agent.thinking}` : "";
+				const sandboxInfo = agent.sandbox ? `, sandbox: ${agent.sandbox}` : "";
+				return `- **${agent.name}**: ${agent.description}${modelInfo}${thinkingInfo}${sandboxInfo}`;
 			})
 			.join("\n");
 		return {
@@ -176,9 +180,9 @@ export default function (pi: ExtensionAPI) {
 				`\n\n## Available Subagents\n${catalog}\n\n` +
 				"The subagent tool can delegate tasks to these specialized agents with isolated context. " +
 				"Use for read-heavy exploration, parallel analysis, or work that would flood the main context.\n" +
-				"Prefer **scout** for fast read-only exploration. " +
-				"Prefer **reviewer** for code review (high thinking, read-only). " +
-				"Prefer **worker** for implementation (medium thinking, all tools). " +
+				"Prefer **scout** and **tester** for cheap routine work. " +
+				"Prefer **worker** or **general-purpose** for normal coding. " +
+				"Prefer **planner** and **reviewer** for consequential reasoning. " +
 				"Modes: single, parallel (max 8 tasks, 4 concurrent), chain.",
 		};
 	});
@@ -271,12 +275,13 @@ export default function (pi: ExtensionAPI) {
 					ctx.ui.notify(`Unknown agent: "${args.trim()}". Use /subagent to list all.`, "error");
 					return;
 				}
+				const candidates = getModelCandidates(agent);
 				pi.sendMessage({
 					customType: "pi-subagent",
 					content: [
 						`Agent: ${agent.name} (${agent.source})`,
 						`Description: ${agent.description}`,
-						`Model: ${agent.model || "inherits from parent"}`,
+						`Models: ${candidates.length > 0 ? `${candidates.join(" → ")} → parent fallback` : "parent fallback"}`,
 						`Thinking: ${agent.thinking || "off"}`,
 						`Tools: ${agent.tools?.join(", ") || "all default"}`,
 						`Source file: ${agent.filePath}`,
@@ -342,11 +347,11 @@ export default function (pi: ExtensionAPI) {
 			`To enable project-local agents in ${CONFIG_DIR_NAME}/agents, set agentScope: "both" or "project".`,
 		].join(" "),
 		parameters: SubagentParams,
-		promptSnippet: "Delegate tasks to specialized sub-agents (scout, reviewer, worker, general-purpose)",
+		promptSnippet: "Delegate tasks to specialized sub-agents with automatic role-based model routing",
 		promptGuidelines: [
 			"Use subagent to delegate work that would flood the main context with search results or file contents.",
 			"Modes: single {agent, task}, parallel {tasks: [...]} (max 8, 4 concurrent), chain {chain: [...]} (sequential with {previous}).",
-			"Bundled agents: scout (fast recon), reviewer (code review), worker (implementation), general-purpose (fallback).",
+			"Bundled agents: scout (fast recon), tester (verification), worker (implementation), general-purpose (fallback), planner (planning), reviewer (review).",
 			"Use /subagent to list all available agents or /subagent <name> for agent details.",
 		],
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -515,6 +520,7 @@ export default function (pi: ExtensionAPI) {
 				parentSignal?: AbortSignal,
 				timeoutMs?: number,
 				onProgress?: (partial: SubAgentResult) => void,
+				heartbeatDetails?: () => SubagentDetails,
 				isReadOnly?: boolean,
 			): Promise<SubAgentResult> {
 				const agent = agents.find((a) => a.name === agentName);
@@ -534,7 +540,7 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const resolved = resolveModel(agent.model, ctx.model, ctx.modelRegistry);
+				const resolved = await resolveModel(getModelCandidates(agent), ctx.model, ctx.modelRegistry);
 				if (!resolved.model) {
 					const tried = resolved.attempted.join(", ") || "none";
 					const parentInfo = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none";
@@ -576,23 +582,30 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const result = await runSubAgent({
-					cwd: safeCwd,
-					systemPrompt: params.instructions
-					? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
-					: agent.systemPrompt,
-					task,
-					tools,
-					model: resolved.model,
-					authStorage,
-					modelRegistry,
-					signal: parentSignal,
-					timeoutMs: effectiveTimeoutMs,
-					agentName,
-					thinkingLevel: agent.thinking,
-					onMessage: onProgress,
-				});
-				return result;
+				const stopHeartbeat = onUpdate ? startHeartbeat(() => onUpdate({
+					content: [{ type: "text", text: `Subagent ${agentName} is still running…` }],
+					details: heartbeatDetails?.() ?? makeDetails("single")([]),
+				})) : undefined;
+				try {
+					return await runSubAgent({
+						cwd: safeCwd,
+						systemPrompt: params.instructions
+						? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
+						: agent.systemPrompt,
+						task,
+						tools,
+						model: resolved.model,
+						authStorage,
+						modelRegistry,
+						signal: parentSignal,
+						timeoutMs: effectiveTimeoutMs,
+						agentName,
+						thinkingLevel: agent.thinking,
+						onMessage: onProgress,
+					});
+				} finally {
+					stopHeartbeat?.();
+				}
 			}
 
 			// --- Chain mode ---
@@ -615,6 +628,7 @@ export default function (pi: ExtensionAPI) {
 						step.agent, taskWithContext, step.cwd,
 						signal, step.timeout ?? params.timeout,
 						(partial) => threadStore.updateThread(thread.id, { result: partial }),
+						() => makeDetails("chain")(results),
 					);
 					threadStore.updateThread(thread.id, {
 						status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
@@ -767,7 +781,8 @@ export default function (pi: ExtensionAPI) {
 								const result = await runOne(
 									t.agent, t.task, t.cwd,
 									parallelController.signal, t.timeout ?? params.timeout,
-								(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
+									(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
+									() => makeDetails("parallel")([...allResults]),
 								);
 								allResults[index] = result;
 								threadStore.updateThread(parallelThreads[index].id, {
@@ -823,6 +838,7 @@ export default function (pi: ExtensionAPI) {
 					params.agent, params.task, params.cwd,
 					signal, params.timeout,
 					(partial) => threadStore.updateThread(thread.id, { result: partial }),
+					() => makeDetails("single")([]),
 				);
 				threadStore.updateThread(thread.id, {
 					status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",

package/extensions/model.ts

@@ -5,14 +5,12 @@
  * (index.ts) and the event-driven service path (service.ts), ensuring
  * consistent error reporting across all sub-agent invocation paths.
  *
- * Queries the parent ModelRegistry first (catches custom-configured models
- * with overridden base URLs, headers, compatibility settings). Falls back
- * to the built-in registry for unconfigured models.
+ * Selects the first authenticated candidate reported by the parent
+ * ModelRegistry, then falls back to the authenticated parent model.
  * For unqualified names (no provider prefix), known naming conventions
  * are tried before assuming Anthropic.
  */
 
-import { getModel } from "@earendil-works/pi-ai/compat";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 
@@ -32,55 +30,38 @@ const KNOWN_PROVIDERS: [string, RegExp][] = [
 	["groq", /^(groq-|llama-)/i],
 ];
 
-function tryGetModel(
-	provider: string,
-	id: string,
-	modelRegistry?: ModelRegistry,
-): Model<any> | null {
-	// Query parent ModelRegistry first — it includes custom-configured models
-	// (overridden base URLs, headers, compatibility settings, per-model overrides).
-	// Fall back to built-in registry for unconfigured models.
-	if (modelRegistry) {
-		const found = modelRegistry.find(provider as any, id as any) ?? null;
-		if (found) return found;
-	}
-	const builtIn = getModel(provider as any, id as any) ?? null;
-	if (builtIn) return builtIn;
-	return null;
-}
-
-export function resolveModel(
-	modelName: string | undefined,
+export async function resolveModel(
+	modelNames: readonly string[],
 	parentModel: Model<any> | undefined,
 	modelRegistry?: ModelRegistry,
-): ResolvedModel {
+): Promise<ResolvedModel> {
 	const attempted: string[] = [];
-	if (modelName) {
+	const available = modelRegistry?.getAvailable() ?? [];
+	const byName = new Map(available.map((model) => [`${model.provider}/${model.id}`, model]));
+	const tryAvailable = (qualifiedName: string): Model<any> | undefined => {
+		if (!attempted.includes(qualifiedName)) attempted.push(qualifiedName);
+		return byName.get(qualifiedName);
+	};
+
+	for (const modelName of [...new Set(modelNames.map((name) => name.trim()).filter(Boolean))]) {
 		const idx = modelName.indexOf("/");
 		if (idx > 0) {
-			// Provider-qualified: "openai/gpt-4o" or "openrouter/anthropic/claude-3.5"
-			const provider = modelName.slice(0, idx);
-			const id = modelName.slice(idx + 1);
-			attempted.push(modelName);
-			const found = tryGetModel(provider, id, modelRegistry);
+			const found = tryAvailable(modelName);
 			if (found) return { model: found, attempted };
-		} else {
-			// Unqualified: try known providers by naming convention
-			for (const [provider, pattern] of KNOWN_PROVIDERS) {
-				if (pattern.test(modelName)) {
-					attempted.push(`${provider}/${modelName}`);
-					const found = tryGetModel(provider, modelName, modelRegistry);
-					if (found) return { model: found, attempted };
-				}
-			}
-			// Fall back to Anthropic shorthand (backward compat)
-			attempted.push(`anthropic/${modelName}`);
-			const found = tryGetModel("anthropic", modelName, modelRegistry);
+			continue;
+		}
+		for (const [provider, pattern] of KNOWN_PROVIDERS) {
+			if (!pattern.test(modelName)) continue;
+			const found = tryAvailable(`${provider}/${modelName}`);
 			if (found) return { model: found, attempted };
 		}
-	} else if (parentModel) {
-		attempted.push(`${parentModel.provider}/${parentModel.id}`);
-		return { model: parentModel, attempted };
+		const found = tryAvailable(`anthropic/${modelName}`);
+		if (found) return { model: found, attempted };
+	}
+
+	if (parentModel) {
+		const found = tryAvailable(`${parentModel.provider}/${parentModel.id}`);
+		if (found) return { model: found, attempted };
 	}
 	return { model: null, attempted };
 }

package/extensions/runner.ts

@@ -7,7 +7,7 @@
  *
  *   - Only the agent's system prompt is used (no pi defaults).
  *   - No AGENTS.md, no extensions, no skills, no prompt templates loaded.
- *   - Thinking disabled, compaction disabled, retry disabled.
+ *   - Thinking disabled, compaction disabled, one transient retry.
  *   - In-memory session (no disk I/O).
  *   - Shared auth/model infrastructure (no re-connection).
  *
@@ -63,6 +63,12 @@ export interface SubAgentResult {
 // Public API
 // ---------------------------------------------------------------------------
 
+export function startHeartbeat(onHeartbeat: () => void, intervalMs = 30_000): () => void {
+	const timer = setInterval(onHeartbeat, intervalMs);
+	timer.unref?.();
+	return () => clearInterval(timer);
+}
+
 export async function runSubAgent(options: {
 	cwd: string;
 	systemPrompt: string;
@@ -120,7 +126,7 @@ export async function runSubAgent(options: {
 
 	const settingsManager = SettingsManager.inMemory({
 		compaction: { enabled: false },
-		retry: { enabled: false },
+		retry: { enabled: true, maxRetries: 1 },
 	});
 
 	// Hoisted so the outer catch can clean up on early failure.
@@ -214,7 +220,7 @@ export async function runSubAgent(options: {
 										result.model = `${msg.provider || "?"}/${msg.model}`;
 									}
 									if (msg.stopReason) result.stopReason = msg.stopReason;
-									if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+									result.errorMessage = msg.errorMessage;
 								}
 								// Collect all messages for extraction
 								result.messages.push(msg as unknown as Message);
@@ -222,6 +228,7 @@ export async function runSubAgent(options: {
 								break;
 							}
 							case "agent_end": {
+								if (event.willRetry) break;
 								// agent_end carries all messages; use them if we haven't collected
 								if (result.messages.length === 0 && event.messages) {
 									result.messages = event.messages as unknown as Message[];
@@ -265,19 +272,16 @@ export async function runSubAgent(options: {
 			abortedBySignal = combinedSignal.aborted && !timedOut;
 
 			if (timedOut) {
-				result.exitCode = 1;
 				result.stopReason = "timeout";
-				result.errorMessage ||= `Timeout after ${timeoutMs}ms`;
+				result.errorMessage = `Timeout after ${timeoutMs}ms`;
 			} else if (abortedBySignal) {
-				result.exitCode = 1;
 				result.stopReason = "aborted";
 				result.errorMessage ||= "Sub-agent aborted";
-			} else {
-				result.exitCode = 0;
 			}
 
-			// Classify canonical status.
+			// Classify canonical status and keep the legacy exit code consistent.
 			result.status = classifyStopReason(result.stopReason, result.stopReason === "aborted", result.stopReason === "timeout");
+			result.exitCode = result.status === "success" || result.status === "partial" ? 0 : 1;
 
 			return result;
 		} finally {

package/extensions/service.ts

@@ -1,5 +1,5 @@
 import { AuthStorage, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { AgentConfig } from "./agents.ts";
+import { type AgentConfig, getModelCandidates } from "./agents.ts";
 import { runSubAgent, type SubAgentResult } from "./runner.ts";
 import { resolveModel } from "./model.ts";
 import {
@@ -39,7 +39,7 @@ export async function runNamedAgent(options: {
 	signal?: AbortSignal;
 	onMessage?: (result: SubAgentResult) => void;
 }): Promise<SubAgentResult> {
-	const { model, attempted } = resolveModel(options.agent.model, options.ctx.model, options.ctx.modelRegistry);
+	const { model, attempted } = await resolveModel(getModelCandidates(options.agent), options.ctx.model, options.ctx.modelRegistry);
 	if (!model) throw new Error(`No model resolved for agent "${options.agent.name}" (tried: ${attempted.join(", ") || "none"})`);
 
 	const authStorage = AuthStorage.inMemory();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",