@bacnh85/pi-subagent 0.8.1 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.9.1 (2026-07-16)
+
+### Activity-aware timeouts
+
+- Child `timeout` values now define a sliding inactivity window (three minutes by default); real SDK lifecycle events reset it while a fixed 20-minute hard cap remains.
+- `/agent` distinguishes real activity from transport heartbeats and reports idle versus hard timeouts.
+
+## 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

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.
@@ -83,12 +86,12 @@ Unknown or misspelled tool names produce clear diagnostics. Duplicate tool names
 
 Every child execution receives a timeout:
 
-- **Default:** 10 minutes (`DEFAULT_TIMEOUT_MS`)
-- **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.
+- **Default inactivity window:** 3 minutes (`DEFAULT_TIMEOUT_MS`); real SDK lifecycle activity resets it.
+- **Absolute cap:** 20 minutes for every child, even when active.
+- **Maximum requested inactivity window:** 60 minutes (`MAX_TIMEOUT_MS`); values must be positive integers.
+- Timeout diagnostics distinguish `Idle timeout` from `Hard timeout` and parent cancellation.
+- 30-second progress heartbeats only keep the parent transport alive; they never reset inactivity.
+- `/agent` shows last real activity and the remaining idle window; parallel tasks and chain steps may have per-item windows.
 
 ### Output safety
 
@@ -159,6 +162,7 @@ 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

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,8 +30,9 @@ 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 SubAgentProgress,
 	type SubAgentResult,
 	getFinalOutput,
 	getResultOutput,
@@ -94,14 +95,14 @@ const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds for this task" })),
+	timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in milliseconds for this task; real child activity resets it (default 3 minutes, absolute cap 20 minutes)" })),
 });
 
 const ChainItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent" })),
-	timeout: Type.Optional(Type.Number({ description: "Timeout in milliseconds for this step" })),
+	timeout: Type.Optional(Type.Number({ description: "Inactivity timeout in milliseconds for this step; real child activity resets it (default 3 minutes, absolute cap 20 minutes)" })),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -126,7 +127,7 @@ const SubagentParams = Type.Object({
 	// Project-agent confirmation is enforced via trusted configuration.
 	// See Security model section in README.
 	cwd: Type.Optional(Type.String({ description: "Working directory (single mode, must be inside workspace)" })),
-	timeout: Type.Optional(Type.Number({ description: "Global timeout in milliseconds for all sub-agents (overridden by per-task/step timeouts)" })),
+	timeout: Type.Optional(Type.Number({ description: "Global inactivity timeout in milliseconds (default 3 minutes; real activity resets it; fixed 20-minute absolute cap)" })),
 	instructions: Type.Optional(Type.String({ description: "Bounded repository/task instructions passed to each child (max 16 KB)" })),
 	abortOnFailure: Type.Optional(Type.Boolean({ description: "In parallel mode, cancel remaining tasks when one fails. Default: false.", default: false })),
 });
@@ -164,11 +165,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 {
@@ -177,9 +181,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.",
 		};
 	});
@@ -205,6 +209,7 @@ export default function (pi: ExtensionAPI) {
 			instructions: request.instructions,
 			signal: request.signal,
 			onMessage: (result) => threadStore.updateThread(thread.id, { result }),
+			onProgress: (progress) => { threadStore.updateProgress(thread.id, progress); request.onProgress?.(progress); },
 		}).then((result) => {
 			threadStore.updateThread(thread.id, {
 				status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
@@ -272,12 +277,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}`,
@@ -343,11 +349,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) {
@@ -516,7 +522,9 @@ export default function (pi: ExtensionAPI) {
 				parentSignal?: AbortSignal,
 				timeoutMs?: number,
 				onProgress?: (partial: SubAgentResult) => void,
+				onActivity?: (progress: SubAgentProgress) => void,
 				heartbeatDetails?: () => SubagentDetails,
+				onHeartbeat?: () => void,
 				isReadOnly?: boolean,
 			): Promise<SubAgentResult> {
 				const agent = agents.find((a) => a.name === agentName);
@@ -536,7 +544,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";
@@ -578,10 +586,10 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const stopHeartbeat = onUpdate ? startHeartbeat(() => onUpdate({
-					content: [{ type: "text", text: `Subagent ${agentName} is still running…` }],
-					details: heartbeatDetails?.() ?? makeDetails("single")([]),
-				})) : undefined;
+				const stopHeartbeat = onUpdate ? startHeartbeat(() => {
+					onHeartbeat?.();
+					onUpdate({ content: [{ type: "text", text: `Subagent ${agentName} is still running…` }], details: heartbeatDetails?.() ?? makeDetails("single")([]) });
+				}) : undefined;
 				try {
 					return await runSubAgent({
 						cwd: safeCwd,
@@ -598,6 +606,7 @@ export default function (pi: ExtensionAPI) {
 						agentName,
 						thinkingLevel: agent.thinking,
 						onMessage: onProgress,
+						onProgress: onActivity,
 					});
 				} finally {
 					stopHeartbeat?.();
@@ -624,7 +633,9 @@ export default function (pi: ExtensionAPI) {
 						step.agent, taskWithContext, step.cwd,
 						signal, step.timeout ?? params.timeout,
 						(partial) => threadStore.updateThread(thread.id, { result: partial }),
+						(progress) => threadStore.updateProgress(thread.id, progress),
 						() => makeDetails("chain")(results),
+						() => threadStore.refreshHeartbeat(thread.id),
 					);
 					threadStore.updateThread(thread.id, {
 						status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
@@ -778,7 +789,9 @@ export default function (pi: ExtensionAPI) {
 									t.agent, t.task, t.cwd,
 									parallelController.signal, t.timeout ?? params.timeout,
 									(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
+									(progress) => threadStore.updateProgress(parallelThreads[index].id, progress),
 									() => makeDetails("parallel")([...allResults]),
+									() => threadStore.refreshHeartbeat(parallelThreads[index].id),
 								);
 								allResults[index] = result;
 								threadStore.updateThread(parallelThreads[index].id, {
@@ -834,7 +847,9 @@ export default function (pi: ExtensionAPI) {
 					params.agent, params.task, params.cwd,
 					signal, params.timeout,
 					(partial) => threadStore.updateThread(thread.id, { result: partial }),
+					(progress) => threadStore.updateProgress(thread.id, progress),
 					() => makeDetails("single")([]),
+					() => threadStore.refreshHeartbeat(thread.id),
 				);
 				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).
  *
@@ -45,6 +45,18 @@ export interface UsageStats {
 	turns: number;
 }
 
+export const DEFAULT_INACTIVITY_TIMEOUT_MS = 3 * 60 * 1000;
+export const HARD_TIMEOUT_MS = 20 * 60 * 1000;
+
+export interface SubAgentProgress {
+	label: string;
+	at: number;
+	elapsedMs: number;
+	inactivityDeadline: number;
+	hardDeadline: number;
+	result: SubAgentResult;
+}
+
 export interface SubAgentResult {
 	agent: string;
 	task: string;
@@ -81,233 +93,110 @@ export async function runSubAgent(options: {
 	agentName?: string;
 	thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	onMessage?: (partialResult: SubAgentResult) => void;
-	/** Pre-validated timeout in ms. When provided, an abort signal will be created. */
+	onProgress?: (progress: SubAgentProgress) => void;
 	timeoutMs?: number;
+	hardTimeoutMs?: number;
 }): Promise<SubAgentResult> {
 	const {
-		cwd,
-		systemPrompt,
-		task,
-		tools,
-		model,
-		authStorage,
-		modelRegistry,
-		signal,
-		agentName = "subagent",
-		thinkingLevel = "off",
-		onMessage,
-		timeoutMs,
+		cwd, systemPrompt, task, tools, model, authStorage, modelRegistry, signal,
+		agentName = "subagent", thinkingLevel = "off", onMessage, onProgress,
+		timeoutMs = DEFAULT_INACTIVITY_TIMEOUT_MS, hardTimeoutMs = HARD_TIMEOUT_MS,
 	} = options;
-
 	const result: SubAgentResult = {
-		agent: agentName,
-		task,
-		exitCode: 0,
-		messages: [],
-		stderr: "",
+		agent: agentName, task, exitCode: 0, messages: [], stderr: "",
 		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-		model: `${model.provider}/${model.id}`,
-		status: undefined,
+		model: `${model.provider}/${model.id}`, status: undefined,
 	};
-
-	// Build a minimal resource loader. The sub-agent sees ONLY the agent's
-	// system prompt — no pi defaults, no AGENTS.md, no extensions, no skills.
 	const resourceLoader: ResourceLoader = {
 		getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
-		getSkills: () => ({ skills: [], diagnostics: [] }),
-		getPrompts: () => ({ prompts: [], diagnostics: [] }),
-		getThemes: () => ({ themes: [], diagnostics: [] }),
-		getAgentsFiles: () => ({ agentsFiles: [] }),
-		getSystemPrompt: () => systemPrompt,
-		getAppendSystemPrompt: () => [],
-		extendResources: () => {},
-		reload: async () => {},
+		getSkills: () => ({ skills: [], diagnostics: [] }), getPrompts: () => ({ prompts: [], diagnostics: [] }),
+		getThemes: () => ({ themes: [], diagnostics: [] }), getAgentsFiles: () => ({ agentsFiles: [] }),
+		getSystemPrompt: () => systemPrompt, getAppendSystemPrompt: () => [], extendResources: () => {}, reload: async () => {},
 	};
-
-	const settingsManager = SettingsManager.inMemory({
-		compaction: { enabled: false },
-		retry: { enabled: false },
-	});
-
-	// Hoisted so the outer catch can clean up on early failure.
-	let timeoutController: AbortController | undefined;
-	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+	const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: true, maxRetries: 1 } });
+	const startedAt = Date.now();
+	let inactivityDeadline = startedAt + timeoutMs;
+	const hardDeadline = startedAt + hardTimeoutMs;
+	let timeoutKind: "idle" | "hard" | undefined;
+	const timeoutController = new AbortController();
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let hardTimer: ReturnType<typeof setTimeout> | undefined;
 	let cleanupCombined: (() => void) | undefined;
-
+	const clearTimers = () => { if (idleTimer) clearTimeout(idleTimer); if (hardTimer) clearTimeout(hardTimer); };
+	const armIdle = () => {
+		if (idleTimer) clearTimeout(idleTimer);
+		inactivityDeadline = Date.now() + timeoutMs;
+		idleTimer = setTimeout(() => { timeoutKind = "idle"; timeoutController.abort(new Error(`Idle timeout after ${timeoutMs}ms`)); }, timeoutMs);
+	};
+	const snapshot = (label: string): SubAgentProgress => ({ label, at: Date.now(), elapsedMs: Date.now() - startedAt, inactivityDeadline, hardDeadline, result: { ...result, messages: [...result.messages] } });
 	try {
-		// Build combined signal from parent signal and timeout
-		const signalsToCombine: (AbortSignal | undefined | null | false)[] = [signal];
-
-		// Create timeout controller
-		if (timeoutMs && timeoutMs > 0) {
-			timeoutController = new AbortController();
-			timeoutId = setTimeout(() => timeoutController!.abort(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs);
-			signalsToCombine.push(timeoutController.signal);
-		}
-
-		const { signal: combinedSignal, cleanup: cleanupCb } = createCombinedAbortSignal(signalsToCombine);
-		cleanupCombined = cleanupCb;
-
+		armIdle();
+		hardTimer = setTimeout(() => { timeoutKind = "hard"; timeoutController.abort(new Error(`Hard timeout after ${hardTimeoutMs}ms`)); }, hardTimeoutMs);
+		const { signal: combinedSignal, cleanup } = createCombinedAbortSignal([signal, timeoutController.signal]);
+		cleanupCombined = cleanup;
 		if (combinedSignal.aborted) {
 			result.exitCode = 1;
-			const isTimeout = timeoutController?.signal.aborted === true && signal?.aborted !== true;
-			result.stopReason = isTimeout ? "timeout" : "aborted";
-			result.errorMessage = combinedSignal.reason instanceof Error ? combinedSignal.reason.message : "Sub-agent aborted before start";
-			result.status = classifyStopReason(result.stopReason, !isTimeout, isTimeout);
-			cleanupCombined?.();
-			if (timeoutId) clearTimeout(timeoutId);
+			const timedOut = timeoutController.signal.aborted && !signal?.aborted;
+			result.stopReason = timedOut ? "timeout" : "aborted";
+			result.errorMessage = timedOut ? `${timeoutKind === "idle" ? "Idle" : "Hard"} timeout after ${timeoutKind === "idle" ? timeoutMs : hardTimeoutMs}ms` : "Sub-agent aborted before start";
+			result.status = classifyStopReason(result.stopReason, !timedOut, timedOut);
 			return result;
 		}
-
-		const { session } = await createAgentSession({
-			cwd,
-			model,
-			thinkingLevel,
-			authStorage,
-			modelRegistry,
-			resourceLoader,
-			tools,
-			sessionManager: SessionManager.inMemory(cwd),
-			settingsManager,
-		});
-
-		let cleanupAbort: (() => void) | undefined;
-		let cleanupEventAbort: (() => void) | undefined;
-		let abortedBySignal = false;
-		let timedOut = false;
-		let eventUnsubscribe: (() => void) | undefined;
-
+		const { session } = await createAgentSession({ cwd, model, thinkingLevel, authStorage, modelRegistry, resourceLoader, tools, sessionManager: SessionManager.inMemory(cwd), settingsManager });
+		let unsubscribe: (() => void) | undefined;
+		let removeAbort: (() => void) | undefined;
 		try {
-			// Wire combined abort signal to session
-			const onAbort = () => {
-				session.abort();
-			};
-			if (combinedSignal.aborted) {
-				abortedBySignal = true;
-				timedOut = timeoutController?.signal.aborted === true && signal?.aborted !== true;
-				onAbort();
-				return result;
-			}
-			combinedSignal.addEventListener("abort", onAbort, { once: true });
-			cleanupAbort = () => combinedSignal.removeEventListener("abort", onAbort);
-
-			// Collect all messages and usage stats from events
-			const eventPromise = new Promise<void>((resolve, reject) => {
-				let settled = false;
-				const finish = (fn: () => void) => {
-					if (settled) return;
-					settled = true;
-					fn();
-				};
-
-				let unsubscribe: (() => void) | undefined;
+			const eventDone = new Promise<void>((resolve, reject) => {
+				let done = false;
+				const finish = (fn: () => void) => { if (!done) { done = true; unsubscribe?.(); fn(); } };
 				unsubscribe = session.subscribe((event) => {
 					try {
-						switch (event.type) {
-							case "message_end": {
-								const msg = event.message as AgentMessage;
-								if (msg.role === "assistant") {
-									result.usage.turns++;
-									if (msg.usage) {
-										result.usage.input += msg.usage.input || 0;
-										result.usage.output += msg.usage.output || 0;
-										result.usage.cacheRead += msg.usage.cacheRead || 0;
-										result.usage.cacheWrite += msg.usage.cacheWrite || 0;
-										result.usage.cost += msg.usage.cost?.total || 0;
-										result.usage.contextTokens = msg.usage.totalTokens || 0;
-									}
-									if (!result.model && msg.model) {
-										result.model = `${msg.provider || "?"}/${msg.model}`;
-									}
-									if (msg.stopReason) result.stopReason = msg.stopReason;
-									if (msg.errorMessage) result.errorMessage = msg.errorMessage;
-								}
-								// Collect all messages for extraction
-								result.messages.push(msg as unknown as Message);
-								if (onMessage) onMessage({ ...result, messages: [...result.messages] });
-								break;
-							}
-							case "agent_end": {
-								// 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[];
-								}
-								finish(() => {
-									unsubscribe?.();
-									resolve();
-								});
-								break;
+						// Any SDK session lifecycle event is actual child activity, unlike a parent heartbeat.
+						armIdle(); onProgress?.(snapshot(event.type));
+						if (event.type === "message_end") {
+							const msg = event.message as AgentMessage;
+							if (msg.role === "assistant") {
+								result.usage.turns++;
+								if (msg.usage) { result.usage.input += msg.usage.input || 0; result.usage.output += msg.usage.output || 0; result.usage.cacheRead += msg.usage.cacheRead || 0; result.usage.cacheWrite += msg.usage.cacheWrite || 0; result.usage.cost += msg.usage.cost?.total || 0; result.usage.contextTokens = msg.usage.totalTokens || 0; }
+								if (!result.model && msg.model) result.model = `${msg.provider || "?"}/${msg.model}`;
+								if (msg.stopReason) result.stopReason = msg.stopReason;
+								result.errorMessage = msg.errorMessage;
 							}
+							result.messages.push(msg as unknown as Message);
+							onMessage?.({ ...result, messages: [...result.messages] });
+						} else if (event.type === "agent_end" && !event.willRetry) {
+							if (!result.messages.length && event.messages) result.messages = event.messages as unknown as Message[];
+							finish(resolve);
 						}
-					} catch (err) {
-						finish(() => {
-							unsubscribe?.();
-							reject(err);
-						});
-					}
+					} catch (error) { finish(() => reject(error)); }
 				});
-				eventUnsubscribe = unsubscribe;
-
-				// Resolve on abort so the eventPromise doesn't hang
-				const onAbortResolve = () => {
-					finish(() => {
-						result.exitCode = 1;
-						if (!result.errorMessage) result.errorMessage = "Sub-agent aborted";
-						unsubscribe?.();
-						resolve();
-					});
-				};
-				combinedSignal.addEventListener("abort", onAbortResolve, { once: true });
-				cleanupEventAbort = () => combinedSignal.removeEventListener("abort", onAbortResolve);
+				const abort = () => finish(resolve);
+				combinedSignal.addEventListener("abort", abort, { once: true });
+				removeAbort = () => combinedSignal.removeEventListener("abort", abort);
 			});
-
-			await Promise.race([
-				session.prompt(task),
-				eventPromise,
-			]);
-
-			// Detect timeout vs. parent abort.
-			timedOut = timeoutController?.signal.aborted === true && signal?.aborted !== true;
-			abortedBySignal = combinedSignal.aborted && !timedOut;
-
-			if (timedOut) {
-				result.exitCode = 1;
-				result.stopReason = "timeout";
-				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.
+			const abortSession = () => session.abort();
+			combinedSignal.addEventListener("abort", abortSession, { once: true });
+			const removeSessionAbort = () => combinedSignal.removeEventListener("abort", abortSession);
+			await Promise.race([session.prompt(task), eventDone]);
+			removeSessionAbort();
+			const timedOut = timeoutController.signal.aborted && !signal?.aborted;
+			if (timedOut) { result.stopReason = "timeout"; result.errorMessage = `${timeoutKind === "idle" ? "Idle" : "Hard"} timeout after ${timeoutKind === "idle" ? timeoutMs : hardTimeoutMs}ms`; }
+			else if (combinedSignal.aborted) { result.stopReason = "aborted"; result.errorMessage ||= "Sub-agent aborted"; }
 			result.status = classifyStopReason(result.stopReason, result.stopReason === "aborted", result.stopReason === "timeout");
-
+			result.exitCode = result.status === "success" || result.status === "partial" ? 0 : 1;
 			return result;
 		} finally {
-			cleanupAbort?.();
-			cleanupEventAbort?.();
-			cleanupCombined();
-			eventUnsubscribe?.();
-			if (timeoutId) clearTimeout(timeoutId);
-			try {
-				session.dispose();
-			} catch {
-				// Best-effort cleanup
-			}
+			unsubscribe?.(); removeAbort?.();
+			try { session.dispose(); } catch { /* best effort */ }
 		}
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
+	} catch (error) {
 		result.exitCode = 1;
-		result.errorMessage = message;
-		if (!result.stopReason) result.stopReason = "error";
-		result.status = classifyStopReason("error", false, false);
-		// Ensure cleanup runs even when the outer try fails before the inner finally.
-		cleanupCombined?.();
-		if (timeoutId) clearTimeout(timeoutId);
+		result.errorMessage = error instanceof Error ? error.message : String(error);
+		result.stopReason ||= "error";
+		result.status = classifyStopReason(result.stopReason, false, false);
 		return result;
+	} finally {
+		clearTimers(); cleanupCombined?.();
 	}
 }
 

package/extensions/security.ts

@@ -28,11 +28,10 @@ export const MUTATION_TOOLS: readonly string[] = ["edit", "write"];
 export const EXECUTION_TOOLS: readonly string[] = ["bash"];
 
 /**
- * Default timeout applied to every child execution unless an explicit timeout
- * is provided. Children may request a shorter-but-not-longer timeout within
- * the allowed range.
+ * Default inactivity timeout. Real SDK lifecycle activity resets this window;
+ * the runner separately enforces a fixed 20-minute absolute cap.
  */
-export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes
+export const DEFAULT_TIMEOUT_MS = 3 * 60 * 1_000; // 3 minutes
 
 /**
  * Absolute maximum timeout. Any requested value above this cap is rejected

package/extensions/service.ts

@@ -1,6 +1,6 @@
 import { AuthStorage, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { AgentConfig } from "./agents.ts";
-import { runSubAgent, type SubAgentResult } from "./runner.ts";
+import { type AgentConfig, getModelCandidates } from "./agents.ts";
+import { runSubAgent, type SubAgentProgress, type SubAgentResult } from "./runner.ts";
 import { resolveModel } from "./model.ts";
 import {
 	validateAgentTools,
@@ -23,6 +23,7 @@ export interface SubagentRunRequest {
 	signal?: AbortSignal;
 	accept?: () => boolean;
 	respond: (response: SubagentRunResponse) => void;
+	onProgress?: (progress: SubAgentProgress) => void;
 }
 
 export type SubagentRunResponse =
@@ -38,8 +39,9 @@ export async function runNamedAgent(options: {
 	instructions?: string;
 	signal?: AbortSignal;
 	onMessage?: (result: SubAgentResult) => void;
+	onProgress?: (progress: SubAgentProgress) => 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();
@@ -88,6 +90,7 @@ export async function runNamedAgent(options: {
 			agentName: options.agent.name,
 			thinkingLevel: options.agent.thinking,
 			onMessage: options.onMessage,
+			onProgress: options.onProgress,
 		});
 		return result;
 	} finally {

package/extensions/thread-viewer.ts

@@ -146,6 +146,14 @@ export class ThreadViewer {
 		lines.push(truncateToWidth(t.fg("dim", this.thread.task), width));
 		lines.push("");
 
+		if (status === "running") {
+			const now = Date.now();
+			const elapsed = Math.floor((now - this.thread.createdAt) / 1000);
+			const activity = this.thread.lastActivityAt ? `${Math.floor((now - this.thread.lastActivityAt) / 1000)}s ago (${this.thread.lastActivityLabel})` : "none yet";
+			const idleMs = this.thread.inactivityDeadline ? this.thread.inactivityDeadline - now : 0;
+			const idle = this.thread.inactivityDeadline ? `${Math.max(0, Math.ceil(idleMs / 1000))}s remaining` : "pending";
+			lines.push(truncateToWidth(t.fg(idleMs < 30_000 ? "warning" : "muted", `Elapsed ${elapsed}s · last activity ${activity} · idle ${idle}`), width));
+		}
 		if (status === "running" && (!result || result.messages.length === 0)) {
 			lines.push(truncateToWidth(t.fg("muted", "(waiting for first message...)"), width));
 		} else if (result) {

package/extensions/threads.ts

@@ -6,7 +6,7 @@
  * Supports subscriptions so UIs can react to thread status changes.
  */
 
-import type { SubAgentResult } from "./runner.ts";
+import type { SubAgentProgress, SubAgentResult } from "./runner.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -26,6 +26,11 @@ export interface SubagentThread {
 	color?: string;
 	createdAt: number;
 	updatedAt: number;
+	lastActivityAt?: number;
+	lastActivityLabel?: string;
+	lastHeartbeatAt?: number;
+	inactivityDeadline?: number;
+	hardDeadline?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -84,6 +89,26 @@ export class ThreadStore {
 		this.notify();
 	}
 
+	updateProgress(id: string, progress: SubAgentProgress): void {
+		const thread = this.threads.get(id);
+		if (!thread) return;
+		thread.result = progress.result;
+		thread.lastActivityAt = progress.at;
+		thread.lastActivityLabel = progress.label;
+		thread.inactivityDeadline = progress.inactivityDeadline;
+		thread.hardDeadline = progress.hardDeadline;
+		thread.updatedAt = Date.now();
+		this.notify();
+	}
+
+	refreshHeartbeat(id: string): void {
+		const thread = this.threads.get(id);
+		if (!thread) return;
+		thread.lastHeartbeatAt = Date.now();
+		thread.updatedAt = thread.lastHeartbeatAt;
+		this.notify();
+	}
+
 	getThread(id: string): SubagentThread | undefined {
 		return this.threads.get(id);
 	}

package/package.json

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