@ferris1225/pi-subagents 0.29.0 → 0.31.0

package/README.md

@@ -28,6 +28,10 @@ on its own — no prompt engineering, no babysitting.
   "go check" step. `subagent_wait` is a **non-blocking** in-turn lookup by default
   (pass `timeoutMs` to block); `subagent_status` inspects runs; `subagent_stop`
   cancels one and delivers its partial output.
+- **Results are not re-narrated** — a sub-agent's completion is shown to you
+  verbatim, and the main agent is told not to paraphrase it back. It replies with
+  only its own conclusion or next step, so the same findings are never paid for
+  twice in tokens.
 - **A quality gate that closes the loop** — when a reviewer returns `REVIEW_FAIL`,
   the extension dispatches a worker briefed with the concrete findings, then a
   re-review, up to `maxFixRounds` times — and only then wakes the main agent.
@@ -36,6 +40,10 @@ on its own — no prompt engineering, no babysitting.
   with backoff, then falls back once to the main window's model; terminal errors
   (quota/auth) short-circuit straight to the main agent; an idle watchdog kills
   runs that go silent; startup races are retried with backoff.
+- **Resumes, not restarts, on a model switch** — every run is session-backed, so
+  a model quota/auth failure resumes on another model with its earlier searches,
+  reads, and edits intact (no re-scanning). When every model is out, the run is
+  handed back with its session preserved for a one-call `subagent({ resume })`.
 - **Honest completions** — a run that ended with failed tool calls (e.g. a broken
   build) is reported as `completed with N failed tool call(s)` with the errors
   attached — a cheerful final text can never hide a failure.
@@ -195,6 +203,22 @@ errors, then once with the main window's model — per-run only, never persisted
 if everything fails, the task is handed back to the main window with
 instructions to execute it directly.
 
+### Resuming after a model quota/auth failure
+
+Every sub-agent run is **session-backed**: its pi session is persisted to a
+temp dir for the run. When a model fails at the provider level, the retry and
+the fallback **resume that session** instead of starting over — so a model
+switch inherits the sub-agent's earlier searches, reads, and edits and never
+re-scans. If every available model is exhausted (e.g. the account is out of
+quota), the run is handed back with its session preserved; once you have a
+working model again, resume it in-context:
+
+```ts
+subagent({ resume: 7 }); // continue run #7 from where its model stopped
+```
+
+The session is reclaimed once the resume succeeds (or when the session ends).
+
 ### Configuration migration
 
 The config file migrates itself on load — no manual steps after an upgrade:
@@ -241,25 +265,6 @@ model), `tools.ts` (wait/status/stop), `widget.ts` (widget + announcements),
 `monitor.ts` (run tracking), `setup.ts` (wizard), `prompt.ts` (delegation
 directive). No runtime dependencies beyond pi peer dependencies.
 
-## Acknowledgments
-
-- The official [pi subagent example](https://github.com/earendil-works/pi)
-  (`examples/extensions/subagent`) — the child-process dispatch and
-  event-stream handling build on it.
-- [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) — the
-  live widget and parallel fan-out follow its design.
-- [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) — the
-  result-delivery design is learned from it: prompt **steer** delivery, a
-  non-blocking `subagent_wait`, status inspection, and stop/interrupt
-  management. Its status-file and workflow-script orchestration are deliberately
-  out of scope: this extension stays a focused 3-agent delegation tool with a
-  configuration wizard.
-- The sub-agent pattern itself, popularized by
-  [Claude Code](https://github.com/anthropics/claude-code).
-
-The agent prompts and extension code are written independently for this
-project; the projects above served as design references.
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/completion.ts

@@ -151,3 +151,31 @@ export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass:
 		reviewVerdict(getResultOutput(result)) === "pass"
 	);
 }
+
+/** Minimal shape of an active run, for the "others still running" footer. Kept
+ * decoupled from the monitor's RunView so this stays a pure, easily tested
+ * formatter; the caller maps its live runs into this shape. */
+export interface ActiveRunFoot {
+	id: number;
+	agent: string;
+	/** Optional content label (task-derived) shown next to the agent name. */
+	label?: string;
+}
+
+/**
+ * Footer appended to a completion message when OTHER runs are still active, so
+ * the main agent does not declare the overall task done prematurely. A result
+ * arriving for one run does not mean sibling runs are finished; naming them
+ * gives the main agent concrete, in-context awareness to keep waiting.
+ *
+ * Returns "" when nothing is active (the common, single-run case stays quiet).
+ */
+export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed = 4): string {
+	if (runs.length === 0) return "";
+	const listed = runs.slice(0, maxListed);
+	const items = listed
+		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
+		.join(", ");
+	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
+	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;
+}

package/src/dispatch.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { rm } from "node:fs/promises";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
@@ -47,6 +48,8 @@ import {
 } from "./monitor.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import {
+	buildFallbackResumeReason,
+	buildResumePrompt,
 	getResultOutput,
 	isFailedResult,
 	isModelLevelFailure,
@@ -81,6 +84,12 @@ const SubagentParams = Type.Object({
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
+	resume: Type.Optional(
+		Type.Number({
+			description:
+				"Resume a handed-back run by its id: continue a sub-agent whose model hit a quota/auth limit, picking up its preserved context without re-scanning. Use the run id from a model-level handback message.",
+		}),
+	),
 });
 
 /** True when any dispatched task carries the vision flag. */
@@ -142,6 +151,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
 			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
+			"Resume: pass { resume: <runId> } to continue a run that was handed back after its model hit a quota/auth limit — it picks up the preserved context without re-scanning.",
 			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
 			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block).",
@@ -159,6 +169,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
 			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
 			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The sub-agent then runs on the configured vision-capable model, or the main session's current model when none is configured.",
+			"When a sub-agent result arrives it is already shown to the user — do NOT restate, paraphrase, or summarize it; reply with only your own conclusion or next action (often just one line), since duplicating the result wastes tokens for nothing.",
 		],
 		parameters: SubagentParams,
 
@@ -251,6 +262,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
 			const hasSingle = Boolean(params.agent) && params.task !== undefined;
+			// `resume` is its own exclusive mode (it re-dispatches a handed-back run
+			// from its preserved session), so it bypasses the single/parallel check.
+			const hasResume = typeof params.resume === "number";
 
 			const makeDetails =
 				(mode: "single" | "parallel", background = false) =>
@@ -258,7 +272,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 
 			const catalog = agents.map((a) => a.name).join(", ") || "none";
 
-			if (Number(hasTasks) + Number(hasSingle) !== 1) {
+			if (!hasResume && Number(hasTasks) + Number(hasSingle) !== 1) {
 				return {
 					content: [
 						{
@@ -436,7 +450,16 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						const last = chain[chain.length - 1];
 						let block = formatChainSummary(chain);
 						if (isFailedResult(last.result) && isModelLevelFailure(last.result)) {
-							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(last.result)}`;
+							if (last.result.sessionDir && last.result.sessionId) {
+								runtime.preservedSessions.set(parentRunId, {
+									sessionId: last.result.sessionId,
+									sessionDir: last.result.sessionDir,
+									agentName: last.result.agent,
+									task: last.result.task,
+									vision,
+								});
+							}
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(last.result, { runId: parentRunId })}`;
 						} else if (isFailedResult(last.result) || reviewVerdict(getResultOutput(last.result)) === "fail") {
 							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}`;
 						}
@@ -487,7 +510,13 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				));
 			};
 
-			const startBackground = (agentName: string, task: string, cwd?: string, vision = false): SingleResult => {
+			const startBackground = (
+				agentName: string,
+				task: string,
+				cwd?: string,
+				vision = false,
+				resumeSession?: { sessionId: string; sessionDir: string; preservedRunId: number },
+			): SingleResult => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 				// A vision-flagged task runs on the configured vision model (or the main
@@ -519,6 +548,17 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 									onLive,
 									makeDetails: makeDetails("single", true),
 									idleTimeoutMs: config.idleTimeoutSec * 1000,
+									// A resume reuses a preserved session (handed back after a
+									// model-level failure) so it continues in-context instead of
+									// re-scanning. The wrapper detects the existing session file and
+									// resumes it; the continuation prompt steers the model to pick up.
+									...(resumeSession
+										? {
+											sessionId: resumeSession.sessionId,
+											sessionDir: resumeSession.sessionDir,
+											stdinText: buildResumePrompt(task, buildFallbackResumeReason()),
+										}
+										: {}),
 								},
 								sessionRef,
 							);
@@ -568,15 +608,36 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						// the result even though the run row is already gone from the monitor.
 						runtime.registerRunResult(runId, result);
 						runtime.runControllers.delete(runId);
+						// A successful resume consumed the preserved session: reclaim its temp
+						// dir and drop the id so it cannot be re-resumed. A failed resume keeps
+						// it (still filed under the original preserved run id) for another try.
+						if (resumeSession && !failed) {
+							runtime.preservedSessions.delete(resumeSession.preservedRunId);
+							void rm(resumeSession.sessionDir, { recursive: true, force: true }).catch(() => undefined);
+						}
 						if (!runtime.sessionActive) return;
+						// A model-level failure that preserved a session (the run did real work
+						// before the model quota/auth broke) files it under this run id so a
+						// later `subagent({ resume: <runId> })` can continue in-context. Skipped
+						// for a resume run — its session is already filed under the original id.
+						if (modelLevel && !resumeSession && result.sessionDir && result.sessionId) {
+							runtime.preservedSessions.set(runId, {
+								sessionId: result.sessionId,
+								sessionDir: result.sessionDir,
+								agentName: agent.name,
+								task,
+								vision,
+							});
+						}
 						// Model-level failure: the configured model is unavailable or broke
-						// and the retry with the main-window model (when distinct) also
-						// failed. Instead of leaving a dead failure, hand the task to the
-						// main window — the main agent executes it itself with its own tools.
+						// and the resume on the main-window model (when distinct) also failed.
+						// Hand the task back; when a session was preserved, steer the main agent
+						// to resume it in-context instead of executing it fresh.
+						const handbackRunId = resumeSession ? resumeSession.preservedRunId : runId;
 						const completion: CompletionMessageItem = {
 							agent: result.agent,
 							block: modelLevel
-								? `${formatCompletionBlock(result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(result)}`
+								? `${formatCompletionBlock(result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(result, { runId: handbackRunId })}`
 								: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
 							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
 						};
@@ -629,6 +690,61 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				return pending;
 			};
 
+			// Resume mode (exclusive): continue a handed-back run in its preserved
+			// session on the agent's configured model, picking up the prior context
+			// instead of re-scanning. Triggered by a model-level handback that named
+			// the run id, after the user has a working model again.
+			if (typeof params.resume === "number") {
+				const preserved = runtime.preservedSessions.get(params.resume);
+				if (!preserved) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `No preservable session for run #${params.resume}. It completed normally, was not a model-level handback, or the session has ended.`,
+							},
+						],
+						details: makeDetails("single")([]),
+						isError: true,
+					};
+				}
+				const resumeAgent = agents.find((a) => a.name === preserved.agentName);
+				if (!resumeAgent) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Cannot resume run #${params.resume}: agent "${preserved.agentName}" is not enabled. Re-enable it (or run /subagents-setup) and resume again.`,
+							},
+						],
+						details: makeDetails("single")([]),
+						isError: true,
+					};
+				}
+				const pending = startBackground(preserved.agentName, preserved.task, undefined, preserved.vision, {
+					sessionId: preserved.sessionId,
+					sessionDir: preserved.sessionDir,
+					preservedRunId: params.resume,
+				});
+				if (pending.exitCode !== -1) {
+					return {
+						content: [{ type: "text", text: getResultOutput(pending) }],
+						details: makeDetails("single")([pending]),
+						isError: true,
+					};
+				}
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Resuming ${preserved.agentName} (run #${params.resume}) in the background on its configured model, picking up its preserved context. Its result will automatically resume the main agent when ready.`,
+						},
+					],
+					details: makeDetails("single", true)([pending]),
+					terminate: true,
+				};
+			}
+
 			// Sub-agents intentionally detach from the foreground turn. This makes the
 			// editor available immediately; completion messages later wake the main agent.
 			if (params.tasks && params.tasks.length > 0) {

package/src/format.ts

@@ -122,13 +122,20 @@ export function formatCompletionBlock(result: SingleResult, maxResultLines: numb
 
 /** Instruction appended to a model-level failure: the sub-agent's provider never
  * produced usable output (or the run stalled), so the task is handed back to the
- * main window instead of being left as a dead failure. */
-export function modelLevelTakeoverNote(result: SingleResult): string {
+ * main window instead of being left as a dead failure. When the run preserved a
+ * session with earlier work (and the run id is known), steer the main agent to
+ * 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 retry with the main-window model also failed" : "";
-	return `The sub-agent could not complete this task: its model was unavailable or failed (or the run stalled)${sameModel}${retry}. Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
+	const retry = result.modelFallbackFrom ? ", and the resume on the main-window 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 with { resume: ${opts!.runId} } to CONTINUE it in-context (it picks up where it stopped — no 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}`;
 }
 
 /** Resolve a run-id request to actual ids: an exact numeric match always wins

package/src/monitor.ts

@@ -39,6 +39,10 @@ export interface RunView {
 	id: number;
 	agent: string;
 	task: string;
+	/** Short content label derived from the task (paths/symbols), shown next to
+	 * the agent name so concurrent same-agent runs are told apart by what they
+	 * are doing, not just their run id. */
+	label?: string;
 	model?: string;
 	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
 	thinking?: string;
@@ -228,6 +232,28 @@ export function formatTaskSummary(task: string, maxWidth: number = TASK_SUMMARY_
 	return `${takeGraphemes(segments, headMax)}${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(segments, tailMax)}`;
 }
 
+/** Max display width of a run's content label. */
+export const RUN_LABEL_MAX = 32;
+
+/**
+ * Short content label for a run, derived from its task: the single most
+ * distinguishing fragment (path, quoted phrase, symbol) so concurrent same-agent
+ * runs are told apart by WHAT they do, not just their run id. A long path keeps
+ * its tail (the filename is the recognisable part); a task with no recognizable
+ * fragment falls back to a head slice of its prose. Grapheme-safe.
+ */
+export function runLabel(task: string): string {
+	const fragment = extractKeyFragments(task)[0];
+	const src = fragment ?? stripVTControlCharacters(task).replace(/\s+/g, " ").trim();
+	if (visibleWidth(src) <= RUN_LABEL_MAX) return src;
+	const chars = [...graphemeSegmenter.segment(src)].map((s) => s.segment);
+	// A path/symbol fragment keeps its tail (filename/symbol is recognisable);
+	// a prose fallback keeps its head.
+	return fragment
+		? `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(chars, RUN_LABEL_MAX - 1)}`
+		: `${takeGraphemes(chars, RUN_LABEL_MAX - 1)}${TASK_SUMMARY_ELLIPSIS}`;
+}
+
 function formatTokens(count: number): string {
 	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
 	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
@@ -401,6 +427,7 @@ export class MonitorStore {
 			id,
 			agent,
 			task,
+			label: runLabel(task),
 			model,
 			thinking,
 			status: "queued",

package/src/prompt.ts

@@ -66,6 +66,12 @@ 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.
 
+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.
+- Reply only with what you ADD: your own conclusion, the next action you are taking, or a one-line acknowledgement. When the result already answers the user, a single sentence is enough — then end your turn or proceed.
+- Read the result and act on it (verify, continue, commit). Keep your own output short.
+- A result arriving does NOT mean all work is finished: sub-agents run in the background and siblings may still be active (a delivery names any still-running runs). Do not report the overall task complete until no runs are active — call subagent_status to confirm before saying Done.
+
 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.`;

package/src/runtime.ts

@@ -9,10 +9,12 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { rmSync } from "node:fs";
 import { BackgroundTaskQueue } from "./background.ts";
 import {
 	completionGroupTriggersTurn,
 	createCompletionBatcher,
+	formatActiveRunsFooter,
 	formatCompletionMessage,
 	type CompletionBatcher,
 	type CompletionMessageItem,
@@ -37,10 +39,23 @@ export interface SubagentRuntime {
 	settledRuns: Map<number, SingleResult>;
 	settledListeners: Map<number, Set<(result: SingleResult) => void>>;
 	registerRunResult: (runId: number, result: SingleResult) => void;
+	/** Sessions preserved on disk after a model-level handback (the run did real
+	 * work but its model quota/auth failed), keyed by the original run id so a
+	 * later `subagent({ resume: <runId> })` can continue in-context. Cleaned up
+	 * on shutdown so a crashed/ended session never leaks temp session dirs. */
+	preservedSessions: Map<number, PreservedSession>;
 	/** Flip sessionActive off and release all session-scoped resources. */
 	shutdown: () => void;
 }
 
+export interface PreservedSession {
+	sessionId: string;
+	sessionDir: string;
+	agentName: string;
+	task: string;
+	vision: boolean;
+}
+
 export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRuntime {
 	// Init-time decisions need the config synchronously; the full (migrating)
 	// async load runs per tool call.
@@ -53,9 +68,17 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 		sessionActive: true,
 		sendCompletionGroup: (items) => {
 			if (!runtime.sessionActive || items.length === 0) return;
+			// A result arriving for one run does not mean sibling runs are done.
+			// Computing this at delivery (emit) time — not when the item was
+			// pushed — reflects the current monitor state, since finishing runs
+			// are removed from the monitor before their completion is pushed.
+			const active = monitor
+				.getRuns()
+				.filter((run) => run.status === "queued" || run.status === "running" || run.retained)
+				.map((run) => ({ id: run.id, agent: run.agent, label: run.label }));
 			const message = {
 				customType: "subagent-result",
-				content: formatCompletionMessage(items),
+				content: formatCompletionMessage(items) + formatActiveRunsFooter(active),
 				display: true,
 			};
 			if (completionGroupTriggersTurn(items)) {
@@ -76,6 +99,7 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 		runControllers: new Map<number, AbortController>(),
 		settledRuns: new Map<number, SingleResult>(),
 		settledListeners: new Map<number, Set<(result: SingleResult) => void>>(),
+		preservedSessions: new Map<number, PreservedSession>(),
 		registerRunResult: (runId, result) => {
 			runtime.settledRuns.set(runId, result);
 			const listeners = runtime.settledListeners.get(runId);
@@ -97,6 +121,17 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			runtime.settledRuns.clear();
 			runtime.settledListeners.clear();
 			runtime.runControllers.clear();
+			// Best-effort cleanup of preserved sub-agent session dirs so an
+			// ended/crashed session does not leak temp files; the OS reclaims
+			// tmpdir eventually, but this keeps things tidy between sessions.
+			for (const { sessionDir } of runtime.preservedSessions.values()) {
+				try {
+					rmSync(sessionDir, { recursive: true, force: true });
+				} catch {
+					/* best-effort */
+				}
+			}
+			runtime.preservedSessions.clear();
 			// Clear the monitor so stale runs from this session never leak into the
 			// next one (the module-level singleton survives across sessions).
 			monitor.clear();

package/src/spawn.ts

@@ -10,7 +10,8 @@
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdirSync, unlinkSync, rmdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, unlinkSync, rmdirSync, writeFileSync } from "node:fs";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
@@ -99,6 +100,16 @@ export interface SingleResult {
 	 * message must surface these so the main agent is never misled by a rosy final
 	 * text (e.g. a worker that ended with "keep waiting" while its build failed). */
 	failedTools?: Array<{ toolName: string; error: string }>;
+	/** The pi session id this run used (every run is session-backed so a
+	 * model-level failure can be resumed on another model without re-scanning). */
+	sessionId?: string;
+	/** Directory holding the run's pi session file. Preserved across the initial
+	 * attempt and any resume attempts; kept on disk only when a model-level
+	 * failure is handed back, so a later `resume` can pick up the context. */
+	sessionDir?: string;
+	/** True when the result was produced by resuming an earlier session (a
+	 * model-level fallback or an explicit resume) rather than a fresh start. */
+	resumed?: boolean;
 }
 
 export interface SubagentDetails {
@@ -348,6 +359,44 @@ export function getResultOutput(result: SingleResult): string {
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
+/**
+ * True when a pi session file for `sessionId` already exists in `sessionDir`.
+ * Every sub-agent run is session-backed; the FIRST attempt creates the session
+ * (`--session-id`) and every later attempt on the same session RESUMES it
+ * (`--session`), so a model-level retry or fallback picks up the prior context
+ * instead of re-scanning. The session file is named `<timestamp>Z_<id>.jsonl`
+ * (pi's convention), so a suffix match is exact and cheap.
+ */
+export function sessionExists(sessionDir: string, sessionId: string): boolean {
+	try {
+		return readdirSync(sessionDir).some((file) => file.endsWith(`_${sessionId}.jsonl`));
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Build the continuation prompt sent to a RESUMED sub-agent session. The model
+ * sees the full prior history (loaded by `--session`) plus this new user turn,
+ * so it continues from where it stopped. Steering it not to redo finished work
+ * is what saves the re-scan the user wants to avoid.
+ *
+ * `reason` is a short clause describing why the session is resuming
+ * ("a transient provider error" / "your previous model hit a quota or auth
+ * limit, so a different model is now continuing").
+ */
+export function buildResumePrompt(task: string, reason: string): string {
+	return `You are resuming an earlier sub-agent session after ${reason}. Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Original task: ${task}. Pick up exactly where you left off and finish it. Do NOT redo searches, reads, or edits you already completed unless a step clearly failed. Continue now.`;
+}
+
+/** Reason clause for resuming on a DIFFERENT model after the configured model
+ * failed at the provider level (quota/auth/overloaded/...). */
+export function buildFallbackResumeReason(fromModel?: string): string {
+	return fromModel
+		? `your previous model (${fromModel}) hit a quota, billing, or auth limit, so a different model is now continuing`
+		: "your previous model became unavailable, so a different model is now continuing";
+}
+
 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, "_");
@@ -424,6 +473,21 @@ export interface RunSingleOptions {
 	 * SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS; pass [] to disable (e.g. when an isolated
 	 * test wants to assert only the fallback path runs once). */
 	runLevelRetryDelaysMs?: readonly number[];
+	/** Directory holding this run's pi session. When set (with sessionId), the
+	 * child is session-backed: it creates the session on the first attempt and
+	 * RESUMES it on any later attempt (model-level retry/fallback), so a model
+	 * switch inherits the prior context. When unset, the child runs ephemerally
+	 * (--no-session) and cannot be resumed. The caller owns the directory's
+	 * lifecycle; runSingleAgent neither creates nor removes it. */
+	sessionDir?: string;
+	/** Pi session id paired with sessionDir. The first attempt creates it
+	 * (--session-id); later attempts resume (--session) once the session file
+	 * exists. */
+	sessionId?: string;
+	/** Text sent to the child via stdin. Defaults to `Task: ${task}`. A resumed
+	 * attempt passes a continuation prompt (see buildResumePrompt) so the model
+	 * picks up the prior session instead of starting the task over. */
+	stdinText?: string;
 	signal?: AbortSignal;
 	onLive?: (e: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
@@ -458,7 +522,20 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 
 	// Defense in depth: even if another extension ignores the depth marker, a
 	// child process can never expose a tool named `subagent` back to its model.
-	const args: string[] = ["--mode", "json", "-p", "--no-session", "--exclude-tools", "subagent"];
+	const args: string[] = ["--mode", "json", "-p", "--exclude-tools", "subagent"];
+	// Session-backed: every run persists its pi session so a model-level retry or
+	// fallback can RESUME it (--session) instead of re-scanning from scratch. The
+	// first attempt creates the session (--session-id); once the session file
+	// exists, later attempts resume it. No sessionDir → ephemeral (--no-session).
+	if (options.sessionDir && options.sessionId) {
+		args.push("--session-dir", options.sessionDir);
+		args.push(
+			sessionExists(options.sessionDir, options.sessionId) ? "--session" : "--session-id",
+			options.sessionId,
+		);
+	} else {
+		args.push("--no-session");
+	}
 	if (agent.model) args.push("--model", agent.model);
 	// The configured level is clamped adaptively per model by pi.
 	args.push("--thinking", thinkingLevel);
@@ -467,6 +544,7 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
 
+	const hasSession = Boolean(options.sessionDir && options.sessionId);
 	const currentResult: SingleResult = {
 		agent: agentName,
 		agentSource: agent.source,
@@ -477,6 +555,9 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		usage: emptyUsage(),
 		model: agent.model,
 		thinking: thinkingLevel,
+		sessionId: options.sessionId,
+		sessionDir: options.sessionDir,
+		resumed: hasSession && sessionExists(options.sessionDir as string, options.sessionId as string),
 	};
 
 	try {
@@ -618,11 +699,11 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 					currentResult.messages.push(event.message as Message);
 				}
 			};
-			// Send the task through the child stdin pipe instead of the process
-			// command line. This avoids OS argument-length limits and does not
-			// require another temporary file for conversation data.
+			// Send the task (or a continuation prompt for a resumed session) through
+			// the child stdin pipe instead of the command line. This avoids OS
+			// argument-length limits and requires no extra temp file for the data.
 			proc.stdin?.on("error", () => undefined);
-			proc.stdin?.end(`Task: ${task}`);
+			proc.stdin?.end(options.stdinText ?? `Task: ${task}`);
 
 			// Decode stdout through a StringDecoder so multi-byte UTF-8 characters
 			// (CJK, emoji) split across chunk boundaries never produce U+FFFD
@@ -725,7 +806,8 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 }
 
 /**
- * Run one agent with three layers of resilience against transient dispatch failures:
+ * Run one agent with three layers of resilience, all session-backed so a model
+ * switch RESUMES the prior context instead of re-scanning from scratch:
  *
  * 1. Startup retry (inner loop): a concurrent pi startup race can make the child
  *    exit before any model/tool activity. Relaunch with backoff so the startup
@@ -733,23 +815,19 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
  *    model — and only a clean, silent, zero-activity exit qualifies (see
  *    isRetryableStartupFailure), so retrying can never duplicate real work.
  * 2. Run-level retry on the SAME configured model (middle): when the provider
- *    rejects the model before producing output with a TRANSIENT error
- *    (503/429/timeout/network/stream/...) — i.e. NOT a terminal one (quota
- *    exhausted, billing, an invalid API key, auth rejected — see
- *    isTerminalModelError) — relaunch the whole run up to
- *    SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS.length more times with backoff, so a
- *    one-off provider hiccup recovers without demoting the configured agent
- *    model. Each relaunch gets its own inner startup-retry loop. This sits
- *    outside pi-ai's per-request provider retry, which by then has already
- *    tried (default 3 attempts) and given up.
- * 3. Model fallback (outer): when the same model is still failing after all its
- *    run-level retries, retry once with the main window's current model. The
- *    fallback gets its own startup-retry loop, since a startup race can hit any
- *    relaunch regardless of model.
+ *    rejects the model with a TRANSIENT error (503/429/timeout/network/...) —
+ *    NOT a terminal one (quota/billing/invalid key/auth — see isTerminalModelError)
+ *    — RESUME the session on the same model up to
+ *    SUBAGENT_RUN_LEVEL_RETRY_DELAYS_MS.length more times with backoff. Resuming
+ *    preserves any work done before the hiccup.
+ * 3. Model fallback (outer): when the same model still fails, RESUME the session
+ *    once on the main window's current model — the fallback inherits the prior
+ *    context, so the user never pays to re-scan after a model switch.
  *
- * Terminal model errors short-circuit straight to the caller (modelRetries is
- * set): the account is the bottleneck, so neither same-model retry nor a
- * same-account fallback can help, and the run is left for the main agent to fix.
+ * Terminal model errors short-circuit to the caller: the account is the
+ * bottleneck, so neither same-model retry nor a same-account fallback can help.
+ * The session is preserved on disk (the result carries sessionId/sessionDir) so
+ * a later manual resume on a working model can continue without re-scanning.
  *
  * The fallback is per-run only and never persisted: a transient provider hiccup
  * must not silently downgrade the configured agent model.
@@ -802,55 +880,98 @@ export async function runSingleAgentWithModelFallback(
 		}
 	};
 
-	let result = await runWithStartupRetry(options);
+	// One pi session backs the whole logical run, shared by the initial attempt
+	// and every resume (model-level retry / fallback), so a model switch inherits
+	// the prior context instead of re-scanning. Created here unless the caller
+	// passed one in (an explicit resume of a handed-back session).
+	const sessionId = options.sessionId ?? randomUUID();
+	const sessionDir = options.sessionDir ?? (await mkdtemp(join(tmpdir(), "pi-subagent-session-")));
+	const baseOptions: RunSingleOptions = { ...options, sessionDir, sessionId };
 
-	// After a model-level failure, classify before reacting. A TERMINAL error
-	// (quota/billing/invalid key/auth) is account-scoped: neither same-model
-	// retry nor a same-account fallback can help, so hand the run straight back
-	// to the main agent instead of burning its time on a doomed retry.
-	if (agent && launchedRef && isModelLevelFailure(result) && isTerminalModelError(result)) return result;
-
-	// A TRANSIENT provider failure (503/429/timeout/network/stream/...) is usually
-	// a one-off hiccup. Relaunch the SAME configured model up to runDelays.length
-	// more times with backoff before degrading to a fallback model — the run's own
-	// provider retry already tried and failed, so each relaunch here is an
-	// independent, fresh attempt that can recover without losing the configured
-	// model's capability to review.
 	let modelRetries = 0;
-	if (agent && launchedRef && isModelLevelFailure(result) && runDelays.length > 0) {
-		for (let attempt = 0; ; attempt++) {
-			const delay = runDelays[attempt];
-			if (delay === undefined) break;
-			try {
-				options.onLive?.({ kind: "status", status: "running" });
-			} catch { /* never throw from event handling */ }
-			const shouldRetry = await waitForStartupRetry(delay, options.signal);
-			if (!shouldRetry) return { ...result, modelRetries };
-			const retried = await runWithStartupRetry(options);
-			modelRetries++;
-			if (!isModelLevelFailure(retried) || isTerminalModelError(retried)) {
-				// Each relaunch redoes the work; failedTools reflect ONLY the final
-				// attempt (no stale build errors from earlier transient failures),
-				// so the completion message's claim stays accurate.
-				return { ...retried, modelRetries };
+	let result: SingleResult | undefined;
+	try {
+		result = await runWithStartupRetry(baseOptions);
+
+		// A TERMINAL model error (quota/billing/invalid key/auth) is account-scoped:
+		// neither a same-model retry nor a same-account fallback can help. Skip the
+		// automatic retry/fallback and hand the run back — the session is preserved
+		// (see finally) so a later manual resume on a working model can continue
+		// without re-scanning.
+		const terminal = isModelLevelFailure(result) && isTerminalModelError(result);
+
+		// A TRANSIENT provider failure (503/429/timeout/network/...) usually
+		// recovers on a relaunch. RESUME the same session on the same configured
+		// model up to runDelays.length more times with backoff — resuming (not
+		// restarting) preserves any work done before the hiccup. This sits outside
+		// pi-ai's per-request provider retry, which by then already tried and gave up.
+		if (!terminal && agent && launchedRef && isModelLevelFailure(result) && runDelays.length > 0) {
+			const retryOpts: RunSingleOptions = {
+				...baseOptions,
+				stdinText: buildResumePrompt(options.task, "a transient provider error"),
+			};
+			for (let attempt = 0; ; attempt++) {
+				const delay = runDelays[attempt];
+				if (delay === undefined) break;
+				try {
+					options.onLive?.({ kind: "status", status: "running" });
+				} catch { /* never throw from event handling */ }
+				const shouldRetry = await waitForStartupRetry(delay, options.signal);
+				if (!shouldRetry) break;
+				const retried = await runWithStartupRetry(retryOpts);
+				modelRetries++;
+				// failedTools reflect ONLY the final attempt (each runSingleAgent call
+				// accumulates its own), so the completion message stays accurate.
+				result = retried;
+				if (!isModelLevelFailure(retried) || isTerminalModelError(retried)) break;
 			}
-			result = retried;
 		}
-	}
 
-	// Same-model retries exhausted (or none configured) and still failing: fall
-	// back to the main window's current model exactly once. Skipped when there is
-	// no fallback ref or it equals the configured model — a same-ref rerun would
-	// just repeat the already-exhausted failure for nothing.
-	if (agent && launchedRef && fallbackModelRef && launchedRef !== fallbackModelRef && isModelLevelFailure(result)) {
-		const retried = await runWithStartupRetry({ ...options, agent: { ...agent, model: fallbackModelRef } });
-		// The fallback replaces the result wholesale: `retried.failedTools` reflect
-		// ONLY the fallback (final) attempt. The original attempt's failedTools are
-		// intentionally not merged — a fallback relaunch redoes the work, so attaching
-		// the first attempt's stale build errors to a clean final attempt would
-		// misattribute failures the worker already fixed. This makes the README's
-		// "failed tool calls from the run's final attempt" claim accurate.
-		return { ...retried, modelFallbackFrom: launchedRef, modelRetries };
+		// Transient retries exhausted (or none) and still a model-level failure:
+		// RESUME the session on the main window's current model exactly once. The
+		// fallback inherits the prior context (no re-scan). Skipped when there is no
+		// fallback ref, it equals the configured model, or the failure is terminal
+		// (a same-account fallback would fail identically — leave it for manual resume).
+		if (
+			!terminal &&
+			agent &&
+			launchedRef &&
+			fallbackModelRef &&
+			launchedRef !== fallbackModelRef &&
+			isModelLevelFailure(result)
+		) {
+			const retried = await runWithStartupRetry({
+				...baseOptions,
+				stdinText: buildResumePrompt(options.task, buildFallbackResumeReason(launchedRef)),
+				agent: { ...agent, model: fallbackModelRef },
+			});
+			// The fallback replaces the result wholesale: failedTools reflect ONLY the
+			// fallback (final) attempt — stale build errors from the first model are
+			// not merged, so a clean final attempt is never misattributed a failure.
+			result = { ...retried, modelFallbackFrom: launchedRef };
+		}
+
+		// A terminal failure takes the bare result (no retries or fallback ran, so
+		// modelRetries stays undefined — matching the contract callers assert).
+		return terminal ? result : { ...result, modelRetries };
+	} finally {
+		// Keep the session on disk only for a model-level failure that did real work
+		// and is being handed back, so a later `resume` can continue it. A provider
+		// rejection before any work (no messages/tools/output) has nothing to resume,
+		// so it is cleaned up along with every success and task-level failure. Never
+		// remove a caller-provided sessionDir (an explicit resume owns its dir).
+		if (result) {
+			result.sessionId ??= sessionId;
+			result.sessionDir ??= sessionDir;
+		}
+		const hasWork =
+			!!result &&
+			(result.messages.length > 1 ||
+				(result.failedTools?.length ?? 0) > 0 ||
+				Boolean(getFinalOutput(result.messages)));
+		const keep = !!result && isModelLevelFailure(result) && hasWork;
+		if (!keep && !options.sessionDir) {
+			await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);
+		}
 	}
-	return { ...result, modelRetries };
 }

package/src/tools.ts

@@ -13,6 +13,7 @@ import {
 	formatElapsed,
 	formatUsageCompact,
 	monitor,
+	runLabel,
 	statusLabel,
 } from "./monitor.ts";
 import type { SubagentRuntime } from "./runtime.ts";
@@ -262,6 +263,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 			const activeLines = activeRuns.map((run) => {
 				const parts = [
 					`#${run.id} ${run.agent}`,
+					run.label,
 					run.model ?? "?",
 					formatUsageCompact(run.usage),
 					formatElapsed(run, now),
@@ -271,7 +273,8 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 			const completed = [...runtime.settledRuns.entries()].slice(-5);
 			const completedLines = completed.map(([id, result]) => {
 				const usage = formatUsage(result.usage);
-				return `- #${id} ${result.agent} · ${isFailedResult(result) ? "failed" : "completed"}${usage ? ` · ${usage}` : ""}`;
+				const label = runLabel(result.task);
+				return `- #${id} ${result.agent}${label ? ` · ${label}` : ""} · ${isFailedResult(result) ? "failed" : "completed"}${usage ? ` · ${usage}` : ""}`;
 			});
 
 			const sections: string[] = [];

package/src/widget.ts

@@ -126,7 +126,11 @@ export function registerWidget(pi: ExtensionAPI, runtime: SubagentRuntime): void
 							// uses the accent color, everything else is quiet.
 							if (!isChain && lines.length > 0) lines.push("");
 							const nodeBranch = isChain ? (chainContinues ? "├─ " : "└─ ") : "";
-							const left = `${dim(nodeBranch)}${icon} ${dim(`#${r.id}`)} ${isChain ? name : theme.fg("accent", theme.bold(name))}`;
+							// Content label (task-derived) trails the agent name so concurrent
+							// same-agent runs read as what they do, not just their run id. Chain
+							// nodes already carry a distinguishing relationLabel.
+							const labelPart = !isChain && r.label ? ` ${dim(`· ${r.label}`)}` : "";
+							const left = `${dim(nodeBranch)}${icon} ${dim(`#${r.id}`)} ${isChain ? name : theme.fg("accent", theme.bold(name))}${labelPart}`;
 
 							// Right side: full model ref (provider/model), token usage (in/out +
 							// cache read/write), tool count, elapsed, and the soft activity-state