@bacnh85/pi-subagent 0.4.1 → 0.5.0

package/README.md

@@ -1,100 +1,52 @@
 # pi-subagent
 
-Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context — running in-process via the pi SDK for zero spawn overhead and ~10x fewer tokens than process-spawning.
-
-## Features
-
-- **In-process execution**: Uses `createAgentSession()` directly — no `spawn("pi")` overhead
-- **Minimal token budget**: Only the agent's system prompt (no AGENTS.md, no extensions, no thinking)
-- **Streaming progress**: Real-time tool-call and text updates during execution
-- **Three modes**: single, parallel (max 8 tasks, 4 concurrent), chain (sequential with `{previous}`)
-- **Abort support**: Esc propagates to all sub-agents
-- **TUI rendering**: Collapsed/expanded views with tool-call formatting and usage stats
-- **Bundled agents**: scout, reviewer, worker — overridable with your own
-- **Thread viewing**: `/agent` slash command to view subagent threads in isolation
+Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads.
 
 ## Install
 
 ```bash
-cd extensions/pi-subagent
-npm install
-cd ../..
-pi install ./extensions/pi-subagent
-```
-
-Or test directly:
-
-```bash
-pi -e ./extensions/pi-subagent
+pi install npm:@bacnh85/pi-subagent
+# local checkout
+pi install ./pi-subagent
 ```
 
-## Usage
+## Bundled roles
 
-### Thread Viewing (`/agent`)
+| Role | Model | Thinking | Tools |
+| --- | --- | --- | --- |
+| `scout` | parent model | low | read, grep, find, ls |
+| `reviewer` | parent model | high | read, grep, find, ls |
+| `worker` | parent model | medium | standard coding tools |
+| `general-purpose` | parent model | off | standard coding tools |
 
-After running subagents, type `/agent` to view individual subagent threads:
+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`.
 
-1. A picker shows `Main [default]` + all subagent threads with status icons
-2. Select a thread to view its full output (task, tool calls, final result, usage stats)
-3. Within the viewer: `Esc` to close, `Alt+←`/`Alt+→` to cycle between threads, `↑/↓` to scroll
+## Agent files
 
-This is useful when running many parallel subagents — instead of Ctrl+O to
-see all output at once, you can focus on one thread at a time.
-
-### Single agent
-
-```
-Use scout to find authentication code in this project
-```
-
-### Parallel execution
-
-```
-Run 2 scouts in parallel: one for models, one for providers
-```
-
-### Chain workflow
-
-```
-Chain: scout finds auth code, then reviewer checks it for security issues
-```
-
-## Included Agents
-
-| Agent | Model | Tools | Purpose |
-|-------|-------|-------|---------|
-| `scout` | Haiku | read, grep, find, ls | Fast codebase recon |
-| `reviewer` | Sonnet | read, grep, find, ls, bash | Code review |
-| `worker` | Sonnet | all | General implementation |
-
-## Custom Agents
-
-Create Markdown files with YAML frontmatter in `~/.pi/agent/agents/` (user-level) or `.pi/agents/` (project-level):
+Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
 
 ```markdown
 ---
-name: my-agent
-description: When to use this agent
-tools: read, grep, find, ls, bash
-model: claude-haiku-4-5
+name: scout-fast
+description: Locate relevant files and symbols
+tools: read, grep, find, ls
+thinking: low
+model: optional-provider/optional-model
 ---
 
-Your system prompt here. This is the ONLY prompt the sub-agent sees.
+Return concise evidence with file/symbol anchors.
 ```
 
-See `agent-format.md` for the full format specification.
+Project agents require confirmation when requested through the public tool. Definitions are cached with file-signature invalidation; `/subagent reload` clears the cache.
+
+## Context and limits
 
-## Architecture
+Children use in-memory SDK sessions with no extensions, skills, prompt templates, or automatic `AGENTS.md` loading. The optional `instructions` argument passes a bounded 16 KB task/repository contract. Only Pi built-in tools are available; Serena, FFF, web, and Munin are not available in lean children.
 
-Sub-agents run in-process via the pi SDK. Compared to the process-spawn approach (spawning `pi --mode json`), this saves ~4-11K tokens per sub-agent invocation by:
+Threads are session-memory only and are cleared when Pi replaces or reloads the session. Timeout and parent cancellation propagate to child sessions. Subagents cannot recursively invoke `subagent`.
 
-- Using only the agent's system prompt (no pi defaults)
-- Skipping AGENTS.md, extensions, skills, prompt templates
-- Disabling thinking, compaction, retry
-- Using in-memory sessions (no disk I/O)
-- Sharing the parent's auth/model infrastructure
+## Extension contract
 
-## Requirements
+`pi-subagent` owns the `pi-subagent:run` event contract for one named-agent request. `pi-review` uses it for isolated review. Requests use an immediate boolean `accept()` claim and exactly one `respond()` callback; this suppresses duplicate responders while missing services and timeouts remain caller-controlled.
 
-- pi coding agent with configured API keys
-- Peer dependencies satisfied by the pi runtime (no extra npm install needed)
+See [`agent-format.md`](./agent-format.md) for all frontmatter fields.

package/agent-format.md

@@ -8,7 +8,7 @@ Sub-agents are defined as Markdown files with YAML frontmatter.
 |----------|-------|
 | `~/.pi/agent/agents/*.md` | User-level (all projects) |
 | `.pi/agents/*.md` | Project-level |
-| `<skill>/agents/*.md` | Bundled with pi-sugagents |
+| `<package>/agents/*.md` | Bundled with pi-subagent |
 
 Project agents override user agents with the same name when `agentScope: "both"`.
 
@@ -19,7 +19,8 @@ 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: claude-haiku-4-5 # Optional. Model ID. Defaults to parent's model.
+model: provider/model     # Optional. Defaults to parent's model.
+thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
 ---
 ```
 
@@ -47,13 +48,17 @@ Model IDs are resolved via `getModel("provider", "id")`. Common values:
 
 If not specified, defaults to the parent session's model.
 
+## Instruction handoff
+
+Children do not automatically load repository instructions. Callers may pass an `instructions` task contract, truncated to 16 KB. Use this for relevant repository rules or review contracts rather than copying the parent transcript.
+
 ## Token Budget
 
 Each sub-agent runs with:
 - **System prompt**: agent body only (~200-1K tokens typical)
 - **No AGENTS.md**: saves 500-5K tokens
 - **No extensions/skills loaded**: saves 200-1K tokens
-- **Thinking off**: saves reasoning overhead
+- **Thinking per role**: defaults off; bundled scout/reviewer/worker choose low/high/medium
 - **No compaction**: avoids compaction token cost
 
 This is ~10x leaner than spawning a full `pi` process.

package/agents/reviewer.md

@@ -1,30 +1,36 @@
 ---
 name: reviewer
-description: Code review specialist. Use for reviewing changes, finding bugs, suggesting improvements.
-tools: read, grep, find, ls, bash
-model: openai-codex/gpt-5.5
+description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
+tools: read, grep, find, ls
+thinking: high
 ---
 
-You are a senior code reviewer. Review code changes and provide specific, actionable feedback.
+You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.
 
-Focus on:
-1. **Correctness**: Logic errors, edge cases, off-by-one
-2. **Security**: Injection risks, auth bypasses, data leaks
-3. **Performance**: N+1 queries, unnecessary allocations, blocking calls
-4. **Maintainability**: Unclear naming, missing error handling, tight coupling
-5. **Best practices**: Idiomatic patterns, testability, documentation
+Focus only on actionable issues introduced by the reviewed change:
+1. Correctness and edge cases
+2. Security and data loss
+3. Regressions and API compatibility
+4. Missing tests that allow a likely bug to escape
 
-Output format:
+Avoid style noise, praise, and speculative redesign. Every finding needs code evidence.
 
-## Summary
-Brief assessment (1-2 sentences)
+Return JSON only:
+```json
+{
+  "summary": "compact scope/result summary",
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "file": "relative/path",
+      "line": 1,
+      "issue": "what is wrong and why it matters",
+      "evidence": "specific inspected code evidence",
+      "suggestedFix": "smallest safe fix",
+      "blocking": true
+    }
+  ]
+}
+```
 
-## Issues Found
-For each issue:
-- **Severity**: critical | high | medium | low
-- **File**: path with line numbers
-- **Problem**: What's wrong
-- **Fix**: Suggested change (code block)
-
-## Overall Assessment
-Green/yellow/red with reasoning.
+Use an empty `findings` array when clean. Do not modify files or Git state.

package/agents/scout.md

@@ -2,7 +2,7 @@
 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
-model: opencode-go/deepseek-v4-flash
+thinking: low
 ---
 
 You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
@@ -22,8 +22,8 @@ Strategy:
 
 Output format:
 
-## Files Retrieved
-List with exact line ranges:
+## Evidence
+List exact file/symbol anchors and relevant line ranges:
 1. `path/to/file.ts` (lines 10-50) - Description of what's here
 2. `path/to/other.ts` (lines 100-150) - Description
 3. ...

package/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 name: worker
-description: General-purpose coding agent with full tool access. Use for implementation, refactoring, debugging, and complex multi-step tasks.
-model: opencode-go/deepseek-v4-pro
+description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
+thinking: medium
 ---
 
 You are a skilled software engineer. Implement the requested task with care and precision.

package/{agents.ts → extensions/agents.ts}

@@ -1,5 +1,5 @@
 /**
- * Agent discovery and configuration for pi-sugagents.
+ * Agent discovery and configuration for pi-subagent.
  *
  * Loads agent definitions from Markdown files with YAML frontmatter.
  * Discovers from user-level (~/.pi/agent/agents/), project-level
@@ -18,6 +18,7 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	systemPrompt: string;
 	source: "user" | "project" | "bundled";
 	filePath: string;
@@ -86,6 +87,9 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+			thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
+				? frontmatter.thinking as AgentConfig["thinking"]
+				: undefined,
 			systemPrompt: body,
 			source,
 			filePath,

package/{index.ts → extensions/index.ts}

@@ -15,13 +15,13 @@
 
 import * as path from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
-import { getModel } from "@earendil-works/pi-ai/compat";
 import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	AuthStorage,
 	CONFIG_DIR_NAME,
 	DynamicBorder,
 	type ExtensionAPI,
+	type ExtensionContext,
 	getAgentDir,
 	getMarkdownTheme,
 	ModelRegistry,
@@ -44,6 +44,7 @@ import {
 	renderSingleResult,
 } from "./render.ts";
 import { type SubagentThread, threadStore } from "./threads.ts";
+import { SUBAGENT_REQUEST_EVENT, runNamedAgent, type SubagentRunRequest } from "./service.ts";
 import { ThreadViewer, type ThreadViewerCallbacks } from "./thread-viewer.ts";
 
 // ---------------------------------------------------------------------------
@@ -54,6 +55,8 @@ const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
 const PER_TASK_OUTPUT_CAP = 50 * 1024; // 50 KB per parallel task
 
+import { resolveModel } from "./model.ts";
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -69,35 +72,6 @@ function truncateParallelOutput(output: string): string {
 	return `${truncated}\n\n[Output truncated: ${byteLength - Buffer.byteLength(truncated, "utf8")} bytes omitted.]`;
 }
 
-interface ResolvedModel {
-	model: Model | null;
-	attempted: string[];
-}
-
-function resolveModel(
-	modelName: string | undefined,
-	parentModel: Model | undefined,
-): ResolvedModel {
-	const attempted: string[] = [];
-	if (modelName) {
-		// Try as provider/id first, then fall back to anthropic/id
-		const parts = modelName.split("/");
-		if (parts.length === 2) {
-			attempted.push(modelName);
-			const found = getModel(parts[0], parts[1]) ?? null;
-			if (found) return { model: found, attempted };
-		} else {
-			// Assume Anthropic shorthand
-			attempted.push(`anthropic/${modelName}`);
-			const found = getModel("anthropic", modelName) ?? null;
-			if (found) return { model: found, attempted };
-		}
-	} else if (parentModel) {
-		attempted.push(`${parentModel.provider}/${parentModel.id}`);
-		return { model: parentModel, attempted };
-	}
-	return { model: null, attempted };
-}
 
 // ---------------------------------------------------------------------------
 // Tool parameter schema
@@ -143,6 +117,7 @@ const SubagentParams = Type.Object({
 	),
 	cwd: Type.Optional(Type.String({ description: "Working directory (single mode)" })),
 	timeout: Type.Optional(Type.Number({ description: "Global timeout in milliseconds for all sub-agents (overridden by per-task/step timeouts)" })),
+	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 })),
 });
 
@@ -162,8 +137,11 @@ interface SubagentDetails {
 // ---------------------------------------------------------------------------
 
 export default function (pi: ExtensionAPI) {
-	// Invalidate agent cache + clear thread store on reload
-	pi.on("session_start", (event) => {
+	let currentCtx: ExtensionContext | undefined;
+
+	// Invalidate agent cache + clear thread store on session replacement.
+	pi.on("session_start", (event, ctx) => {
+		currentCtx = ctx;
 		if (event.reason === "reload") invalidateAgentCache();
 		threadStore.clear();
 	});
@@ -180,22 +158,43 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
-	// Inject available agent list into system prompt on every session
-	pi.on("before_agent_start", async (event, ctx) => {
-		const discovery = discoverAgents(ctx.cwd, "both", bundledAgentsDir);
-		if (discovery.agents.length > 0) {
-			const names = discovery.agents.map(a => a.name).join(", ");
-			return {
-				systemPrompt:
-					event.systemPrompt +
-					`\n\nAvailable sub-agents: ${names}. Use /subagent for details.`,
-			};
+	// Resolve bundled agents directory relative to this extension file
+	const bundledAgentsDir = path.resolve(__dirname, "../agents");
+
+	// Public one-request/one-response service used by pi-review.
+	pi.events.on(SUBAGENT_REQUEST_EVENT, (raw) => {
+		const request = raw as SubagentRunRequest;
+		const ctx = currentCtx;
+		if (!ctx || !request?.id || typeof request.respond !== "function") return;
+		if (request.accept && !request.accept()) return;
+		const agent = discoverAgents(ctx.cwd, "user", bundledAgentsDir).agents.find((item) => item.name === request.agent);
+		if (!agent) {
+			request.respond({ id: request.id, ok: false, error: `Unknown agent: ${request.agent}` });
+			return;
 		}
+		const thread = threadStore.createThread({ agentName: agent.name, task: request.task, mode: "single" });
+		void runNamedAgent({
+			agent: request.readOnly ? { ...agent, tools: ["read", "grep", "find", "ls"] } : agent,
+			task: request.task,
+			cwd: request.cwd ?? ctx.cwd,
+			ctx,
+			timeout: request.timeout,
+			instructions: request.instructions,
+			signal: request.signal,
+			onMessage: (result) => threadStore.updateThread(thread.id, { result }),
+		}).then((result) => {
+			threadStore.updateThread(thread.id, {
+				status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+				result,
+			});
+			if (isFailedResult(result)) request.respond({ id: request.id, ok: false, error: getResultOutput(result) });
+			else request.respond({ id: request.id, ok: true, result });
+		}, (error) => {
+			threadStore.updateThread(thread.id, { status: "failed" });
+			request.respond({ id: request.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+		});
 	});
 
-	// Resolve bundled agents directory relative to this extension file
-	const bundledAgentsDir = path.resolve(__dirname, "agents");
-
 	// /subagent command — list available agents
 	pi.registerCommand("subagent", {
 		description: "List available sub-agents, reload agent definitions, or show agent details",
@@ -246,6 +245,7 @@ export default function (pi: ExtensionAPI) {
 						`Agent: ${agent.name} (${agent.source})`,
 						`Description: ${agent.description}`,
 						`Model: ${agent.model || "inherits from parent"}`,
+						`Thinking: ${agent.thinking || "off"}`,
 						`Tools: ${agent.tools?.join(", ") || "all default"}`,
 						`Source file: ${agent.filePath}`,
 						"",
@@ -326,12 +326,8 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
-			// Confirm project-local agents
-			if (
-				(agentScope === "project" || agentScope === "both") &&
-				confirmProjectAgents &&
-				ctx.hasUI
-			) {
+			// Handle project-local agent confirmation
+			if (agentScope === "project" || agentScope === "both") {
 				const requestedAgentNames = new Set<string>();
 				if (params.chain) for (const s of params.chain) requestedAgentNames.add(s.agent);
 				if (params.tasks) for (const t of params.tasks) requestedAgentNames.add(t.agent);
@@ -341,16 +337,30 @@ export default function (pi: ExtensionAPI) {
 					.map((name) => agents.find((a) => a.name === name))
 					.filter((a): a is AgentConfig => a?.source === "project");
 
-				if (projectAgentsRequested.length > 0) {
-					const names = projectAgentsRequested.map((a) => a.name).join(", ");
-					const dir = discovery.projectAgentsDir ?? "(unknown)";
-					const ok = await ctx.ui.confirm(
-						"Run project-local agents?",
-						`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
-					);
-					if (!ok) {
+				if (projectAgentsRequested.length > 0 && confirmProjectAgents) {
+					if (ctx.hasUI) {
+						const names = projectAgentsRequested.map((a) => a.name).join(", ");
+						const dir = discovery.projectAgentsDir ?? "(unknown)";
+						const ok = await ctx.ui.confirm(
+							"Run project-local agents?",
+							`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
+						);
+						if (!ok) {
+							return {
+								content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
+								details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+							};
+						}
+					} else {
+						// ponytail: fail closed in headless sessions — project agent
+						// prompts and tools run without user oversight.
 						return {
-							content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
+							content: [{
+								type: "text",
+								text: "Cannot run project-local agents without UI confirmation. "
+									+ "Set confirmProjectAgents: false to allow in headless sessions, "
+									+ "or use agentScope: 'user' to skip project agents.",
+							}],
 							details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
 						};
 					}
@@ -358,14 +368,17 @@ export default function (pi: ExtensionAPI) {
 			}
 
 			// Shared auth/model setup for SDK sessions
-			const authStorage = AuthStorage.create();
-			const modelRegistry = ModelRegistry.create(authStorage);
+			// ponytail: reuse parent modelRegistry instead of a fresh copy — avoids
+			// internal API casts (storeModelHeaders) and preserves env/headers/OAuth.
+			const authStorage = AuthStorage.inMemory();
+			const modelRegistry = ctx.modelRegistry;
 
 			// Helper: inject parent's API key into child auth storage
-			async function injectApiKey(model: Model): Promise<void> {
+			async function injectApiKey(model: Model<any>): Promise<void> {
 				const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-				if (auth.ok && auth.apiKey) {
-					authStorage.setRuntimeApiKey(model.provider, auth.apiKey);
+				if (auth.ok) {
+					if (auth.apiKey) authStorage.setRuntimeApiKey(model.provider, auth.apiKey);
+					// ponytail: headers/env stay on the parent registry — no copy needed.
 				}
 			}
 
@@ -393,7 +406,7 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const resolved = resolveModel(agent.model, ctx.model);
+				const resolved = resolveModel(agent.model, ctx.model, ctx.modelRegistry);
 				if (!resolved.model) {
 					const tried = resolved.attempted.join(", ") || "none";
 					const parentInfo = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "none";
@@ -417,53 +430,40 @@ export default function (pi: ExtensionAPI) {
 				let tools = agent.tools ?? defaultTools;
 				tools = tools.filter((t) => t !== "subagent");
 
-				// Build timeout + parent signal into a combined AbortSignal
-				let combinedSignal = parentSignal;
-				let timeoutId: ReturnType<typeof setTimeout> | undefined;
-				let timeoutController: AbortController | undefined;
-				if (timeoutMs && timeoutMs > 0) {
-					timeoutController = new AbortController();
-					timeoutId = setTimeout(() => {
-						timeoutController!.abort();
-					}, timeoutMs);
-					// Combine with parent signal if present (Node 20+ AbortSignal.any)
-					if (parentSignal && typeof (AbortSignal as any).any === "function") {
-						combinedSignal = (AbortSignal as any).any([parentSignal, timeoutController.signal]);
-					} else if (parentSignal) {
-						combinedSignal = timeoutController.signal;
-						// Link parent to timeout: if parent aborts, also abort our timeout controller
-						if (parentSignal.aborted) timeoutController.abort();
-						else parentSignal.addEventListener("abort", () => timeoutController!.abort(), { once: true });
-					} else {
-						combinedSignal = timeoutController.signal;
+				const timeoutController = timeoutMs && timeoutMs > 0 ? new AbortController() : undefined;
+				const timeoutId = timeoutController ? setTimeout(() => timeoutController.abort(), timeoutMs) : undefined;
+				const signals = [parentSignal, timeoutController?.signal].filter((value): value is AbortSignal => Boolean(value));
+				const combinedSignal = signals.length > 1
+					? typeof (AbortSignal as any).any === "function"
+						? (AbortSignal as any).any(signals)
+						: signals[0]
+					: signals[0];
+
+				try {
+					const result = await runSubAgent({
+						cwd: cwd ?? ctx.cwd,
+						systemPrompt: params.instructions
+						? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, 16 * 1024)}`
+						: agent.systemPrompt,
+						task,
+						tools,
+						model: resolved.model,
+						authStorage,
+						modelRegistry,
+						signal: combinedSignal,
+						agentName,
+						thinkingLevel: agent.thinking,
+						onMessage: onProgress,
+					});
+					if (timeoutController?.signal.aborted && !parentSignal?.aborted) {
+						result.exitCode = 1;
+						result.stopReason = "timeout";
+						result.errorMessage ||= `Timeout after ${timeoutMs}ms`;
 					}
+					return result;
+				} finally {
+					if (timeoutId) clearTimeout(timeoutId);
 				}
-
-				const result = await runSubAgent({
-					cwd: cwd ?? ctx.cwd,
-					systemPrompt: agent.systemPrompt,
-					task,
-					tools,
-					model: resolved.model,
-					authStorage,
-					modelRegistry,
-					signal: combinedSignal,
-					agentName,
-					onMessage: onProgress,
-				});
-
-				// Clean up timeout
-				if (timeoutId) clearTimeout(timeoutId);
-
-				// Detect timeout: our timeout controller fired, not the parent
-				const timedOut = timeoutController?.signal.aborted && !parentSignal?.aborted;
-				if (timedOut) {
-					result.exitCode = 1;
-					result.stopReason = "timeout";
-					if (!result.errorMessage) result.errorMessage = `Timeout after ${timeoutMs}ms`;
-				}
-
-				return result;
 			}
 
 			// --- Chain mode ---
@@ -1051,7 +1051,7 @@ export default function (pi: ExtensionAPI) {
 		ctx: { ui: { custom: <T>(factory: any, opts?: any) => Promise<T> } },
 		items: PickerItem[],
 	): Promise<string | null> {
-		return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+		return ctx.ui.custom<string | null>((tui: any, theme: any, _kb: any, done: (value: string | null) => void) => {
 			const container = new Container();
 			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
 			container.addChild(new Text(theme.fg("accent", theme.bold("Subagents")), 1, 0));
@@ -1101,7 +1101,7 @@ export default function (pi: ExtensionAPI) {
 		const getThreads = () => threadStore.getAllThreads();
 
 		// Overlay mode: viewer appears above editor, Esc dismisses
-		await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+		await ctx.ui.custom<void>((tui: any, theme: any, _kb: any, done: () => void) => {
 			let unsubscribe: (() => void) | undefined;
 			let closed = false;
 

package/extensions/model.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared model resolution for pi-subagent.
+ *
+ * Provides a single canonical resolveModel() used by both the tool handler
+ * (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.
+ * 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";
+
+export interface ResolvedModel {
+	model: Model<any> | null;
+	attempted: string[];
+}
+
+/** Known provider prefixes for unqualified model names. */
+const KNOWN_PROVIDERS: [string, RegExp][] = [
+	["openai", /^gpt-/i],
+	["anthropic", /^claude-/i],
+	["google", /^gemini-/i],
+	["cohere", /^command-/i],
+	["deepseek", /^(deepseek-|ds-)/i],
+	["mistral", /^mistral-/i],
+	["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,
+	parentModel: Model<any> | undefined,
+	modelRegistry?: ModelRegistry,
+): ResolvedModel {
+	const attempted: string[] = [];
+	if (modelName) {
+		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);
+			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);
+			if (found) return { model: found, attempted };
+		}
+	} else if (parentModel) {
+		attempted.push(`${parentModel.provider}/${parentModel.id}`);
+		return { model: parentModel, attempted };
+	}
+	return { model: null, attempted };
+}

package/extensions/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/{render.ts → extensions/render.ts}

@@ -1,5 +1,5 @@
 /**
- * TUI rendering for pi-sugagents.
+ * TUI rendering for pi-subagent.
  *
  * Renders sub-agent results in collapsed and expanded views.
  * Collapsed: status icon, agent name, last few items, usage stats.
@@ -187,7 +187,7 @@ function renderDisplayItems(
 export function renderSingleResult(
 	result: SubAgentResult,
 	expanded: boolean,
-	theme: { fg: (c: string, t: string) => string; bold: (t: string) => string },
+	theme: { fg: (c: any, t: string) => string; bold: (t: string) => string },
 ): Container | Text {
 	const isError = isFailedResult(result);
 	const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");

package/{runner.ts → extensions/runner.ts}

@@ -1,5 +1,5 @@
 /**
- * SDK-based sub-agent runner for pi-sugagents.
+ * SDK-based sub-agent runner for pi-subagent.
  *
  * Creates an in-process AgentSession via the pi SDK instead of spawning a
  * separate `pi` process. This eliminates cold-start overhead and allows
@@ -61,11 +61,12 @@ export async function runSubAgent(options: {
 	systemPrompt: string;
 	task: string;
 	tools: string[];
-	model: Model;
+	model: Model<any>;
 	authStorage: AuthStorage;
 	modelRegistry: ModelRegistry;
 	signal?: AbortSignal;
 	agentName?: string;
+	thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 	onUpdate?: (text: string) => void;
 	onMessage?: (partialResult: SubAgentResult) => void;
 }): Promise<SubAgentResult> {
@@ -79,6 +80,7 @@ export async function runSubAgent(options: {
 		modelRegistry,
 		signal,
 		agentName = "subagent",
+		thinkingLevel = "off",
 		onUpdate,
 		onMessage,
 	} = options;
@@ -123,7 +125,7 @@ export async function runSubAgent(options: {
 		const { session } = await createAgentSession({
 			cwd,
 			model,
-			thinkingLevel: "off", // no reasoning token overhead
+			thinkingLevel,
 			authStorage,
 			modelRegistry,
 			resourceLoader,
@@ -221,8 +223,10 @@ export async function runSubAgent(options: {
 				}
 			});
 
-			await session.prompt(task);
-			await eventPromise;
+			await Promise.race([
+				session.prompt(task),
+				eventPromise,
+			]);
 
 			if (result.stopReason !== "aborted") {
 				result.exitCode = 0;

package/extensions/service.ts

@@ -0,0 +1,79 @@
+import { AuthStorage, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentConfig } from "./agents.ts";
+import { runSubAgent, type SubAgentResult } from "./runner.ts";
+import { resolveModel } from "./model.ts";
+
+export const SUBAGENT_REQUEST_EVENT = "pi-subagent:run";
+
+export interface SubagentRunRequest {
+	id: string;
+	agent: string;
+	task: string;
+	cwd?: string;
+	timeout?: number;
+	instructions?: string;
+	readOnly?: boolean;
+	signal?: AbortSignal;
+	accept?: () => boolean;
+	respond: (response: SubagentRunResponse) => void;
+}
+
+export type SubagentRunResponse =
+	| { id: string; ok: true; result: SubAgentResult }
+	| { id: string; ok: false; error: string };
+
+export async function runNamedAgent(options: {
+	agent: AgentConfig;
+	task: string;
+	cwd: string;
+	ctx: ExtensionContext;
+	timeout?: number;
+	instructions?: string;
+	signal?: AbortSignal;
+	onMessage?: (result: SubAgentResult) => void;
+}): Promise<SubAgentResult> {
+	const { model, attempted } = resolveModel(options.agent.model, 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();
+	const modelRegistry = options.ctx.modelRegistry;
+	const auth = await options.ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (auth.ok) {
+		if (auth.apiKey) authStorage.setRuntimeApiKey(model.provider, auth.apiKey);
+		// ponytail: env and headers stay on the parent modelRegistry — reuse it directly.
+	}
+
+	const timeoutController = options.timeout && options.timeout > 0 ? new AbortController() : undefined;
+	const timeoutId = timeoutController ? setTimeout(() => timeoutController.abort(), options.timeout) : undefined;
+	const signals = [options.signal, timeoutController?.signal].filter((value): value is AbortSignal => Boolean(value));
+	const signal = signals.length > 1
+		? typeof (AbortSignal as any).any === "function"
+			? (AbortSignal as any).any(signals)
+			: signals[0]
+		: signals[0];
+	const contract = options.instructions?.slice(0, 16 * 1024);
+
+	try {
+		const result = await runSubAgent({
+			cwd: options.cwd,
+			systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
+			task: options.task,
+			tools: (options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"]).filter((tool) => tool !== "subagent"),
+			model,
+			authStorage,
+			modelRegistry,
+			signal,
+			agentName: options.agent.name,
+			thinkingLevel: options.agent.thinking,
+			onMessage: options.onMessage,
+		});
+		if (timeoutController?.signal.aborted && !options.signal?.aborted) {
+			result.exitCode = 1;
+			result.stopReason = "timeout";
+			result.errorMessage ||= `Timeout after ${options.timeout}ms`;
+		}
+		return result;
+	} finally {
+		if (timeoutId) clearTimeout(timeoutId);
+	}
+}

package/package.json

@@ -1,49 +1,54 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.4.1",
-  "description": "Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context using the pi SDK in-process.",
+  "version": "0.5.0",
+  "description": "Minimal-overhead sub-agents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "homepage": "https://github.com/bacnh85/skills#readme",
+  "publishConfig": { "access": "public" },
+  "homepage": "https://github.com/bacnh85/pi-extensions#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bacnh85/skills.git",
-    "directory": "extensions/pi-subagent"
-  },
-  "bugs": {
-    "url": "https://github.com/bacnh85/skills/issues"
+    "url": "git+https://github.com/bacnh85/pi-extensions.git",
+    "directory": "pi-subagent"
   },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "subagent",
-    "sub-agent",
-    "delegation",
-    "parallel"
-  ],
+  "bugs": { "url": "https://github.com/bacnh85/pi-extensions/issues" },
+  "keywords": ["pi-package", "pi-extension", "subagent", "sub-agent", "delegation", "parallel"],
   "files": [
     "README.md",
-    "index.ts",
-    "agents.ts",
-    "runner.ts",
-    "render.ts",
-    "threads.ts",
-    "thread-viewer.ts",
+    "agent-format.md",
     "agents/",
-    "agent-format.md"
+    "extensions/index.ts",
+    "extensions/agents.ts",
+    "extensions/model.ts",
+    "extensions/runner.ts",
+    "extensions/service.ts",
+    "extensions/render.ts",
+    "extensions/threads.ts",
+    "extensions/thread-viewer.ts",
+    "extensions/package.json"
   ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
+  "pi": { "extensions": ["./extensions/index.ts"] },
+  "scripts": {
+    "test": "cd extensions && npx mocha",
+    "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.2",
+    "@earendil-works/pi-ai": "^0.80.2",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.80.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.19.43",
+    "mocha": "^10.8.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "typebox": "^1.3.1"
   }
 }