@ferris1225/pi-subagents 1.0.1 → 2.0.1

package/src/format.ts

@@ -73,33 +73,40 @@ export function formatUsage(usage: UsageStats): string {
 	return parts.join(" ");
 }
 
-export function formatCompletionBlock(result: SingleResult, maxResultLines: number, cwd?: string): string {
+export interface CompletionFormatOptions {
+	/** Include individual failed-tool errors. Reserved for explicit status lookup. */
+	failedToolDetails?: boolean;
+}
+
+export function formatCompletionBlock(
+	result: SingleResult,
+	maxResultLines: number,
+	cwd?: string,
+	options: CompletionFormatOptions = {},
+): string {
 	const failed = isFailedResult(result);
 	const failedTools = result.failedTools ?? [];
 	const status = failed
 		? "failed"
-		: failedTools.length > 0
+		: options.failedToolDetails && failedTools.length > 0
 			? `completed with ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}`
 			: "completed";
 	const usage = formatUsage(result.usage);
 	const output = getResultOutput(result);
 	const { text, truncated } = truncateResultOutput(output, maxResultLines);
 	const fallbackNote = result.modelFallbackFrom
-		? ` (model pool fallback: primary ${result.modelFallbackFrom} → final ${result.model ?? "dynamic default"})`
+		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
 		: "";
 	const startupRetryNote = result.startupRetries
 		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
 		: "";
-	const modelRetryNote = result.modelRetries
-		? ` (recovered after ${result.modelRetries} same-model retr${result.modelRetries === 1 ? "y" : "ies"} on a transient provider error)`
-		: "";
 	const relations = [
 		result.forkedFromRunId !== undefined ? `forked from #${result.forkedFromRunId}` : undefined,
 		(result.forkChildRunIds?.length ?? 0) > 0 ? `fork children ${result.forkChildRunIds!.map((id) => `#${id}`).join(", ")}` : undefined,
 	].filter((value): value is string => Boolean(value));
 	const relationNote = relations.length > 0 ? ` · ${relations.join(" · ")}` : "";
 	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${modelRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
 	if (result.isolation === "worktree") {
 		const isolation =
 			result.integrationStatus === "integrated"
@@ -120,23 +127,22 @@ export function formatCompletionBlock(result: SingleResult, maxResultLines: numb
 		lines.push(`Relation: ${relations.join(" · ")}`, "");
 	}
 	lines.push(text);
-	// A run can exit cleanly while its last tools failed (e.g. a build that broke):
-	// the final text alone may claim more than the tools achieved, so surface the
-	// failures explicitly and tell the main agent to verify before relying on it.
-	if (!failed && failedTools.length > 0) {
-		const shown = failedTools.slice(0, 3);
-		const more = failedTools.length - shown.length;
+	// Explicit status always exposes every retained diagnostic, including when
+	// the overall run failed or was aborted. Automatic delivery adds only a
+	// compact pointer for otherwise-clean runs.
+	if (options.failedToolDetails && failedTools.length > 0) {
 		lines.push(
 			"",
-			`⚠ ${failedTools.length} tool call${failedTools.length === 1 ? "" : "s"} failed during this run — the final text above may not reflect a working state:`,
-			...shown.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
+			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
+			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
 		);
-		if (more > 0) lines.push(`- … and ${more} more`);
-		lines.push("Verify the actual artifacts before relying on this report.");
+	} else if (!failed && failedTools.length > 0) {
+		const lookup = result.runId !== undefined ? ` · details: subagent_status #${result.runId}` : "";
+		lines.push("", `⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}${lookup}`);
 	}
 	if (truncated) {
 		// The full text lives on disk so the main agent can read it on demand.
-		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent, cwd)})`);
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent, result.projectCwd ?? cwd)})`);
 	}
 	return lines.join("\n");
 }
@@ -148,15 +154,12 @@ export function formatCompletionBlock(result: SingleResult, maxResultLines: numb
  * RESUME it in-context once a model is available, instead of re-dispatching
  * fresh (which would re-scan everything). */
 export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
-	const sameModel = result.modelRetries
-		? `, after ${result.modelRetries} same-model retr${result.modelRetries === 1 ? "y" : "ies"} on transient errors`
-		: "";
-	const retry = result.modelFallbackFrom ? ", and the configured backup chain also failed" : "";
+	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
 	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
 	const recovery = sessionPreserved
 		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
 		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
-	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${sameModel}${retry}.${recovery}`;
+	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${retry}.${recovery}`;
 }
 
 /** Resolve a run-id request to actual ids: an exact numeric match always wins

package/src/index.ts

@@ -68,7 +68,7 @@ export default function (pi: ExtensionAPI): void {
 	registerLookupTools(pi, runtime);
 
 	pi.registerCommand("subagents-setup", {
-		description: "Configure pi-subagents: enabled agents, primary/backup model pools, and runtime settings",
+		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, vision, and runtime settings",
 		handler: async (_args, ctx) => {
 			await runSetup(ctx, configPath);
 		},

package/src/models.ts

@@ -1,22 +1,26 @@
 /*
- * Model-pool resolution and setup-picker helpers.
+ * Model routing, capability-aware thinking, and setup-picker helpers.
  *
- * Runtime pools deliberately do not filter configured references by current
- * availability: a stale primary/backup is attempted and normal provider/model
- * failure handling advances to the next candidate. Setup uses the same catalog
- * only for honest availability labels; it never rewrites persisted choices.
+ * Runtime has one explicit fallback only: a configured agent/vision model hands
+ * off directly to the current main-window model. Setup lists only currently
+ * available models and derives thinking choices from Pi's model metadata.
  */
 
-import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+	clampThinkingLevel,
+	getSupportedThinkingLevels,
+	type Api,
+	type Model,
+} from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_THINKING_LEVEL, type ThinkingLevel } from "./config.ts";
 
 export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
 	Partial<Pick<ExtensionContext, "scopedModels">>;
 
 export const CURRENT_MAIN_MODEL = "__current_main_model__";
 
-export type ModelPoolSlot = "primary" | "backup";
-export type ModelPickerSlot = ModelPoolSlot | "vision";
+export type ModelPickerSlot = "agent" | "vision";
 
 export interface ModelPickerItem {
 	value: string;
@@ -26,34 +30,26 @@ export interface ModelPickerItem {
 
 export type ModelListEntry = Pick<
 	Model<Api>,
-	"provider" | "id" | "name" | "input" | "reasoning"
+	"provider" | "id" | "name" | "input" | "reasoning" | "thinkingLevelMap"
 >;
 
-export interface ResolvedAgentModelPool {
-	/** Effective first candidate. Undefined means let pi use its normal default. */
+export interface ResolvedAgentModelRoute {
+	/** Effective first candidate. Undefined means let Pi use its normal default. */
 	primaryRef?: string;
-	/** Ordered candidates after the primary, already deduplicated. */
-	fallbackModelRefs: string[];
-	/** All known references in runtime order, useful for tests/inspection. */
+	/** Current main-window model when it differs from the selection. */
+	mainFallbackRef?: string;
+	/** Runtime order, useful for status/tests. */
 	candidateRefs: string[];
+	/** Configured ref skipped because Pi does not currently report it available. */
+	unavailableSelectedRef?: string;
 }
 
-export interface AgentModelPoolInput {
-	primaryRef?: string;
-	backupRef?: string;
+export interface AgentModelRouteInput {
+	selectedRef?: string;
 	mainRef?: string;
 	declaredDefaultRef?: string;
-}
-
-export interface AgentModelPoolMaps {
-	agentModels: Record<string, string>;
-	agentBackupModels: Record<string, string>;
-}
-
-export interface AgentModelPoolRow {
-	name: string;
-	primary: string;
-	backup: string;
+	/** When supplied, a configured selection outside this live set is skipped. */
+	availableRefs?: readonly string[];
 }
 
 function cleanModelRef(ref: string | undefined): string | undefined {
@@ -76,62 +72,84 @@ export function currentModelRef(ctx: Pick<ModelContext, "model">): string | unde
  */
 export function availableModelsInScope(ctx: ModelContext): readonly Model<Api>[] {
 	const models = ctx.modelRegistry.getAvailable();
-	// scopedModels was added after the declared Pi 0.80.6 minimum. Treat a
-	// missing field exactly like an empty scope and use the full live registry.
+	// scopedModels was added after the original Pi minimum. Treat a missing field
+	// exactly like an empty scope and use the full live registry.
 	const scopedModels = ctx.scopedModels ?? [];
 	if (scopedModels.length === 0) return models;
 	const scopedRefs = new Set(scopedModels.map((entry) => modelRef(entry.model)));
 	return models.filter((model) => scopedRefs.has(modelRef(model)));
 }
 
+export function findModelByRef(
+	models: readonly Model<Api>[],
+	ref: string | undefined,
+): Model<Api> | undefined {
+	const normalized = cleanModelRef(ref);
+	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
+}
+
 /**
- * Resolve one agent's ordered runtime pool:
+ * Resolve one agent's runtime route:
  *
- * configured primary -> configured backup -> current main-window model
+ * configured selection -> current main-window model
  *
- * Without a primary override, the current main model remains the primary; an
- * agent-declared default is used only when no main model exists. Equal refs are
- * removed without consulting availability, so stale refs stay in the chain and
- * fail normally at runtime instead of being silently repaired.
+ * Without an override, current main is primary; the agent-declared default is
+ * used only when no main model exists. A configured selection that Pi no longer
+ * reports as available is skipped immediately instead of spawning a doomed child.
  */
-export function resolveAgentModelPool(input: AgentModelPoolInput): ResolvedAgentModelPool {
+export function resolveAgentModelRoute(input: AgentModelRouteInput): ResolvedAgentModelRoute {
+	const selectedRef = cleanModelRef(input.selectedRef);
 	const mainRef = cleanModelRef(input.mainRef);
-	const primaryRef = cleanModelRef(input.primaryRef) ?? mainRef ?? cleanModelRef(input.declaredDefaultRef);
-	const ordered = [primaryRef, cleanModelRef(input.backupRef), mainRef];
-	const seen = new Set<string>();
-	const candidateRefs: string[] = [];
-	for (const ref of ordered) {
-		if (!ref || seen.has(ref)) continue;
-		seen.add(ref);
-		candidateRefs.push(ref);
-	}
-	const fallbackModelRefs = candidateRefs.filter((ref) => ref !== primaryRef);
-	return { primaryRef, fallbackModelRefs, candidateRefs };
+	const declaredDefaultRef = cleanModelRef(input.declaredDefaultRef);
+	const available = input.availableRefs
+		? new Set(input.availableRefs.map((ref) => ref.trim()).filter(Boolean))
+		: undefined;
+	const selectedAvailable = !selectedRef || !available || available.has(selectedRef);
+	const usableSelectedRef = selectedAvailable ? selectedRef : undefined;
+	const primaryRef = usableSelectedRef ?? mainRef ?? declaredDefaultRef;
+	const ordered = [primaryRef, usableSelectedRef && usableSelectedRef !== mainRef ? mainRef : undefined];
+	const candidateRefs = [...new Set(ordered.filter((ref): ref is string => Boolean(ref)))];
+	return {
+		primaryRef,
+		...(candidateRefs[1] ? { mainFallbackRef: candidateRefs[1] } : {}),
+		candidateRefs,
+		...(!selectedAvailable && selectedRef ? { unavailableSelectedRef: selectedRef } : {}),
+	};
+}
+
+/** The exact levels Pi exposes for this model, including `off` when supported. */
+export function supportedThinkingLevels(model: Model<Api> | undefined): ThinkingLevel[] {
+	return model ? (getSupportedThinkingLevels(model) as ThinkingLevel[]) : [];
+}
+
+/** Clamp an agent preference to the effective model's actual capability map. */
+export function resolveThinkingLevel(
+	model: Model<Api> | undefined,
+	preferred: ThinkingLevel = DEFAULT_THINKING_LEVEL,
+): ThinkingLevel {
+	return model ? (clampThinkingLevel(model, preferred) as ThinkingLevel) : preferred;
 }
 
 function modelCapabilities(model: ModelListEntry): string {
-	const capabilities = [model.input.includes("image") ? "vision" : "text-only"];
-	if (model.reasoning) capabilities.push("reasoning");
-	return capabilities.join(" + ");
+	const input = model.input.includes("image") ? "vision" : "text-only";
+	const thinking = getSupportedThinkingLevels(model as Model<Api>).join("/");
+	return `${input} · thinking: ${thinking}`;
 }
 
-/** Build the single searchable model list shared by primary/backup/vision picks.
- * Only refs Pi currently reports as available are shown, which means providers
- * without a configured API key/OAuth session never flood the setup picker. */
+/** Build one searchable list for agent or vision selection. Only models Pi
+ * currently reports as available are supplied by setup. */
 export function buildModelPickerItems(options: {
 	models: readonly ModelListEntry[];
-	availableRefs: readonly string[];
 	slot: ModelPickerSlot;
 	configuredRef?: string;
 	mainRef?: string;
 }): ModelPickerItem[] {
 	const configuredRef = cleanModelRef(options.configuredRef);
 	const mainRef = cleanModelRef(options.mainRef);
-	const available = new Set(options.availableRefs.map((ref) => ref.trim()));
 	const byRef = new Map<string, ModelListEntry>();
 	for (const model of options.models) {
 		const ref = modelRef(model);
-		if (available.has(ref) && !byRef.has(ref)) byRef.set(ref, model);
+		if (!byRef.has(ref)) byRef.set(ref, model);
 	}
 
 	const refs = [...byRef.keys()]
@@ -142,26 +160,18 @@ export function buildModelPickerItems(options: {
 			return leftRank - rightRank || left.localeCompare(right);
 		});
 
-	const dynamic = options.slot === "backup"
-		? {
-			value: CURRENT_MAIN_MODEL,
-			label: "Current main model (default)",
-			description: "Clear configured backup; use the main-window model dynamically",
-		}
-		: {
-			value: CURRENT_MAIN_MODEL,
-			label: "Current main model (dynamic)",
-			description: options.slot === "vision"
-				? "Clear vision override; use the main-window model for vision tasks"
-				: "Clear primary override; use the main-window model dynamically",
-		};
-
+	const dynamic: ModelPickerItem = {
+		value: CURRENT_MAIN_MODEL,
+		label: "Current main model (dynamic)",
+		description: options.slot === "vision"
+			? "Clear vision override; use the current main model for image tasks"
+			: "Clear agent override; use the current main model dynamically",
+	};
 	const items: ModelPickerItem[] = [dynamic];
 	for (const ref of refs) {
 		const model = byRef.get(ref)!;
-		const tags = ["available"];
-		if (ref === configuredRef) tags.push("configured");
-		if (ref === mainRef) tags.push("current main");
+		const tags = [ref === configuredRef ? "configured" : "", ref === mainRef ? "current main" : ""]
+			.filter(Boolean);
 		const name = model.name.trim() && model.name !== model.id ? model.name.trim() : undefined;
 		items.push({
 			value: ref,
@@ -172,31 +182,14 @@ export function buildModelPickerItems(options: {
 	return items;
 }
 
-/** Pure pool update: the dynamic/default choice removes the persisted override. */
-export function applyModelPoolChoice(
-	current: AgentModelPoolMaps,
+/** The dynamic choice removes the persisted per-agent override. */
+export function applyAgentModelChoice(
+	current: Record<string, string>,
 	agentName: string,
-	slot: ModelPoolSlot,
 	choice: string,
-): AgentModelPoolMaps {
-	const next: AgentModelPoolMaps = {
-		agentModels: { ...current.agentModels },
-		agentBackupModels: { ...current.agentBackupModels },
-	};
-	const target = slot === "primary" ? next.agentModels : next.agentBackupModels;
-	if (choice === CURRENT_MAIN_MODEL) delete target[agentName];
-	else target[agentName] = choice.trim();
+): Record<string, string> {
+	const next = { ...current };
+	if (choice === CURRENT_MAIN_MODEL) delete next[agentName];
+	else next[agentName] = choice.trim();
 	return next;
 }
-
-/** Pure rows used by the overview component and focused helper tests. */
-export function buildAgentModelPoolRows(
-	agentNames: readonly string[],
-	pools: AgentModelPoolMaps,
-): AgentModelPoolRow[] {
-	return agentNames.map((name) => ({
-		name,
-		primary: pools.agentModels[name] ?? "Main (dynamic)",
-		backup: pools.agentBackupModels[name] ?? "Main (default)",
-	}));
-}

package/src/monitor.ts

@@ -33,7 +33,7 @@ export interface RunView {
 	 * are doing, not just their run id. */
 	label?: string;
 	model?: string;
-	/** Primary model ref when the run advanced to another candidate in its pool. */
+	/** Selected model ref when the run handed off to current main. */
 	modelFallbackFrom?: string;
 	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
 	thinking?: string;
@@ -406,7 +406,7 @@ export class MonitorStore {
 		run.status = status;
 		if (status === "running" || status === "steering" || status === "interrupting") {
 			if (run.startedAt === undefined) run.startedAt = Date.now();
-			// A model-fallback retry or resumed generation restarts the clock; a
+			// A selected-to-main handoff or resumed generation restarts the clock; a
 			// stale endedAt would freeze the elapsed display at the first attempt.
 			if (run.endedAt !== undefined) run.endedAt = undefined;
 		} else if ((status === "parked" || status === "done" || status === "failed") && run.endedAt === undefined) {
@@ -422,7 +422,7 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	/** Record the final actual model and primary-to-backup transition. */
+	/** Record the final actual model and selected-to-main transition. */
 	setModel(id: number, model?: string, fallbackFrom?: string): void {
 		const run = this.find(id);
 		if (!run) return;
@@ -431,6 +431,14 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Record the capability-clamped thinking level for the active model. */
+	setThinking(id: number, thinking?: string): void {
+		const run = this.find(id);
+		if (!run || !thinking) return;
+		run.thinking = thinking;
+		this.notify();
+	}
+
 	/** Update the run's current one-line activity (what it is doing now). */
 	setActivity(id: number, text: string): void {
 		const run = this.find(id);

package/src/prompt.ts

@@ -16,8 +16,9 @@ import { formatCatalogEntry } from "./agents.ts";
 
 /** Compact role routing hints, emitted only for roles that are enabled. */
 const ROLE_ROUTING: Record<string, string> = {
-	explore: "explore — codebase reconnaissance: broad/open-ended search, multi-file lookups, mapping unfamiliar code, tracing symbols/dependencies (read-only, cheap fast model); NOT for one-line lookups.",
+	explore: "explore — codebase reconnaissance: broad/open-ended search, multi-file lookups, mapping unfamiliar code, tracing symbols/dependencies (read-only, competent fast model); NOT for one-line lookups.",
 	worker: "worker — implement/fix/refactor/test a self-contained task worth a separate context (full tools; plans internally).",
+	cleaner: "cleaner — evidence-first cleanup for explicit cleanup intent in any language (for example dead code, redundancy, simplification, or over-engineering) or a requested periodic cleanup pass; audit/find/inspect/report is read-only, while explicit remove/clean/simplify/refactor wording permits verified edits; never PR-count or pre-commit driven (reviewer remains the gate).",
 	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
 };
 
@@ -30,6 +31,8 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 		.filter((line): line is string => Boolean(line))
 		.map((line) => `- ${line}`)
 		.join("\n");
+	const hasExplore = agents.some((a) => a.name === "explore");
+	const hasCleaner = agents.some((a) => a.name === "cleaner");
 	const hasReviewer = agents.some((a) => a.name === "reviewer");
 	const hasMultiple = agents.length > 1;
 
@@ -54,18 +57,18 @@ ${catalog}
 
 ${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
 - Handle SIMPLE work INLINE with direct tools: a one-line lookup, single edit, or quick question is a grep/read/edit in the main context — never a sub-agent. Sub-agents cost startup time, tokens, and a context switch.
-- Use \`explore\` PROACTIVELY for codebase reconnaissance: mapping an unfamiliar area, multi-file lookups, tracing symbols across modules, or any "where is X / which files reference Y" question that would take several greps or reading multiple files. It runs on a fast cheap model and returns compressed findings, so delegating recon costs little.
-- Delegate only when isolation genuinely pays: a self-contained implementation/fix with its own validation (worker), or a fresh-context review gate (reviewer).
-- When in doubt, start with a direct tool call in the main context; escalate to \`explore\` as soon as the search turns broad or crosses multiple files.
+- Use \`explore\` PROACTIVELY for codebase reconnaissance: mapping an unfamiliar area, multi-file lookups, tracing symbols across modules, or any "where is X / which files reference Y" question that would take several greps or reading multiple files. It should run on a competent fast code model and returns compressed findings, saving main-context space.
+- Delegate only when isolation genuinely pays: a self-contained implementation/fix with its own validation (worker)${hasCleaner ? ", explicit evidence-first cleanup (cleaner)" : ""}, or a fresh-context review gate (reviewer).
+${hasCleaner ? "- Route explicit cleanup intent in any language to `cleaner` (for example dead code, redundancy, simplification, or over-engineering), including a requested periodic maintenance pass. Audit/find/inspect/report wording means read-only evidence; apply only for explicit remove/clean/simplify/refactor wording. Generic code review without cleanup intent goes to `reviewer`. Never dispatch cleaner by PR count or automatically as the pre-commit gate; `reviewer` separately reviews cleaner edits.\n" : ""}- When in doubt, start with a direct tool call in the main context; escalate to \`explore\` as soon as the search turns broad or crosses multiple files.
 - For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
-${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Parallel worker items default to detached Git worktree isolation; pass `isolation: \"shared\"` only when a worker intentionally needs the caller's live uncommitted tree. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Single dispatch stays in the shared working tree by default. Use \`isolation: "worktree"\` only for worker/write-capable agents in a Git repository; never request it for explore/reviewer, and never silently retry shared after setup fails.
+${hasMultiple ? `- Run INDEPENDENT tasks in parallel: one subagent call with a \`tasks\` array, and track them with your todo list. Parallel worker items default to detached Git worktree isolation; pass \`isolation: "shared"\` only when a worker intentionally needs the caller's live uncommitted tree.${hasCleaner ? " Cleaner is also write-capable and may use explicit worktree isolation." : ""} Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then ${hasCleaner ? "worker/cleaner" : "worker"}, then reviewer).\n` : ""}- Single dispatch stays in the shared working tree by default. Use \`isolation: "worktree"\` only for ${hasCleaner ? "worker, cleaner, or another" : "worker or another"} write-capable agent in a Git repository; never request it for explore/reviewer, and never silently retry shared after setup fails.
 - Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
 - Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool. Use \`subagent_control fork\` on a parked/settled retained thread when you need an independent continuation with preserved context and a new run id.
 - Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
-
+${hasExplore ? "- Treat `explore` findings as a retrieval index, never as sole proof for edits, deletion, security, compatibility, persistence, or dynamic reachability. Re-read load-bearing files before acting. An underpowered model can be false economy on complex dynamic, concurrent, migration, or security-sensitive code; use a stronger model or specialist there.\n" : ""}
 Vision tasks:
 - Judge whether a delegated task may require viewing images (frontend screenshots, mockups, design files, visual regression comparisons). If it might, pass \`vision: true\` in the subagent call and give the sub-agent the exact image paths — it reads them with its read tool.
-- \`vision: true\` runs the sub-agent on the vision-capable model configured in /subagents-setup; when none is configured it falls back to the main session's current model. Do not skip the flag because the agent's default model looks fast/cheap — a non-vision model cannot see the images.
+- \`vision: true\` runs the sub-agent on the vision-capable model configured in /subagents-setup; when none is configured it falls back to the main session's current model. Do not skip the flag because the agent's default model looks fast — a non-vision model cannot see the images.
 
 Result handoff (do not re-state):
 - A sub-agent's result arrives as a message that is already shown to the user. Do NOT restate, paraphrase, or re-summarize its findings in your reply — that just burns tokens duplicating what is already visible. The user can read the result above.
@@ -75,5 +78,7 @@ Result handoff (do not re-state):
 
 Review & verification:
 - Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
-${hasReviewer ? "- For non-trivial diffs, run one fresh read-only `reviewer` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.\n- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.\n" : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;
+${hasReviewer ? `- For non-trivial diffs${hasCleaner ? " (including cleaner edits)" : ""}, run one fresh read-only \`reviewer\` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.
+- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.
+` : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;
 }

package/src/rpc-run.ts

@@ -52,18 +52,23 @@ export interface RpcSingleResult {
 	thinking?: string;
 	stopReason?: string;
 	errorMessage?: string;
-	/** Primary model when this result came from a later candidate in its configured pool. */
+	/** Selected model when this result handed off to the current main model. */
 	modelFallbackFrom?: string;
 	dispatchFailed?: boolean;
 	/** An accepted generation failed because an RPC prompt was rejected before
-	 * model execution. This remains model-candidate retry/fallback eligible even
-	 * when an earlier, aborted objective left assistant text in the session. */
+	 * model execution. This remains main-model handoff eligible even when an
+	 * earlier, aborted objective left assistant text in the session. */
 	rpcPromptRejected?: boolean;
+	/** The child accepted a prompt; startup retries must never duplicate it. */
+	rpcPromptAccepted?: boolean;
+	/** Pi emitted agent/turn/model/tool activity for this attempt. */
+	rpcActivity?: boolean;
 	startupRetries?: number;
-	modelRetries?: number;
 	failedTools?: Array<{ toolName: string; error: string }>;
 	sessionId?: string;
 	sessionDir?: string;
+	/** Original task/project cwd used for result-artifact retention buckets. */
+	projectCwd?: string;
 	/** Internal disposition: dispatch suppresses completion delivery for parks. */
 	parked?: boolean;
 	/** Stable logical run id assigned by dispatch (also present on queued results). */
@@ -84,7 +89,7 @@ export interface RpcSingleResult {
 
 export type SubagentLiveEvent =
 	| { kind: "status"; status: "queued" | "running" | "steering" | "interrupting" | "parked" | "done" | "failed" }
-	| { kind: "model"; model?: string; fallbackFrom?: string }
+	| { kind: "model"; model?: string; thinking?: ThinkingLevel; fallbackFrom?: string }
 	| { kind: "usage"; usage: UsageStats; model?: string }
 	| { kind: "tool_start"; toolCallId?: string; toolName: string; args: unknown }
 	| { kind: "tool_end"; toolCallId?: string; toolName: string; isError: boolean }
@@ -110,7 +115,7 @@ interface AttemptControl {
 }
 
 /**
- * Stable control surface for a logical run generation. Retry/fallback attempts
+ * Stable control surface for a logical run generation. Startup/main-handoff attempts
  * attach and detach beneath it, so callers never retain a stale child handle.
  * Control calls are serialized to prevent overlapping abort/settle/prompt flows.
  */
@@ -338,6 +343,46 @@ export function extractToolErrorText(content: unknown): string {
 		.join("\n");
 }
 
+interface ChildRetryPolicyExtension {
+	dir: string;
+	filePath: string;
+}
+
+/** Build a child-only Pi extension that replaces the selected provider's
+ * stream adapter with its registered API implementation while forcing
+ * maxRetries=0. It uses Pi's public extension and pi-ai compatibility APIs, so
+ * it works in Node and standalone/Bun builds without touching user settings. */
+export async function writeChildRetryPolicyExtension(
+	modelRef?: string,
+): Promise<ChildRetryPolicyExtension> {
+	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-policy-"));
+	const filePath = join(dir, "no-provider-retries.mjs");
+	const slash = modelRef?.indexOf("/") ?? -1;
+	const selectedProvider = slash > 0 ? modelRef!.slice(0, slash) : undefined;
+	const source = `import { getApiProvider } from "@earendil-works/pi-ai/compat";\n`
+		+ `const selectedProvider = ${JSON.stringify(selectedProvider)};\n`
+		+ `export default function noProviderRetries(pi) {\n`
+		+ `  pi.on("before_provider_request", (_event, ctx) => {\n`
+		+ `    const providerId = ctx.model?.provider ?? selectedProvider;\n`
+		+ `    if (!providerId) return;\n`
+		+ `    pi.registerProvider(providerId, {\n`
+		+ `      streamSimple(model, context, options) {\n`
+		+ `        const api = getApiProvider(model.api);\n`
+		+ `        if (!api) throw new Error(\`No API stream implementation is registered for \${model.api}.\`);\n`
+		+ `        return api.streamSimple(model, context, { ...options, maxRetries: 0 });\n`
+		+ `      },\n`
+		+ `    });\n`
+		+ `  });\n`
+		+ `}\n`;
+	try {
+		await writeFile(filePath, source, "utf8");
+		return { dir, filePath };
+	} catch (error) {
+		await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
 async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
 	const dir = await mkdtemp(join(tmpdir(), "pi-subagents-"));
 	const safeName = agentName.replace(/[^\w.-]+/g, "_");
@@ -422,6 +467,15 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 		args.push("--append-system-prompt", tmpPromptPath);
 	}
 
+	let retryPolicy: ChildRetryPolicyExtension;
+	try {
+		retryPolicy = await writeChildRetryPolicyExtension(agent.model);
+		args.push("--extension", retryPolicy.filePath);
+	} catch (error) {
+		if (tmpPromptDir) await rm(tmpPromptDir, { recursive: true, force: true }).catch(() => undefined);
+		throw error;
+	}
+
 	const result: RpcSingleResult = {
 		agent: agentName,
 		task,
@@ -512,6 +566,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	const resolveInitialPrompt = (accepted: boolean, error?: Error): void => {
 		if (initialPromptResolved) return;
 		initialPromptResolved = true;
+		if (accepted) result.rpcPromptAccepted = true;
 		initialPrompt.resolve({ accepted, error });
 	};
 
@@ -738,6 +793,33 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 		}
 		if (finished) return;
 
+		if (
+			[
+				"agent_start",
+				"agent_end",
+				"turn_start",
+				"turn_end",
+				"message_start",
+				"message_update",
+				"message_end",
+				"tool_execution_start",
+				"tool_execution_update",
+				"tool_execution_end",
+				"auto_retry_start",
+				"auto_retry_end",
+				"agent_settled",
+			].includes(event.type)
+		) {
+			result.rpcActivity = true;
+		}
+
+		// The child provider adapter disables request-level retries. Cancel Pi's
+		// separate outer turn retry the instant it is scheduled, before another
+		// same-model provider call can begin.
+		if (event.type === "auto_retry_start") {
+			void send({ type: "abort_retry" }).catch(() => undefined);
+		}
+
 		// Child RPC mode exposes extension dialogs. Sub-agents are non-interactive:
 		// cancel blocking dialogs so an unrelated child extension cannot deadlock.
 		if (
@@ -973,5 +1055,6 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				/* ignore */
 			}
 		}
+		await rm(retryPolicy.dir, { recursive: true, force: true }).catch(() => undefined);
 	}
 }