one-code-extension 0.4.1 → 0.5.0

package/extensions/subagents/index.ts

@@ -16,17 +16,21 @@
  * children persist their sessions per run to make that possible).
  */
 
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { CHILD_WROTE_CHANNEL, type ChildWrote } from "../lib/child-writes.ts";
+import { canShowCustomUi } from "../lib/headless-output.ts";
+import { existsSync, mkdirSync, readdirSync, renameSync, writeFileSync, readFileSync } from "node:fs";
+import { AGENT_CRON_CHANNEL, AGENT_CRON_FIRE_CHANNEL, type AgentCronFire, type AgentCronRequest, agentCronTools, agentOwnsCronJobs } from "../lib/agent-cron.ts";
 import os from "node:os";
 import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { StringEnum } from "@earendil-works/pi-ai";
-import type { Api, Model } from "@earendil-works/pi-ai";
-import { getAgentDir, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import type { Api, Message, Model } from "@earendil-works/pi-ai";
+import { type AgentToolResult, defineTool, getAgentDir, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
 import { SUBAGENT_ACTIONS_CHANNEL, type SubagentActionsPayload } from "../auto-mode/actions.ts";
-import { type AgentDefinition, type AgentSource, agentDirs, discoverAgents } from "./agents.ts";
-import { modelIdentity, modelSpec, supportsImageInput } from "../lib/model-policy.ts";
+import { type AgentDefinition, agentFileSources, BUNDLED_AGENTS_DIR, discoverAgents } from "./agents.ts";
+import { findConfigured, modelIdentity, modelSpec, supportsImageInput } from "../lib/model-policy.ts";
 import { MODEL_UNUSABLE_CHANNEL, type ModelUnusableEvent, withoutUnusable } from "../lib/model-unusable.ts";
 import { applicableSubagentDefault, loadSubagentDefault, persistSubagentModel, type SubagentDefault } from "./default-model.ts";
 import {
@@ -35,27 +39,44 @@ import {
 	type SubagentModelResolution,
 	SUBAGENT_STATUS_CHANNEL,
 	subagentModelNotes,
+	refusedModelNote,
 	subagentModelsReminder,
 	subagentStatusModel,
 } from "./model-select.ts";
-import { modelPickerComponent, pickerSpec, toPickerEntries, type PickerEntry } from "../auto-mode/model-picker.ts";
+import { modelPickerComponent, pickerSpec, toPickerEntries, type PickerEntry } from "../lib/model-picker.ts";
+import { chosenModelWarnings } from "../lib/model-choice-warnings.ts";
+import { readSuggestNewerModels } from "../lib/one-code-settings.ts";
 import { defaultDiscoverRoots, discoverPlugins } from "../lib/plugins.ts";
+import { guideDocs } from "../lib/guide-docs.ts";
+import { extensionVersion } from "../lib/package-version.ts";
+import { scanSkills } from "../lib/skill-scan.ts";
+import { type GuideInput, guideAgentDefinition, settingsSetup } from "./guide-agent.ts";
+import { MCP_STATUS_CHANNEL, MCP_STATUS_REQUEST_CHANNEL, type McpServerStatus, type McpStatusEvent, type McpStatusKind } from "../lib/mcp-status.ts";
+
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
-import { MCP_TOOLS_CHANNEL, type McpToolsPayload } from "../lib/mcp-share.ts";
-import { resolveModelTier } from "../lib/model-tier.ts";
+import { requestSystemPrompt } from "../lib/prompt-options.ts";
+import { captureMatches, LAST_REQUEST_CHANNEL, type RequestCapture } from "../lib/request-replay.ts";
+import { BTW_FORK_CHANNEL, btwForkDescription, btwForkName, btwForkRecord, btwForkTaskId, type BtwForkRequest, type BtwForkResult } from "../lib/btw-fork.ts";
+import { watchMcpTools } from "../lib/mcp-share.ts";
+import { sessionModelTier } from "../lib/session-model-tier.ts";
+import { type DescriptionForm, followDescriptionForm, registerVariantTool } from "../lib/tool-variants.ts";
+import { agentDescription } from "./agent-description.ts";
+import { prepareAgentArguments } from "./agent-args.ts";
+import { projectConfigDirName } from "../lib/config-mode.ts";
 import { pendingClaimReminder } from "./pending-claim.ts";
 import { watchPermissionBridge } from "../permissions/subagent-gate.ts";
 import { watchHookBridge } from "../hooks/subagent-bridge.ts";
-import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { CONTEXT_ORDER, REMINDER_CHANNEL, type ReminderPayload } from "../lib/reminders.ts";
 import { type BackgroundTask, generateTaskId, TASK_REGISTER_CHANNEL } from "../background/registry.ts";
 import { type ChildAction } from "../auto-mode/actions.ts";
 import { type ChildOutcome, forkTaskMessage, OUTPUT_CAP, type RpcChildHandle } from "./outcome.ts";
-import { type AgentRunRecord, resolveRunName, RunRegistry } from "./runs.ts";
+import { type AgentRunRecord, FORK_AGENT, freeRunName, resolveRunName, RunRegistry } from "./runs.ts";
 import { SubagentRuntime } from "./runner.ts";
 import { emptyUsage, formatStats, type UsageTotals } from "./usage.ts";
-import { cleanupWorktree, createWorktree, isGitRepo, type Worktree } from "./worktree.ts";
-import { findGitRoot } from "../lib/git.ts";
-import { registerWorktreeIsolation } from "../lib/worktree-isolation.ts";
+import { cleanupWorktree, createWorktree, isGitRepo, keptWorktreeNote, type Worktree } from "./worktree.ts";
+import { findProjectRoot } from "../lib/git.ts";
+import { followEnteredWorktree, registerWorktreeIsolation } from "../lib/worktree-isolation.ts";
+import { sessionWorkCwd } from "../lib/worktree-channel.ts";
 import {
 	AGENT_NOTE,
 	agentMessage,
@@ -80,14 +101,33 @@ import { recordUsage } from "../lib/usage-bus.ts";
 import { SUBAGENT_DEFAULT_CHANGED_CHANNEL } from "../lib/settings-channels.ts";
 import { SubagentWidget } from "./panel-widget.ts";
 import { type ProseRenderer, renderTranscript } from "./panel-render.ts";
-import { decodeStripKey, type StripKey } from "./panel-keys.ts";
-import { reduceShellKey } from "./shell-panel.ts";
+import { decodeStripKey, editorYieldsDown, isStripEntryKey, type StripKey } from "./panel-keys.ts";
+import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
+import { AGENT_VIEW_CHANNEL, type AgentViewAnnouncement, agentViewTarget, userMessageForAgent } from "../lib/agent-view.ts";
+import { isKeyRelease, keyId, keyText } from "../lib/key-input.ts";
+import { moveTasksSelection, renderShellDetail, renderTasksDialog, settleTasksView, shellDetailKey, tasksItems, type TasksView } from "./tasks-dialog.ts";
+import { reduceShellKey, shellRows } from "./shell-panel.ts";
 import { trackShellTasks } from "../lib/shell-tasks.ts";
 import { createMarkdownProse } from "./prose.ts";
+import { asScrollableViewport, ViewportMirror } from "./viewport-mirror.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
-
-/** The catalog shipped in this package: <package>/agents. */
-const BUNDLED_AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
+import { extendingCompletions } from "../lib/argument-hints.ts";
+import { CONTEXT_BASELINE_CHANNEL, restoredContext } from "../lib/context-stack.ts";
+import { emptySubagentBaseline, planSubagentAnnouncement, subagentBaseline, subagentBaselineFromStack, type SubagentBaseline } from "./announce.ts";
+import { panelUi } from "../lib/panel-focus.ts";
+import { dockRowsReporter, trackDockRows } from "../lib/dock-rows.ts";
+
+/** How the guide's setup list names a server that is not connected. */
+const MCP_STATUS_LABELS: Record<McpStatusKind, string | undefined> = {
+	connected: undefined,
+	failed: "failed to connect",
+	authNeeded: "needs authentication",
+	connecting: "connecting",
+	disabled: "disabled",
+};
+
+/** This package's root (the `one-code-extension` directory). */
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 interface RunRequest {
 	agent: string;
@@ -105,6 +145,8 @@ interface RunRequest {
 	fallbackModel?: string;
 	thinking?: string;
 	worktree?: boolean;
+	/** Claude Code's `description`: the run's title (AgentRunRecord.description). */
+	description?: string;
 }
 
 /**
@@ -134,6 +176,8 @@ interface TaskResult {
 	usage: UsageTotals;
 	failed?: boolean;
 	worktreePath?: string;
+	/** The kept worktree's branch, which holds any commits the agent made. */
+	worktreeBranch?: string;
 	worktreeKept?: boolean;
 	/** What the child did, for auto mode's return review. */
 	actions?: ChildAction[];
@@ -143,12 +187,10 @@ const SubagentParams = Type.Object({
 	subagent_type: Type.Optional(
 		Type.String({
 			description:
-				'The agent to run — a name from the "Available agents" system reminder, or "fork" to clone this conversation. Required unless action:"list". To run several in parallel, issue multiple Agent tool calls in one turn.',
+				'The agent to run — a name from the "Available agents" system reminder (general-purpose when omitted), or "fork" to clone this conversation. To run several in parallel, issue multiple Agent tool calls in one turn.',
 		}),
 	),
-	task: Type.Optional(
-		Type.String({ description: "The task — a complete, self-contained instruction (the agent cannot ask follow-ups). Required with subagent_type." }),
-	),
+	task: Type.String({ description: "The task — a complete, self-contained instruction (the agent cannot ask follow-ups)." }),
 	// `prompt` is Claude Code's name for the task text and `description` its short
 	// title. A CC-trained model writes `{subagent_type, description, prompt}`; pi
 	// does not reject unknown keys, so without these the task silently became ""
@@ -186,7 +228,6 @@ const SubagentParams = Type.Object({
 	),
 });
 
-export const FORK_AGENT = "fork";
 
 /**
  * The anti-fabrication sentence, carried by the tool RESULT of a background
@@ -218,10 +259,34 @@ interface Resident {
 	 * ahead of the report in its notification.
 	 */
 	turnHandlers: Array<(outcome: ChildOutcome, review: HandBackVerdict | undefined, stopped: boolean) => void>;
+	/** Finished turns whose hand-back is still waiting on auto mode's review, so not yet delivered. */
+	reviewing: number;
+}
+
+/**
+ * Whether a resident has a report still to deliver: a turn is running, a turn's
+ * handler is queued, or a finished turn waits on its review. A resident that
+ * has delivered stays alive and idle for SendMessage; counting it as pending
+ * told a cheap-tier model to retract an answer the agent really gave
+ * (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 M4).
+ */
+function residentPending(resident: Resident): boolean {
+	return !resident.handle.exited() && (resident.handle.busy() || resident.turnHandlers.length > 0 || resident.reviewing > 0);
 }
 
 export default function subagentsExtension(pi: ExtensionAPI) {
+	const requestTier = sessionModelTier(pi);
 	const registry = new RunRegistry();
+	/**
+	 * The session's permission mode as the permissions extension last announced
+	 * it; auto (the shipped default) until the first announcement. It picks the
+	 * hand-back's shape (notifyHandBack).
+	 */
+	let permissionMode = "auto";
+	pi.events.on(PERMISSION_STATUS_CHANNEL, (data) => {
+		const mode = (data as Partial<PermissionStatus> | undefined)?.mode;
+		if (typeof mode === "string") permissionMode = mode;
+	});
 	/**
 	 * Task ids with a blocking child (nested spawn or SendMessage resume) currently
 	 * running (SendMessage must wait for these). Keyed by task id, like `residents`:
@@ -231,6 +296,23 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	const runningIds = new Set<string>();
 	/** Task id → live resident. */
 	const residents = new Map<string, Resident>();
+	/**
+	 * Task id → the main session's tool call that started the run's current
+	 * turn (its Agent call, or the latest SendMessage to it); a nested run
+	 * answers with its parent's (`parentTaskOf`). The permission gate reads the
+	 * main session only as far as that call (auto-mode/history.ts
+	 * childHistoryCursor). Ids only, a few per run.
+	 */
+	const mainCallFor = new Map<string, string>();
+	const parentTaskOf = new Map<string, string>();
+	const mainCallOf = (taskId: string): string | undefined => {
+		// Bounded: nesting is capped far below this, and a cycle must not hang the gate.
+		for (let id: string | undefined = taskId, depth = 0; id !== undefined && depth < 8; id = parentTaskOf.get(id), depth++) {
+			const call = mainCallFor.get(id);
+			if (call) return call;
+		}
+		return undefined;
+	};
 	/**
 	 * Task ids of background runs spawned during the agent loop now in flight.
 	 * Cleared at `agent_start`; read at `agent_end` to notice a turn that ended
@@ -256,7 +338,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	const stoppedTaskIds = new Set<string>();
 	let lastCtx: ExtensionContext | undefined;
 	const shellTasks = trackShellTasks(pi);
-	const panel = new SubagentWidget(liveRuns, () => lastCtx, shellTasks);
+	const panel = new SubagentWidget(liveRuns, () => lastCtx, shellTasks, dockRowsReporter(pi.events, "subagents"));
+	// The other strips below the editor (workflow status rows), so the agent view leaves their rows free.
+	const dock = trackDockRows(pi.events);
 
 	/**
 	 * Register a child in the live panel and return the wiring the spawn sites
@@ -273,6 +357,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			liveRuns.register({
 				taskId: record.taskId,
 				name: record.name,
+				description: record.description,
 				agentType: request.agent,
 				model: request.model,
 				thinking: request.thinking,
@@ -301,37 +386,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
 	// Live MCP tool definitions published by the mcp extension; injected into
 	// child sessions so subagents share the parent's open connections (no reconnect).
-	// Empty when no MCP servers are configured, so this is a no-op for most sessions.
-	// The parent's MCP connect runs in the background, so a spawn in the first
-	// seconds of a session waits for the settled publish (capped, so a hung server
-	// can't stall spawns) instead of baking in a still-connecting snapshot.
-	const MCP_SETTLE_CAP_MS = 10_000;
-	let mcpTools: ToolDefinition[] = [];
-	let mcpSettled = false;
-	let resolveMcpSettled: (() => void) | undefined;
-	const mcpSettledPromise = new Promise<void>((resolve) => {
-		resolveMcpSettled = resolve;
-	});
-	pi.events.on(MCP_TOOLS_CHANNEL, (data) => {
-		const payload = data as McpToolsPayload | undefined;
-		mcpTools = payload?.tools ?? [];
-		if (payload?.settled) {
-			mcpSettled = true;
-			resolveMcpSettled?.();
-		}
-	});
-	const awaitMcpTools = async (): Promise<ToolDefinition[]> => {
-		if (!mcpSettled) {
-			await Promise.race([
-				mcpSettledPromise,
-				new Promise<void>((resolve) => {
-					const timer = setTimeout(resolve, MCP_SETTLE_CAP_MS);
-					timer.unref?.();
-				}),
-			]);
-		}
-		return mcpTools;
-	};
+	const awaitMcpTools = watchMcpTools(pi.events);
 
 	// The parent permissions extension's decision closure, used to gate a child's
 	// tool calls through the real pipeline (mode inheritance, classifier, prompts
@@ -361,10 +416,21 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		// The default may have been that model: recompute and republish the
 		// reminder/banner so the next request already names the replacement.
 		const event = data as ModelUnusableEvent;
-		if (rememberUnusable(event.model) && lastCtx) emitModelStatus(lastCtx);
+		if (rememberUnusable(event.model) && lastCtx) emitModelStatus(lastCtx, lastCtx.model, event.model);
 	});
 
-	/** The in-process runner, built lazily on first run and shared across all runs. */
+	// After `enter_worktree` the session works in the worktree, but pi keeps
+	// ctx.cwd at the original checkout: spawns start where the session works.
+	const enteredWorktree = followEnteredWorktree(pi.events);
+	const workCwd = (ctx: ExtensionContext) => sessionWorkCwd(enteredWorktree(), ctx.cwd);
+
+	/**
+	 * The in-process runner, built lazily on first run and shared across all runs.
+	 * A failed build (a malformed models.json or auth.json) is forgotten, so the
+	 * next spawn tries again instead of every later spawn failing on the same
+	 * rejected promise; callers await it before they mark a run as running
+	 * (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 L8).
+	 */
 	let runtimePromise: Promise<SubagentRuntime> | undefined;
 	const getRuntime = (ctx: ExtensionContext) =>
 		(runtimePromise ??= SubagentRuntime.create(
@@ -386,19 +452,85 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				pi.events.emit(MODEL_UNUSABLE_CHANNEL, { model, reason } satisfies ModelUnusableEvent);
 				const live = liveUiCtx(lastCtx);
 				live?.ui.notify(`Subagent model ${model} is not usable on this account (${reason}); automatic selection skips it from now on.`, "warning");
-				if (lastCtx) emitModelStatus(lastCtx);
+				if (lastCtx) emitModelStatus(lastCtx, lastCtx.model, model);
+			},
+			(path, agent) => pi.events.emit(CHILD_WROTE_CHANNEL, { path, ...(agent ? { agent } : {}) } satisfies ChildWrote),
+		).catch((error: unknown) => {
+			runtimePromise = undefined;
+			throw error;
+		}));
+	/** The runtime, or the startup error as a message a failed run can report. */
+	const runtimeOrError = (ctx: ExtensionContext): Promise<SubagentRuntime | string> =>
+		getRuntime(ctx)
+			.then((runtime) => shuttingDown ? "the session ended before the agent started" : runtime)
+			.catch((error: unknown) => `could not start the subagent runtime: ${error instanceof Error ? error.message : String(error)}`);
+
+	// The mcp extension answers a status request synchronously on the bus.
+	let mcpStatus: McpServerStatus[] | undefined;
+	pi.events.on(MCP_STATUS_CHANNEL, (data) => {
+		mcpStatus = (data as McpStatusEvent).servers;
+	});
+	/** The configured servers now; empty when the mcp extension is not loaded. */
+	const requestMcpStatus = (): McpServerStatus[] => {
+		mcpStatus = undefined;
+		pi.events.emit(MCP_STATUS_REQUEST_CHANNEL, {});
+		return (mcpStatus as McpServerStatus[] | undefined) ?? [];
+	};
+
+	/**
+	 * What the code-defined `one-code-guide`'s prompt lists (guide-agent.ts): the
+	 * user's custom skills and agents, enabled plugins, MCP servers, installed pi
+	 * packages and extensions, and pi's settings keys. Read only when a spawn
+	 * reads the guide's prompt.
+	 */
+	const guideInput = (cwd: string, catalog: readonly AgentDefinition[], plugins: ReturnType<typeof discoverPlugins>): GuideInput => {
+		const agentDir = getAgentDir();
+		let settingsText: string | undefined;
+		try {
+			settingsText = readFileSync(join(agentDir, "settings.json"), "utf-8");
+		} catch {
+			// No settings file yet: no packages or keys to list.
+		}
+		let extensions: string[] = [];
+		try {
+			extensions = readdirSync(join(agentDir, "extensions")).filter((entry) => !entry.startsWith("."));
+		} catch {
+			// No user extensions directory.
+		}
+		// Every configured server, from the mcp extension's status snapshot: a
+		// failed, disabled or resource-only server registers no tools.
+		const mcpServers = requestMcpStatus().map((server) => ({ name: server.name, status: MCP_STATUS_LABELS[server.status] }));
+		return {
+			docs: guideDocs(),
+			install: {
+				shape: process.env.ONECODE_INSTALL_METHOD ? "app" : "extension",
+				method: process.env.ONECODE_INSTALL_METHOD,
+				agentDir,
+				version: process.env.CC_VERSION ?? extensionVersion(),
+			},
+			setup: {
+				skills: scanSkills(cwd, os.homedir(), agentDir, plugins.skills).map((skill) => skill.name),
+				agents: catalog.filter((agent) => agent.source !== "built-in" && !agent.source.startsWith(BUNDLED_AGENTS_DIR)).map((agent) => agent.name),
+				plugins: plugins.enabledPlugins.map((plugin) => plugin.name),
+				mcpServers,
+				extensions,
+				...settingsSetup(settingsText, PACKAGE_ROOT),
 			},
-		));
+		};
+	};
 
 	const loadAgents = (cwd: string) => {
 		// Plugin agents sit between bundled and user definitions, and are exposed
 		// namespaced (`<plugin>:<agent>`) so two plugins can ship the same name.
-		const sources: Array<string | AgentSource> = [
-			BUNDLED_AGENTS_DIR,
-			...discoverPlugins(defaultDiscoverRoots(getAgentDir(), cwd)).agentDirs,
-			...agentDirs(cwd, os.homedir()),
-		];
-		return discoverAgents(sources);
+		// The code-defined guide ranks below every agent file, so one of the same
+		// name replaces it.
+		const plugins = discoverPlugins(defaultDiscoverRoots(getAgentDir(), cwd));
+		const fileSources = agentFileSources(cwd, os.homedir(), plugins.agentDirs);
+		// The prompt is built from the catalog it sits in, when a spawn reads it.
+		let catalog: AgentDefinition[] = [];
+		const guide = guideAgentDefinition(() => guideInput(cwd, catalog, plugins));
+		catalog = discoverAgents([{ agents: [guide] }, ...fileSources]);
+		return catalog;
 	};
 
 	// Claude Code closes every catalog row with a tools clause — "(Tools: *)",
@@ -408,7 +540,8 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	const toolsClause = (a: AgentDefinition): string => {
 		if (a.tools && a.tools.length > 0) return ` (Tools: ${a.tools.join(", ")})`;
 		if (a.excludeTools && a.excludeTools.length > 0) return ` (Tools: All tools except ${a.excludeTools.join(", ")})`;
-		return " (Tools: *)";
+		// Claude Code writes "*" for its built-in agents and "All tools" for an agent file that lists none.
+		return a.source === "built-in" || a.source.startsWith(BUNDLED_AGENTS_DIR) ? " (Tools: *)" : " (Tools: All tools)";
 	};
 
 	const describeAgents = (cwd: string) => {
@@ -435,14 +568,14 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				// A kept worktree can host a resumed run in a NEW process, where
 				// createWorktree's registration no longer exists — re-register so the
 				// git-isolation guard survives the restart. A removed worktree's entry
-				// is inert (no session runs there any more). findGitRoot instead of
+				// is inert (no session runs there any more). findProjectRoot instead of
 				// `git rev-parse` because session_start handlers must stay fast
 				// (findings §15); a slightly-off sharedRoot only softens one message —
 				// the worktree containment check itself uses the exact record.cwd.
 				if (record.worktree && !worktreesSeen.has(record.cwd)) {
 					worktreesSeen.add(record.cwd);
 					if (!existsSync(record.cwd)) continue;
-					sharedRoot ??= findGitRoot(ctx.cwd) ?? ctx.cwd;
+					sharedRoot ??= findProjectRoot(ctx.cwd) ?? ctx.cwd;
 					registerWorktreeIsolation(record.cwd, sharedRoot);
 				}
 			}
@@ -486,30 +619,67 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		return resolution;
 	};
 
+	// Message 1 is frozen once a request has gone out (decisions/caching.md):
+	// after that, a model the account refused is corrected by a one-shot, not by
+	// rewriting the menu and re-caching the conversation. A user's /model or
+	// /subagent still rewrites it.
+	let requestSent = false;
+	let restoredSession = false;
+	let capabilityBaseline: SubagentBaseline = emptySubagentBaseline();
+	const publishCapabilityBaseline = (baseline: SubagentBaseline) => {
+		pi.events.emit(CONTEXT_BASELINE_CHANNEL, { key: "subagents", value: baseline });
+	};
+	pi.on("context", () => {
+		requestSent = true;
+	});
+
 	/**
 	 * The every-turn menu reminder and the banner's subagent-default status.
 	 * Every-turn because reminders are transient per-request injections — that
 	 * scope survives compaction by construction — and keyed so a model change
 	 * replaces it: the very next LLM call, even mid-turn, carries the update.
+	 * `refused` names a model the account just refused: once a request has gone
+	 * out, that change rides a one-shot instead.
 	 */
-	const emitModelStatus = (ctx: ExtensionContext, sessionModel = ctx.model) => {
+	const emitModelStatus = (ctx: ExtensionContext, sessionModel = ctx.model, refused?: string) => {
 		const available = usableModels(ctx);
 		const configured = applicableSubagentDefault(loadSubagentDefault(os.homedir()), sessionModel);
 		const resolution = resolveAutoDefault(sessionModel, available, configured);
+		const text = subagentModelsReminder({
+			available, sessionModel, defaultModel: resolution.model, defaultSource: resolution.source, configured,
+			requireImageInput: supportsImageInput(sessionModel),
+		});
 		for (const notice of resolution.notices) notifyModelOnce(ctx, notice);
-		pi.events.emit(REMINDER_CHANNEL, {
-			text: subagentModelsReminder({
-				available,
-				sessionModel,
-				defaultModel: resolution.model,
-				defaultSource: resolution.source,
-				configured,
-				requireImageInput: supportsImageInput(sessionModel),
-			}),
-			scope: "every-turn",
-			key: "subagent-models",
-			placement: "first-prepend",
-			order: CONTEXT_ORDER.subagentModels,
+		// The user's own subagentModel setting is honoured, so say what it costs:
+		// a newer model in its line, or a model far weaker than the session's.
+		if (resolution.source === "default" && resolution.model) {
+			for (const warning of chosenModelWarnings({ available, sessionModel, chosen: resolution.model, role: "subagent", suggestNewer: readSuggestNewerModels(os.homedir()) })) {
+				notifyModelOnce(ctx, `${warning.text} ${warning.fix}`);
+			}
+		}
+		// Keep the established narrow refusal correction: it does not claim the
+		// entire menu was reprinted, and it remains useful on restored sessions.
+		if (refused !== undefined && requestSent) {
+			// The narrow correction is all the model needs now, but persist the
+			// corrected complete menu as announcement history. Otherwise the next
+			// process would compare the stale menu with the same live catalog and
+			// append a spurious full-menu correction on every resume.
+			capabilityBaseline = {
+				...capabilityBaseline,
+				models: text,
+				refusedModels: [...new Set([...capabilityBaseline.refusedModels, refused])],
+			};
+			publishCapabilityBaseline(capabilityBaseline);
+			pi.events.emit(REMINDER_CHANNEL, { text: refusedModelNote(refused, resolution.model) });
+			pi.events.emit(SUBAGENT_STATUS_CHANNEL, subagentStatusModel(configured, resolution));
+			return;
+		}
+		const plan = planSubagentAnnouncement({ restored: restoredSession, baseline: capabilityBaseline, capability: "models", text });
+		capabilityBaseline = plan.baseline;
+		if (plan.kind !== "none") publishCapabilityBaseline(capabilityBaseline);
+		if (plan.kind === "addendum") pi.events.emit(REMINDER_CHANNEL, { text: plan.text });
+		else if (!restoredSession) pi.events.emit(REMINDER_CHANNEL, {
+			text, scope: "every-turn", key: "subagent-models", placement: "first-prepend", order: CONTEXT_ORDER.subagentModels,
 		});
 		pi.events.emit(SUBAGENT_STATUS_CHANNEL, subagentStatusModel(configured, resolution));
 	};
@@ -521,27 +691,26 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	 * byte-stable within a session, so it costs nothing in prompt-cache terms.
 	 */
 	const emitAgentCatalog = (ctx: ExtensionContext) => {
-		pi.events.emit(REMINDER_CHANNEL, {
-			scope: "every-turn",
-			key: "subagent-agents",
-			text: `Available agent types for the Agent tool:\n${describeAgents(ctx.cwd)}\n\nWhen you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.`,
-			placement: "first-prepend",
-			order: CONTEXT_ORDER.agents,
+		const text = `Available agent types for the Agent tool:\n${describeAgents(ctx.cwd)}\n\nWhen you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.`;
+		const plan = planSubagentAnnouncement({ restored: restoredSession, baseline: capabilityBaseline, capability: "agents", text });
+		capabilityBaseline = plan.baseline;
+		if (plan.kind !== "none") publishCapabilityBaseline(capabilityBaseline);
+		if (plan.kind === "addendum") pi.events.emit(REMINDER_CHANNEL, { text: plan.text });
+		else if (!restoredSession) pi.events.emit(REMINDER_CHANNEL, {
+			scope: "every-turn", key: "subagent-agents", text, placement: "first-prepend", order: CONTEXT_ORDER.agents,
 		});
 	};
 
-	const emitDelegationSteer = (sessionModel = lastCtx?.model) => {
-		if (resolveModelTier(sessionModel) === "tiny") {
-			pi.events.emit(REMINDER_CHANNEL, {
-				scope: "every-turn",
-				key: "subagent-delegation",
-				text: DELEGATION_STEER,
-				placement: "first-prepend",
-				order: CONTEXT_ORDER.delegation,
-			});
-		} else {
-			pi.events.emit(REMINDER_CHANNEL, { key: "subagent-delegation", remove: true });
-		}
+	const emitDelegationSteer = () => {
+		const text = requestTier() === "tiny" ? DELEGATION_STEER : null;
+		const plan = planSubagentAnnouncement({ restored: restoredSession, baseline: capabilityBaseline, capability: "delegation", text });
+		capabilityBaseline = plan.baseline;
+		if (plan.kind !== "none") publishCapabilityBaseline(capabilityBaseline);
+		if (plan.kind === "addendum") pi.events.emit(REMINDER_CHANNEL, { text: plan.text });
+		else if (!restoredSession && text !== null) pi.events.emit(REMINDER_CHANNEL, {
+			scope: "every-turn", key: "subagent-delegation", text, placement: "first-prepend", order: CONTEXT_ORDER.delegation,
+		});
+		else if (!restoredSession) pi.events.emit(REMINDER_CHANNEL, { key: "subagent-delegation", remove: true });
 	};
 
 	let shuttingDown = false;
@@ -552,8 +721,8 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	 * would get the reminder on every delegating turn for nothing, and the
 	 * trigger fires on correct behaviour as readily as on the failure.
 	 */
-	const backstopApplies = (ctx: ExtensionContext | undefined) => {
-		const tier = resolveModelTier(ctx?.model);
+	const backstopApplies = () => {
+		const tier = requestTier();
 		return tier === "cheap" || tier === "tiny";
 	};
 	pi.on("agent_start", () => {
@@ -564,16 +733,16 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	pi.on("agent_settled", () => {
 		parentBusy = false;
 	});
-	pi.on("agent_end", (_event, ctx) => {
+	pi.on("agent_end", () => {
 		const spawned = [...spawnedThisLoop];
 		spawnedThisLoop.clear();
 		// Tier check first: on a frontier session the backstop never fires, so the
 		// lookups below would be discarded work on every turn that delegated.
-		if (!backstopApplies(ctx)) return undefined;
+		if (!backstopApplies()) return undefined;
 		const pending = spawned
 			.filter((taskId) => {
 				const resident = residents.get(taskId);
-				return (resident !== undefined && !resident.handle.exited()) || runningIds.has(taskId);
+				return (resident !== undefined && residentPending(resident)) || runningIds.has(taskId);
 			})
 			.map((taskId) => registry.resolve(taskId))
 			.filter((record): record is AgentRunRecord => record !== undefined)
@@ -584,6 +753,17 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", (_event, ctx) => {
+		const restored = restoredContext(pi.events);
+		restoredSession = restored !== undefined;
+		requestSent = restoredSession;
+		// New snapshots carry exact structured text; old v1 snapshots can still
+		// seed from their locked first-prepend blocks without rewriting them.
+		capabilityBaseline = subagentBaseline(restored?.baselines.subagents)
+			?? subagentBaselineFromStack(restored?.stack ?? []);
+		// A refusal correction is a real capability fact, not merely UI prose.
+		// Restore its selection floor before rebuilding the menu, otherwise this
+		// process can choose the same refused model and reissue a false correction.
+		for (const model of capabilityBaseline.refusedModels) unusableModels.add(model);
 		lastCtx = ctx;
 		// A replaced session (/clear, /new, /resume) never reaches this instance
 		// with the old one's agents: pi emits `session_shutdown` (reason "new" /
@@ -594,12 +774,12 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		reconstructRuns(ctx);
 		emitModelStatus(ctx);
 		emitAgentCatalog(ctx);
-		emitDelegationSteer(ctx.model);
+		emitDelegationSteer();
 		registerPanelInputHook(ctx);
 	});
 	pi.on("model_select", (event, ctx) => {
 		emitModelStatus(ctx, event.model);
-		emitDelegationSteer(event.model);
+		emitDelegationSteer();
 	});
 	// Another extension wrote `subagentModel` on disk (`/doctor preset`): drop the
 	// cached automatic default and republish the reminder + banner status, the
@@ -703,13 +883,29 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	 * back.
 	 */
 	let view: { retarget(taskId: string): void; scrollBy(delta: number): void; close(): void } | undefined;
-	/** Rows kept clear at the bottom: token counter + editor(3) + mode line + strip hint + strip rows + shell section + cwd/status(2) + one spare. */
+	/** Rows kept clear at the bottom: token counter + editor(3) + mode line + strip hint + strip rows + shell section + other strips + cwd/status(2) + one spare. */
 	const viewReserve = () => {
 		const shellLines = panel.shellLineCount();
-		return panel.rowCount() + (shellLines ? shellLines + 1 : 0) + 9;
+		return panel.rowCount() + (shellLines ? shellLines + 1 : 0) + dock.others("subagents") + 9;
+	};
+
+	/**
+	 * Tell the editor which agent it now addresses (lib/agent-view.ts), or that
+	 * it is back on main. Viewing a run also puts it on `/tasks`' Completed list
+	 * once it settles, as Claude Code keeps a viewed agent (findings §40).
+	 */
+	const announceView = (taskId: string | undefined) => {
+		const run = taskId === undefined ? undefined : liveRuns.get(taskId);
+		if (run) liveRuns.markViewed(run.taskId);
+		const announcement: AgentViewAnnouncement = run ? { target: agentViewTarget(run, run.agentType === FORK_AGENT) } : {};
+		pi.events.emit(AGENT_VIEW_CHANNEL, announcement);
 	};
 
 	const openView = (ctx: ExtensionContext, taskId: string) => {
+		if (ctx.mode !== "tui") {
+			ctx.ui.notify("The live subagent panel requires TUI mode. Use /tasks for task status; task_output and task_stop inspect or stop a task.", "warning");
+			return;
+		}
 		if (view) return view.retarget(taskId);
 		let currentId = taskId;
 		let scroll = 0;
@@ -717,12 +913,16 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		let closed = false;
 		let repaintFn: (() => void) | undefined;
 		let doneFn: ((result: null) => void) | undefined;
+		/** Fullscreen only: turns pi's own viewport scrolling into view scrolling. */
+		let mirror: ViewportMirror | undefined;
 		const entry = {
 			retarget(id: string) {
 				if (currentId === id) return;
 				currentId = id;
 				scroll = 0;
+				mirror?.park(0);
 				panel.setView(id);
+				announceView(id);
 				repaintFn?.();
 			},
 			scrollBy(delta: number) {
@@ -733,22 +933,26 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				if (closed) return;
 				closed = true;
 				if (view === entry) view = undefined;
+				mirror?.restore();
+				mirror = undefined;
 				panel.setView(undefined);
+				announceView(undefined);
 				doneFn?.(null);
 			},
 		};
 		view = entry;
 		panel.setView(currentId);
+		announceView(currentId);
 		void (async () => {
 			const prose = await getProse(ctx);
 			if (closed) return;
-			await ctx.ui.custom<null>(
+			await panelUi(pi.events, ctx.ui).custom<null>(
 				(tui, theme, _keybindings, done) => {
 					doneFn = done;
 					// close() raced ahead of the factory — dissolve as soon as we exist.
 					if (closed) queueMicrotask(() => done(null));
 					const paint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme) };
-					let cache: { width: number; lines: string[] } | undefined;
+					let cache: { width: number; height: number; lines: string[] } | undefined;
 					const live = liveRepaint(
 						tui,
 						() => {
@@ -758,19 +962,32 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					);
 					repaintFn = live.repaint;
 					const height = () => Math.max(8, tui.terminal.rows - viewReserve());
+					const viewport = asScrollableViewport(tui);
+					if (viewport && !closed) mirror = new ViewportMirror(viewport);
 					return {
 						render: (width: number) => {
-							if (cache?.width === width) return cache.lines;
+							// The page keys and the wheel scroll pi's main viewport, under
+							// this overlay; take the move as ours and park main again.
+							if (mirror) {
+								const next = mirror.absorb(scroll, maxScroll);
+								if (next !== scroll) {
+									scroll = next;
+									cache = undefined;
+								}
+							}
+							// Keyed by height too: a resize or another strip changing size moves the room.
+							const viewHeight = height();
+							if (cache?.width === width && cache.height === viewHeight) return cache.lines;
 							const run = liveRuns.get(currentId);
 							let lines: string[];
 							if (run) {
-								const transcript = renderTranscript({ run, width, height: height(), scroll, now: Date.now(), prose }, paint);
+								const transcript = renderTranscript({ run, width, height: viewHeight, scroll, now: Date.now(), prose }, paint);
 								maxScroll = transcript.maxScroll;
 								lines = transcript.lines;
 							} else {
 								lines = [paint.fg("dim", "agent gone")];
 							}
-							cache = { width, lines: lines.map((line) => truncateLine(line, width)) };
+							cache = { width, height: viewHeight, lines: lines.map((line) => truncateLine(line, width)) };
 							return cache.lines;
 						},
 						invalidate: () => {
@@ -790,10 +1007,12 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		if (panelHookRegistered || !registerCtx.hasUI) return;
 		panelHookRegistered = true;
 		let chordArmed = false;
+		// Leaving the strip hands focus back to the editor and keeps any open view,
+		// as Claude Code's Esc does: the editor then addresses the viewed agent.
 		const leave = () => {
 			panel.setFocus(undefined);
-			closeView();
 		};
+		const editorEmpty = () => (panel.editorBaseline as { getText?(): string } | undefined)?.getText?.() === "";
 		type KeyResult = { consume: boolean } | undefined;
 		// Actions shared by both key modes (browse and read), declared once so the
 		// two switches below never drift. esc consumes only when idle — a streaming
@@ -814,16 +1033,15 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			return { consume: true };
 		};
 		/** Unrecognized key: ctrl+x keeps the stop-all chord armed, else drop focus
-		 * (closing any open view) and let the byte resume in the editor. */
+		 * (any open view stays) and let the byte resume in the editor. */
 		const closeAndPassthrough = (): KeyResult => {
 			if (chordArmed) return { consume: true };
 			leave();
 			return undefined;
 		};
-		const DOWN_KEYS = new Set(["\x1b[B", "\x1bOB"]);
-		/** Keys the agents branch owns; any other decode (typing, shell-only keys
-		 * like left/space) drops focus and passes through — stated positively so a
-		 * future StripKey addition is foreign here by default. */
+		/** Keys the agents branch owns; any other decode (typing) drops focus and
+		 * passes through — stated positively so a future StripKey addition is
+		 * foreign here by default. */
 		const AGENT_KEYS = new Set<StripKey>(["up", "down", "open", "leave", "stop", "stopAll", "pageUp", "pageDown"]);
 		/** Row 0 exists only past the synthetic `main` row. */
 		const focusFirstAgentRow = (): boolean => {
@@ -831,54 +1049,46 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			panel.setFocus(0);
 			return true;
 		};
-		/** The shell-manager stages (chip → list → details); agents keys untouched. */
+		/** The focused shells chip; agents keys untouched. */
 		const handleShellKey = (data: string, ctx: ExtensionContext): KeyResult => {
-			// Focus moved to a dialog/overlay — drop soft focus, let it have the key.
-			if (!panel.editorFocused()) {
-				panel.setShellFocus(undefined);
+			// Focus moved to a dialog/overlay, or the chip cleared under us: drop
+			// soft focus and let the key through.
+			if (!panel.editorFocused() || !panel.shellChipAvailable()) {
+				panel.setShellChipFocus(false);
 				return undefined;
 			}
-			// Derive the row order once per keystroke; every step below reuses it.
-			const ids = panel.shellIds();
-			const focus = panel.anchoredShellFocus(ids);
-			if (!focus) return undefined;
 			const decoded = decodeStripKey(data, false);
-			// ctrl+x (the agents stop-all chord arm) means nothing in the shell
-			// stages — swallow it rather than leaking the raw \x18 into the editor.
+			// ctrl+x (the agents stop-all chord arm) means nothing on the chip:
+			// swallow it rather than leaking the raw \x18 into the editor.
 			if (decoded.chordArmed) return { consume: true };
-			const result = reduceShellKey(focus, decoded.key, ids);
-			if (result.effect === "passthrough") {
-				panel.setShellFocus(undefined);
-				return undefined; // typing resumes in the editor, byte included
-			}
-			if (result.effect === "toAgents") {
-				panel.setShellFocus(undefined);
+			const effect = reduceShellKey(decoded.key);
+			panel.setShellChipFocus(false);
+			if (effect === "passthrough") return undefined; // typing resumes in the editor, byte included
+			if (effect === "toAgents") {
 				if (focusFirstAgentRow()) return { consume: true };
 				// No agent rows below the chip: stay on it. Dropping focus here handed
 				// the NEXT key to the editor, where ↑ recalls the last prompt — the
 				// "sometimes ↓ recalls history" seen on the Windows VM (2026-09-19):
 				// ↓ chip, ↓ (nothing below, focus silently gone), ↑ → history.
-				panel.setShellFocus({ stage: "chip" });
+				panel.setShellChipFocus(true);
 				return { consume: true };
 			}
-			if (result.effect === "stopSelected") {
-				try {
-					panel.selectedShellTask()?.stop();
-				} catch {
-					// A dead process's stop() throwing must not break the panel.
-				}
-				panel.setShellFocus(result.focus, ids);
+			if (effect === "openTasks") {
+				void openTasksDialog(ctx).catch((error: unknown) => {
+					ctx.ui.notify(`Could not open the tasks dialog: ${error instanceof Error ? error.message : String(error)}`, "error");
+				});
 				return { consume: true };
 			}
-			panel.setShellFocus(result.focus, ids);
 			// While the model streams, esc must still interrupt it — consume only when idle.
-			if (decoded.key === "leave" && result.focus === undefined) {
-				return ctx.isIdle() ? { consume: true } : undefined;
-			}
+			if (decoded.key === "leave") return ctx.isIdle() ? { consume: true } : undefined;
 			return { consume: true };
 		};
 		try {
 			registerCtx.ui.onTerminalInput((data) => {
+				// pi-tui calls input listeners before it filters key releases, and a
+				// kitty terminal sends one after every press: a release is never a
+				// key here (it used to read as typing and drop focus).
+				if (isKeyRelease(data)) return undefined;
 				const ctx = lastCtx ?? registerCtx;
 				// Enter focus: down-arrow while the editor holds real focus. Unlike the
 				// workflow strip we do NOT require the editor to be idle — the whole
@@ -887,15 +1097,31 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				// O(rows) checks run only once a Down actually asks to focus, never on
 				// plain typing. Claude Code's order: the FIRST ↓ lands on the shells
 				// chip when shells are running; the next ↓ moves into the agent rows.
-				if (panel.focusIndex === undefined && panel.shellFocus === undefined) {
-					if (!DOWN_KEYS.has(data) || !panel.editorFocused()) return undefined;
+				if (panel.focusIndex === undefined && !panel.shellChipFocused) {
+					// Viewing an agent with the editor focused: the page keys scroll the
+					// view, and Esc in an empty editor goes back to main.
+					if (view && panel.editorFocused()) {
+						const id = keyId(data);
+						if (id === "pageUp" || id === "pageDown") {
+							view.scrollBy(id === "pageUp" ? 10 : -10);
+							return { consume: true };
+						}
+						if (id === "escape" && editorEmpty()) {
+							closeView();
+							return { consume: true };
+						}
+					}
+					if (!isStripEntryKey(data) || !panel.editorFocused()) return undefined;
+					// In a draft, ↓ first moves the cursor, walks recalled history or the
+					// autocomplete list; the strip takes it only past the draft's last line.
+					if (!editorYieldsDown(panel.editorBaseline)) return undefined;
 					if (panel.shellChipAvailable()) {
-						panel.setShellFocus({ stage: "chip" });
+						panel.setShellChipFocus(true);
 						return { consume: true };
 					}
 					return focusFirstAgentRow() ? { consume: true } : undefined;
 				}
-				if (panel.shellFocus !== undefined) return handleShellKey(data, ctx);
+				if (panel.shellChipFocused) return handleShellKey(data, ctx);
 				const focusIndex = panel.focusIndex;
 				if (focusIndex === undefined) return undefined; // unreachable: one of the two focuses was set
 				// The strip emptied under us (finished rows lingered out) — let go.
@@ -910,53 +1136,6 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				}
 				const decoded = decodeStripKey(data, chordArmed);
 				chordArmed = decoded.chordArmed;
-				// Read mode: while a transcript view is open the arrows/page keys
-				// scroll IT (the natural gesture — pi's main screen has no mouse
-				// wheel, so PageUp/PageDown alone were the only path and few reach
-				// for them), Tab retargets to the next agent, Enter/esc close, and
-				// ← closes the transcript but keeps the panel focused on that agent
-				// (setView parked the highlight there) so ↑/↓ can pick a different
-				// agent and Enter reopens — Claude Code's back-to-selection gesture.
-				if (view) {
-					switch (decoded.key) {
-						case "up":
-							view.scrollBy(1);
-							return { consume: true };
-						case "down":
-							view.scrollBy(-1);
-							return { consume: true };
-						case "pageUp":
-							view.scrollBy(10);
-							return { consume: true };
-						case "pageDown":
-							view.scrollBy(-10);
-							return { consume: true };
-						case "left":
-							closeView();
-							return { consume: true };
-						case "switch": {
-							// Retarget to the next agent, anchored to the VIEWED run in the
-							// full row list (not the windowed selection) so it stays correct
-							// once the viewed run scrolls past MAX_STRIP_ROWS; setView then
-							// moves the strip highlight to it when it is in-window.
-							const nextId = panel.nextAgentAfter(panel.viewedTaskId());
-							if (nextId) openView(ctx, nextId);
-							return { consume: true };
-						}
-						case "open": // Enter toggles the view shut, mirroring Enter-to-open.
-							closeView();
-							return { consume: true };
-						case "leave":
-							return doLeave(ctx);
-						case "stop":
-							// Stop the agent whose transcript is open, not the strip selection.
-							return doStop(panel.viewedTaskId());
-						case "stopAll":
-							return doStopAll();
-						default:
-							return closeAndPassthrough(); // typing closes the view and resumes in the editor
-					}
-				}
 				if (!decoded.key || !AGENT_KEYS.has(decoded.key)) return closeAndPassthrough();
 				switch (decoded.key) {
 					case "up":
@@ -964,7 +1143,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 							// Back up out of the agent rows: onto the shells chip when
 							// shells are running, otherwise out of the panel entirely.
 							leave();
-							if (panel.shellChipAvailable()) panel.setShellFocus({ stage: "chip" });
+							if (panel.shellChipAvailable()) panel.setShellChipFocus(true);
 						} else panel.setFocus(focusIndex - 1);
 						return { consume: true };
 					case "down":
@@ -987,8 +1166,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 						return doStopAll();
 					case "pageUp":
 					case "pageDown":
-						// No transcript open → nothing to scroll; swallow so the page
-						// keys never leak into the editor while the strip holds focus.
+						// Scroll an open view; with none open, swallow so the page keys
+						// never leak into the editor while the strip holds focus.
+						view?.scrollBy(decoded.key === "pageUp" ? 10 : -10);
 						return { consume: true };
 				}
 			});
@@ -999,10 +1179,16 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
 	// Compact transcript rendering for the notifications this extension injects
 	// (full body on ctrl+o); the verbose framing stays model-only.
+	// A message is addressed from the agent's task id; its headline names the
+	// agent, from the live registry or the message's own details (a resumed
+	// session has no live runs).
 	for (const customType of ["subagent-message", "subagent-result"]) {
-		pi.registerMessageRenderer(customType, (message, { expanded }, theme) =>
-			notificationComponent(theme, customMessageText(message.content), expanded),
-		);
+		pi.registerMessageRenderer(customType, (message, { expanded }, theme) => {
+			const details = (message as { details?: { taskId?: unknown; name?: unknown } }).details;
+			const agentName = (from: string): string | undefined =>
+				liveRuns.get(from)?.name ?? (details?.taskId === from && typeof details.name === "string" ? details.name : undefined);
+			return notificationComponent(theme, customMessageText(message.content), expanded, agentName);
+		});
 	}
 
 	// A hand-back the model already read through task_output (block: true on the
@@ -1010,7 +1196,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	// so the message and its pointer would only repeat it (see decisions).
 	const notifier = createTaskNotifier(pi, { withdrawOnDelivery: true });
 	/** Every subagent notification; silent during shutdown (a teardown kill is not news). */
-	const notify: typeof notifier = (customType, text, details) => {
+	const notify = (customType: string, text: string, details?: Record<string, unknown>) => {
 		if (shuttingDown) return;
 		notifier(customType, text, details);
 	};
@@ -1066,15 +1252,17 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		record.sessionSearchDir ? join(record.sessionSearchDir, "output.log") : undefined;
 
 	/**
-	 * Claude Code's two-message hand-back for a resident agent's finished turn
-	 * (its first report, an update, a reply): the report goes out as an
-	 * `<agent-message>` from the agent — the preamble, every line indented, auto
-	 * mode's review flag above it — and the agent's own `<task-notification>`
-	 * follows, its `<result>` a pointer at that message, never the report again.
-	 * A turn that failed or was stopped delivered no report, so it is one
-	 * notification with the output (and any flag) inline in `<result>`. Both go
-	 * through the same notifier, in this order, so a coalesced round keeps the
-	 * report ahead of the pointer.
+	 * The hand-back for a resident agent's finished turn (its first report, an
+	 * update, a reply). Claude Code 2.1.283 sends one `<task-notification>` with
+	 * the report inline in `<result>` for a fork in every mode and for every agent
+	 * outside auto mode (findings §40). In auto mode a non-fork agent keeps the
+	 * two-message form: the report goes out as an `<agent-message>` from the
+	 * agent — the preamble, every line indented, auto mode's review flag above it
+	 * — and the agent's own `<task-notification>` follows, its `<result>` a
+	 * pointer at that message, never the report again. A turn that failed or was
+	 * stopped delivered no report, so it is always one notification with the
+	 * output (and any flag) inline. Both go through the same notifier, in this
+	 * order, so a coalesced round keeps the report ahead of the pointer.
 	 */
 	const notifyHandBack = (opts: {
 		/** The agent's persistent id: `from=` on the message, the SendMessage address. */
@@ -1097,6 +1285,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	}) => {
 		const status: TaskStatus = opts.stopped ? "killed" : opts.outcome.failed ? "failed" : "completed";
 		const warning = opts.review ? handBackWarning(opts.review) : undefined;
+		const record = registry.resolve(opts.from);
 		const details = { ...opts.details, taskId: opts.taskId, name: opts.name, failed: status === "failed", reviewed: opts.review !== undefined };
 		const envelope = (result: string) =>
 			taskNotification({
@@ -1105,12 +1294,12 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				toolUseId: opts.toolUseId,
 				outputFile: opts.outputFile,
 				status,
-				summary: agentSummary(opts.name, status),
+				summary: agentSummary(record?.description ?? opts.name, status),
 				note: AGENT_NOTE,
 				result,
 				usage: { subagentTokens: opts.outcome.usage.total, toolUses: opts.outcome.toolCalls, durationMs: Date.now() - opts.startedAt },
 			});
-		if (status !== "completed") {
+		if (status !== "completed" || record?.agent === FORK_AGENT || permissionMode !== "auto") {
 			notify("subagent-result", envelope(withReview(opts.report, warning)), details);
 			return;
 		}
@@ -1120,6 +1309,68 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		notify("subagent-result", envelope(handBackPointer(opts.from, opts.review !== undefined)), details);
 	};
 
+	/**
+	 * The prompt a fork inherits: the one this session's next request carries.
+	 * pi's `getSystemPrompt()` is its own stock prompt between turns, before the
+	 * first prompt and in a turn opened from idle, so it is only the fallback
+	 * for a prompt pi builds itself (a named agent's).
+	 */
+	const forkSystemPrompt = (ctx: ExtensionContext): string => requestSystemPrompt(pi.events, ctx) ?? ctx.getSystemPrompt();
+
+	/**
+	 * The parent's last provider request (the compaction extension publishes
+	 * each one). A fork's requests are built from it so the fork reads the
+	 * parent's prompt cache (fork-cache.ts; decisions/caching.md). None before
+	 * the first request, or for another model: that fork has no cache to read.
+	 */
+	let lastRequest: RequestCapture | undefined;
+	pi.events.on(LAST_REQUEST_CHANNEL, (data) => {
+		lastRequest = data as RequestCapture | undefined;
+	});
+	const forkRequest = (ctx: ExtensionContext): RequestCapture | undefined =>
+		lastRequest?.covers && captureMatches(lastRequest, ctx.model as { api?: string; provider?: string; id?: string } | undefined) ? lastRequest : undefined;
+
+	/**
+	 * The capture is persisted too, so a resumed fork still reads the cache its
+	 * earlier turns wrote. One file per distinct capture (a fan-out of forks
+	 * shares one), named by its hash, beside the fork session directories.
+	 */
+	const FORK_REQUEST_FILE = "parent-request";
+	const forkRequestsDir = (sessionSearchDir: string) => join(dirname(sessionSearchDir), "parent-requests");
+	/** Each capture is serialized and hashed once, however many forks share it. */
+	const persistedCaptures = new WeakMap<RequestCapture, string>();
+	const persistForkRequest = (record: AgentRunRecord, capture: RequestCapture) => {
+		if (!record.sessionSearchDir) return;
+		try {
+			const dir = forkRequestsDir(record.sessionSearchDir);
+			let name = persistedCaptures.get(capture);
+			if (!name || !existsSync(join(dir, name))) {
+				const body = JSON.stringify(capture);
+				name = `${createHash("sha256").update(body).digest("hex").slice(0, 24)}.json`;
+				mkdirSync(dir, { recursive: true });
+				if (!existsSync(join(dir, name))) {
+					// Atomic: a partial file would be skipped as present by every later fork.
+					const temp = join(dir, `${name}.${process.pid}.tmp`);
+					writeFileSync(temp, body);
+					renameSync(temp, join(dir, name));
+				}
+				persistedCaptures.set(capture, name);
+			}
+			writeFileSync(join(record.sessionSearchDir, FORK_REQUEST_FILE), name);
+		} catch {
+			// The run still reads the cache; only a later resume re-reads uncached.
+		}
+	};
+	const readForkRequest = (record: AgentRunRecord): RequestCapture | undefined => {
+		if (!record.sessionSearchDir) return undefined;
+		try {
+			const name = readFileSync(join(record.sessionSearchDir, FORK_REQUEST_FILE), "utf-8").trim();
+			return JSON.parse(readFileSync(join(forkRequestsDir(record.sessionSearchDir), name), "utf-8")) as RequestCapture;
+		} catch {
+			return undefined;
+		}
+	};
+
 	/** A fork's system prompt is persisted beside its session so a later resume can restore it (review S6). */
 	const FORK_PROMPT_FILE = "system-prompt.md";
 	const persistForkPrompt = (record: AgentRunRecord, prompt: string) => {
@@ -1130,6 +1381,19 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			// The run still works; only a later resume loses the prompt (and says so).
 		}
 	};
+	/**
+	 * A fork's inputs from this conversation (its system prompt and the parent's
+	 * last request, for the cache), saved beside its session so a SendMessage
+	 * can resume it later. Undefined for a named agent.
+	 */
+	const forkInputs = (request: RunRequest, record: AgentRunRecord, ctx: ExtensionContext) => {
+		if (!request.fork) return { parentSystemPrompt: undefined, parentRequest: undefined };
+		const parentSystemPrompt = forkSystemPrompt(ctx);
+		persistForkPrompt(record, parentSystemPrompt);
+		const parentRequest = forkRequest(ctx);
+		if (parentRequest) persistForkRequest(record, parentRequest);
+		return { parentSystemPrompt, parentRequest };
+	};
 	const readForkPrompt = (record: AgentRunRecord): string | undefined => {
 		if (!record.sessionSearchDir) return undefined;
 		try {
@@ -1206,15 +1470,17 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			// matched case-insensitively — a nested subagent is just as likely to be
 			// CC-trained.
 			parameters: Type.Object({
-				subagent_type: Type.String({ description: "An agent name from the list in this tool's description" }),
-				task: Type.Optional(Type.String({ description: "The task — a complete, self-contained instruction" })),
+				subagent_type: Type.Optional(Type.String({ description: "An agent name from the list in this tool's description (default: general-purpose)" })),
+				task: Type.String({ description: "The task — a complete, self-contained instruction" }),
 				prompt: Type.Optional(Type.String({ description: "Alias of `task` (Claude Code's name for it)." })),
 				description: Type.Optional(Type.String({ description: "A short (3-5 word) description of the task." })),
 				name: Type.Optional(Type.String({ description: "Name for this run (default: <agent>-<n>)" })),
 			}) as never,
+			prepareArguments: prepareAgentArguments as never,
 			async execute(_toolCallId: string, params: unknown, signal?: AbortSignal) {
 				const ctx = lastCtx;
-				const p = (params ?? {}) as { subagent_type?: unknown; task?: unknown; prompt?: unknown; name?: unknown };
+				const p = (params ?? {}) as { subagent_type?: unknown; task?: unknown; prompt?: unknown; name?: unknown; description?: unknown };
+				const description = typeof p.description === "string" && p.description.trim() ? p.description.trim() : undefined;
 				const agentName = typeof p.subagent_type === "string" ? p.subagent_type : "";
 				const taskInput = typeof p.task === "string" ? p.task : typeof p.prompt === "string" ? p.prompt : "";
 				const task = taskInput.trim();
@@ -1257,8 +1523,10 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					model: resolved,
 					thinking: undefined,
 					depth: parentDepth + 1,
+					...(description ? { description } : {}),
 				};
 				registry.add(record); // SendMessage from main can reach the nested run too
+				parentTaskOf.set(taskId, parentRecord.taskId);
 
 				// The main conversation's Agent calls are classified as delegations
 				// (matcher DELEGATION_TOOLS); a child's nested spawn must be judged the
@@ -1269,7 +1537,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				try {
 					const bridge = getPermissionBridge();
 					const verdict = bridge
-						? await bridge({ toolName: "Agent", input: { subagent_type: agentDef.name, prompt: task, description: name }, cwd: parentRecord.cwd, signal })
+						? await bridge({ toolName: "Agent", input: { subagent_type: agentDef.name, prompt: task, description: name }, cwd: parentRecord.cwd, signal, parentToolCallId: mainCallOf(parentRecord.taskId) })
 						: { block: true as const, reason: "no permission bridge is available to judge the delegation" };
 					if (verdict?.block) {
 						return {
@@ -1292,6 +1560,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 							agent: agentDef.name,
 							task,
 							name,
+							description,
 							model: resolved,
 							fallbackModel: spawnFallbackModel(resolved, resolution.source, ctx.model),
 						},
@@ -1308,7 +1577,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					content: [
 						{
 							type: "text" as const,
-							text: `${notes.length ? `${notes.join("\n")}\n\n` : ""}${result.output}\n\n(${formatStats(result.toolCalls, result.usage)})`,
+							text: `${notes.length ? `${notes.join("\n")}\n\n` : ""}${bounded(result.output, `${record.taskId}-report`, OUTPUT_CAP)}\n\n(${formatStats(result.toolCalls, result.usage)})`,
 						},
 					],
 					details: { agentRuns: [record] },
@@ -1321,13 +1590,29 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	 * The spawn tool a run is entitled to. THE one depth gate: it reads the
 	 * record's own depth (set once at creation), so every handout site —
 	 * fresh spawn, background resident, SendMessage resume — enforces
-	 * MAX_SPAWN_DEPTH identically. A resumed grandchild stays capped.
+	 * MAX_SPAWN_DEPTH identically. A resumed grandchild stays capped. Only a
+	 * `resident` run can receive a cron fire, so any other run's cron_create refuses.
 	 */
-	const spawnToolsFor = (record: AgentRunRecord): ToolDefinition[] => {
+	const spawnToolsFor = (record: AgentRunRecord, { resident = false } = {}): ToolDefinition[] => {
 		const depth = record.depth ?? 0;
-		return depth < MAX_SPAWN_DEPTH ? [childAgentTool(record, depth)] : [];
+		// The child's cron tools reach this session's store (lib/agent-cron.ts).
+		const cron = agentCronTools(pi.events, { agentId: record.taskId, cwd: record.cwd, resident }) as unknown as ToolDefinition[];
+		return depth < MAX_SPAWN_DEPTH ? [childAgentTool(record, depth), ...cron] : cron;
 	};
 
+	// A fired cron job of a subagent's: to that agent while it lives (Claude
+	// Code's task-notification delivery); otherwise the background extension drops it.
+	pi.events.on(AGENT_CRON_FIRE_CHANNEL, (data) => {
+		const fire = data as AgentCronFire;
+		const resident = residents.get(fire.agentId);
+		if (!resident || resident.handle.exited()) return;
+		fire.delivered = true;
+		// A send that fails after all ends the job, as a fire to an ended agent does.
+		void resident.handle.send(fire.prompt).catch(() => {
+			pi.events.emit(AGENT_CRON_CHANNEL, { op: "delete", agentId: fire.agentId, id: fire.jobId } satisfies AgentCronRequest);
+		});
+	});
+
 	/**
 	 * The text a child's first turn is prompted with: a fork gets the inherited-
 	 * context framing (plus, in a worktree, where its paths moved to); a named
@@ -1337,8 +1622,8 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		request.fork ? forkTaskMessage(request.task, worktree ? { worktreePath: worktree.path, parentCwd } : undefined) : request.task;
 
 	/** Create a run's isolation worktree and point its record at it (both spawn paths). */
-	const isolateInWorktree = async (ctx: ExtensionContext, record: AgentRunRecord, name: string): Promise<Worktree> => {
-		const worktree = await createWorktree(ctx.cwd, name);
+	const isolateInWorktree = async (base: string, record: AgentRunRecord, name: string): Promise<Worktree> => {
+		const worktree = await createWorktree(base, name);
 		record.cwd = worktree.path;
 		record.worktree = true;
 		return worktree;
@@ -1362,11 +1647,20 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		onProgress?: (toolCalls: number, text: string, usage: UsageTotals) => void,
 	): Promise<TaskResult> => {
 		const { request, record, agentDef } = prepared;
+		// The session's working directory: the entered worktree, if any.
+		const base = workCwd(ctx);
+
+		// Before anything marks the run as running: a failed build must not leave
+		// the task id in runningIds, where SendMessage would call it "still running".
+		const runtime = await runtimeOrError(ctx);
+		if (typeof runtime === "string") {
+			return { agent: request.agent, name: request.name, taskId: record.taskId, task: request.task, output: `Subagent failed: ${runtime}`, toolCalls: 0, usage: emptyUsage(), failed: true };
+		}
 
 		let worktree: Worktree | undefined;
 		if (request.worktree) {
 			try {
-				worktree = await isolateInWorktree(ctx, record, request.name);
+				worktree = await isolateInWorktree(base, record, request.name);
 			} catch (error) {
 				return {
 					agent: request.agent,
@@ -1383,14 +1677,15 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
 		runningIds.add(record.taskId);
 		const live = trackLiveRun(record, request, parent);
-		const runtime = await getRuntime(ctx);
+		const { parentSystemPrompt: forkPrompt, parentRequest } = forkInputs(request, record, ctx);
 		const handle = runtime.run({
 			name: request.name,
 			agent: agentDef,
-			task: frameTask(request, worktree, ctx.cwd),
+			task: frameTask(request, worktree, base),
 			cwd: record.cwd,
 			forkFrom: request.fork ? forkFrom : undefined,
-			parentSystemPrompt: request.fork ? ctx.getSystemPrompt() : undefined,
+			parentSystemPrompt: forkPrompt,
+			parentRequest,
 			sessionDir: record.sessionSearchDir || undefined,
 			model: request.model,
 			fallbackModel: request.fallbackModel,
@@ -1404,6 +1699,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			onMessageToMain: (message, summary) =>
 				parent ? relayToParent(parent.taskId, record.taskId, request.name, message, summary) : notifyAgentMessage(record.taskId, request.name, message),
 			extraTools: spawnToolsFor(record),
+			mainToolCallId: () => mainCallOf(record.taskId),
 		});
 		liveHandles.set(record.taskId, handle);
 
@@ -1413,7 +1709,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			live.finish(Boolean(outcome.failed));
 			let worktreeKept: boolean | undefined;
 			if (worktree) {
-				worktreeKept = !(await cleanupWorktree(ctx.cwd, worktree));
+				worktreeKept = !(await cleanupWorktree(base, worktree));
 			}
 			return {
 				agent: request.agent,
@@ -1422,11 +1718,14 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				task: request.task,
 				...outcome,
 				worktreePath: worktreeKept ? worktree?.path : undefined,
+				worktreeBranch: worktreeKept ? worktree?.branch : undefined,
 				worktreeKept,
 			};
 		} catch (error) {
 			live.finish(true);
-			if (worktree) await cleanupWorktree(ctx.cwd, worktree);
+			// A failed run can still have committed or edited in its worktree:
+			// a kept one is reported like a finished run's.
+			const worktreeKept = worktree ? !(await cleanupWorktree(base, worktree)) : undefined;
 			return {
 				agent: request.agent,
 				name: request.name,
@@ -1436,40 +1735,321 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				toolCalls: 0,
 				usage: emptyUsage(),
 				failed: true,
+				worktreePath: worktreeKept ? worktree?.path : undefined,
+				worktreeBranch: worktreeKept ? worktree?.branch : undefined,
+				worktreeKept,
 			};
 		} finally {
 			runningIds.delete(record.taskId);
 		}
 	};
 
-	pi.registerTool({
+	/**
+	 * Launch one prepared run as a background resident (Claude Code parity):
+	 * it returns as soon as the child starts, the report arrives as a steered
+	 * task notification, and the child stays resident so SendMessage can reach
+	 * it live (steer mid-turn, prompt when idle). `sessionFile` is the parent
+	 * transcript a fork clones; `toolCallId` links the notifications to the
+	 * spawning Agent call (none for a `/btw` fork); `forkMessages` are appended
+	 * to a fork's transcript. Returns the line reported for the run.
+	 */
+	const launchResident = async (
+		p: PreparedRun,
+		ctx: ExtensionContext,
+		runtime: SubagentRuntime,
+		{ sessionFile, toolCallId, forkMessages }: { sessionFile?: string; toolCallId?: string; forkMessages?: Message[] },
+	): Promise<{ launched: boolean; line: string }> => {
+		const ended = () => {
+			registry.remove(p.record.taskId);
+			return { launched: false, line: `✗ ${p.record.name}: the session ended before the agent started.` };
+		};
+		if (shuttingDown) return ended();
+		if (toolCallId) mainCallFor.set(p.record.taskId, toolCallId);
+		// Captured as a string: onExit runs from a `.finally` long after this
+		// turn's ctx may be stale (review S5). The entered worktree, if any.
+		const parentCwd = workCwd(ctx);
+		let worktree: Worktree | undefined;
+		if (p.request.worktree) {
+			try {
+				worktree = await isolateInWorktree(parentCwd, p.record, p.request.name);
+			} catch (error) {
+				return { launched: false, line: `✗ ${p.record.name}: could not create a worktree: ${(error as Error).message}` };
+			}
+			// Shutdown can begin while git creates the worktree: build no child
+			// after its sweep, and remove the worktree within its grace.
+			if (shuttingDown) {
+				await cleanupWorktree(parentCwd, worktree);
+				return ended();
+			}
+		}
+
+		const logPath = outputLogPath(p.record);
+		let lastLogWrite = 0;
+		let finish!: () => void;
+		const finished = new Promise<void>((resolve) => {
+			finish = resolve;
+		});
+
+		// The child's final output. task.output() falls back to this
+		// because handle.snapshot().text can be blank at a turn boundary —
+		// the same reason the log write below uses `|| outcome.output`.
+		// Keeps task_output consistent with the log and the completion
+		// notification rather than showing an empty body in that case.
+		let lastOutput = "";
+		// The initial task's own report. task_output for THIS task must return the
+		// first turn's reply — not the resident's growing multi-turn transcript —
+		// the same way a SendMessage task returns one reply (review S12).
+		let firstTurnOutput: string | undefined;
+		const live = trackLiveRun(p.record, p.request);
+		const resident: Resident = { handle: undefined as never, startedAt: Date.now(), turnHandlers: [], reviewing: 0 };
+		const worktreeNote = worktree
+			? `\n\n(Running in worktree ${worktree.path} on branch ${worktree.branch} — kept while the agent stays resident, and after it exits if it holds uncommitted changes or commits.)`
+			: "";
+		resident.turnHandlers.push((outcome, review, stopped) => {
+			task.status = stopped ? "stopped" : outcome.failed ? "failed" : "completed";
+			task.finishedAt = Date.now();
+			firstTurnOutput = outcome.output;
+			finish();
+			notifyHandBack({
+				from: p.record.taskId,
+				taskId: p.record.taskId,
+				name: p.record.name,
+				toolUseId: toolCallId,
+				outputFile: logPath,
+				outcome,
+				stopped,
+				startedAt: task.startedAt,
+				report: `${bounded(outcome.output, `${p.record.taskId}-report`, OUTPUT_CAP)}${worktreeNote}`,
+				review,
+			});
+		});
+
+		// Idle reaper: every run is a resident now, so without this a long
+		// session accumulates one live AgentSession (extension instances,
+		// message array, MCP tool refs) per delegation for its whole life.
+		// After RESIDENT_IDLE_MS idle the session is released quietly; the
+		// agent stays reachable — SendMessage resumes it from its session
+		// file. Worktree residents are exempt: release would remove the
+		// worktree a resume still needs. So is one that owns a cron job, which
+		// fires only to a live agent (lib/agent-cron.ts). Armed from every turn end.
+		let reaper: ReturnType<typeof setTimeout> | undefined;
+		const armReaper = () => {
+			if (worktree) return;
+			if (reaper) clearTimeout(reaper);
+			reaper = setTimeout(() => {
+				reaper = undefined;
+				if (handle.exited()) return;
+				if (handle.busy() || agentOwnsCronJobs(pi.events, p.record.taskId)) {
+					armReaper();
+					return;
+				}
+				handle.release();
+			}, RESIDENT_IDLE_MS);
+			reaper.unref?.();
+		};
+		const { parentSystemPrompt: forkPrompt, parentRequest } = forkInputs(p.request, p.record, ctx);
+		// No `signal` here on purpose: a resident outlives the spawning turn and
+		// is stopped through task_stop / the panel, not by the turn ending (S15).
+		const started = await runtime.runResident({
+			name: p.record.name,
+			agent: p.agentDef,
+			cwd: p.record.cwd,
+			forkFrom: p.request.fork ? sessionFile : undefined,
+			forkMessages: p.request.fork ? forkMessages : undefined,
+			parentSystemPrompt: forkPrompt,
+			parentRequest,
+			sessionDir: p.record.sessionSearchDir || undefined,
+			model: p.request.model,
+			fallbackModel: p.request.fallbackModel,
+			thinking: p.request.thinking,
+			onProgress: (toolCalls, text, usage) => {
+				live.progress(toolCalls, usage);
+				// Throttled: onProgress fires per tool call/message with the whole
+				// turn text so far, and this path now carries EVERY run — an
+				// unthrottled sync rewrite would be O(n²) bytes on the hot path.
+				// onTurnEnd below flushes the final state, so the tail is never lost.
+				if (logPath && text && Date.now() - lastLogWrite > LOG_WRITE_INTERVAL_MS) {
+					lastLogWrite = Date.now();
+					writeFileSync(logPath, text);
+				}
+			},
+			sink: live.sink,
+			onMessageToMain: (message) => notifyAgentMessage(p.record.taskId, p.record.name, message),
+			extraTools: spawnToolsFor(p.record, { resident: true }),
+			mainToolCallId: () => mainCallOf(p.record.taskId),
+			onTurnEnd: (outcome) => {
+				registry.sessionFileFor(p.record);
+				live.settle();
+				lastOutput = resident.handle.snapshot().text || outcome.output;
+				if (logPath) writeFileSync(logPath, lastOutput);
+				// The handler is claimed now (so a message arriving mid-review pairs
+				// with the NEXT turn), but runs only once auto mode's hand-back
+				// review of this turn's action sequence has answered, so the
+				// verdict rides in the same notification as the report instead of
+				// trailing it. The wait is bounded (hand-back-review.ts) and
+				// answered synchronously when auto mode is off.
+				const handler = resident.turnHandlers.shift();
+				// A stop or resume during review must not change this turn's outcome.
+				const stopped = stoppedTaskIds.has(p.record.taskId);
+				armReaper();
+				resident.reviewing++;
+				void awaitHandBackReview(pi.events, p.record, outcome.actions, undefined, mainCallOf(p.record.taskId)).then((review) => {
+					resident.reviewing--;
+					if (handler) {
+						handler(outcome, review, stopped);
+					} else {
+						// A turn nobody is waiting on (e.g. a steer that raced past its
+						// target turn and ran on its own) must still surface.
+						// Only the launch's notification names its tool call; a later
+						// turn's notifies without one, as Claude Code's do (findings §40).
+						notifyHandBack({
+							from: p.record.taskId,
+							taskId: p.record.taskId,
+							name: p.record.name,
+							outputFile: logPath,
+							outcome,
+							stopped,
+							startedAt: resident.startedAt,
+							report: bounded(outcome.output, `${p.record.taskId}-update-${Date.now()}`, OUTPUT_CAP),
+							review,
+							details: { update: true },
+						});
+					}
+				});
+			},
+			onExit: () => {
+				if (reaper) clearTimeout(reaper);
+				live.finish(stoppedTaskIds.has(p.record.taskId) ? "stopped" : false);
+				if (residents.get(p.record.taskId) === resident) residents.delete(p.record.taskId);
+				liveHandles.delete(p.record.taskId);
+				// Returned, not voided: kill() settles after the cleanup, so the
+				// session_shutdown grace covers it.
+				if (worktree) return cleanupWorktree(parentCwd, worktree);
+				return undefined;
+			},
+		}).catch((error: unknown) => (error instanceof Error ? error : new Error(String(error))));
+		if (started instanceof Error) {
+			// The child never started: settle its panel row and forget the run, so
+			// neither the panel nor list_agents offers it.
+			live.finish(true);
+			registry.remove(p.record.taskId);
+			if (worktree) void cleanupWorktree(parentCwd, worktree);
+			return { launched: false, line: `✗ ${p.record.name}: could not start: ${started.message}` };
+		}
+		const handle = started;
+		resident.handle = handle;
+		// Construction can finish after shutdown's stop-all sweep. The handle
+		// was not registered then, so dispose it before sending any task now.
+		if (shuttingDown) {
+			await handle.kill();
+			return ended();
+		}
+		residents.set(p.record.taskId, resident);
+		liveHandles.set(p.record.taskId, handle);
+
+		const task: BackgroundTask = {
+			id: p.record.taskId,
+			kind: "subagent",
+			ownUI: true, // rendered live by the subagents panel's agent strip
+			description: `${p.record.name}: ${p.request.task.slice(0, 80)}`,
+			status: "running",
+			startedAt: Date.now(),
+			logPath,
+			output: () => firstTurnOutput ?? (handle.snapshot().text || lastOutput),
+			stop: () => stopAgent(p.record.taskId, handle),
+			resident: () => !handle.exited(),
+			finished,
+		};
+		pi.events.emit(TASK_REGISTER_CHANNEL, task);
+		void handle.send(frameTask(p.request, worktree, parentCwd));
+
+		return {
+			launched: true,
+			line: `⏳ ${p.record.name} (task ${p.record.taskId}) running in background${logPath ? ` — interim output readable at ${logPath}` : ""}`,
+		};
+	};
+
+	/**
+	 * `/btw`'s `f to fork` (lib/btw-fork.ts): a background fork that inherits
+	 * the conversation (if the session has one yet), then the side question and
+	 * its answer, and takes the question as its task. It reports back like any
+	 * spawned fork.
+	 */
+	const forkFromBtw = async (request: BtwForkRequest): Promise<BtwForkResult> => {
+		const ctx = request.ctx as ExtensionContext;
+		// Before the first turn the file is not written yet and the fork starts from
+		// the side exchange alone, as Claude Code's does (newChildSessionManager).
+		// Without a session file at all the conversation cannot be cloned, and a
+		// fork framed as inheriting it would confabulate (the Agent tool refuses too).
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		if (!sessionFile) return { error: "Cannot fork: this session is not persisted (started with --no-session), so there is no conversation to clone." };
+		// Named from the question, as Claude Code names a /btw fork.
+		const name = freeRunName(registry.names(), btwForkName(request.question));
+		const taskId = btwForkTaskId(name);
+		// The session's current model and thinking, explicitly: before the first
+		// turn there is no transcript for the fork to restore them from.
+		const prepared: PreparedRun = {
+			request: {
+				agent: FORK_AGENT,
+				task: request.question,
+				name,
+				description: btwForkDescription(request.question),
+				fork: true,
+				model: ctx.model ? modelSpec(ctx.model) : undefined,
+				thinking: pi.getThinkingLevel(),
+			},
+			agentDef: undefined,
+			record: {
+				name,
+				agent: FORK_AGENT,
+				taskId,
+				sessionSearchDir: runSessionDir(ctx, taskId) ?? "",
+				cwd: workCwd(ctx),
+				depth: 0,
+				description: btwForkDescription(request.question),
+			},
+		};
+		registry.add(prepared.record);
+		// The session can be torn down while the runtime or the child starts; a
+		// fork launched after shutdown's stop-all sweep would outlive it.
+		const runtime = await runtimeOrError(ctx);
+		if (typeof runtime === "string") {
+			registry.remove(taskId);
+			return { error: `Cannot fork: ${runtime}` };
+		}
+		if (shuttingDown) return { error: "The session ended before the fork started." };
+		const { launched, line } = await launchResident(prepared, ctx, runtime, { sessionFile, forkMessages: request.messages });
+		if (shuttingDown) {
+			void stopAgent(taskId);
+			return { error: "The session ended before the fork started." };
+		}
+		if (!launched) return { error: line };
+		for (const text of btwForkRecord(name, taskId, request.question)) {
+			pi.events.emit(REMINDER_CHANNEL, { text, placement: "user-prepend", raw: true } satisfies ReminderPayload);
+		}
+		return { name, taskId };
+	};
+	pi.events.on(BTW_FORK_CHANNEL, (data) => {
+		const request = data as BtwForkRequest;
+		request.handled = true;
+		void forkFromBtw(request).then(request.respond, (error: unknown) =>
+			request.respond({ error: `Failed to fork: ${error instanceof Error ? error.message : String(error)}` }),
+		);
+	});
+
+	// Claude Code's Agent text, short or long by the model's tier
+	// (agent-description.ts, lib/tool-variants.ts); registered again when the
+	// form changes.
+	const agentTool = defineTool({
 		name: "Agent",
 		label: "Agent",
 		...ccToolRenderers<{ subagent_type?: string; task?: string; prompt?: string; description?: string; action?: string }>("Agent", {
 			title: (a) => (a ? [a.subagent_type, a.description ?? a.task ?? a.prompt ?? a.action].filter(Boolean).join(": ") || undefined : undefined),
 		}),
-		description:
-			'Delegate a task to a specialist agent that runs in its own context window and reports back. The available agents are listed in the "Available agents" system reminder.\n' +
-			"\n" +
-			"## When to use\n" +
-			"- Broad codebase searches or exploration where you need the conclusion, not the file dumps.\n" +
-			"- Self-contained research, reviews, or verification whose intermediate output you won't need again.\n" +
-			"- Independent questions that can run at once — issue multiple Agent tool calls in one message to run them in parallel.\n" +
-			"\n" +
-			"For a single-fact lookup you already know how to run, search directly instead. Once you've delegated work, don't also run it yourself — wait for the result.\n" +
-			"\n" +
-			"## How agents run\n" +
-			"Agents run in the background: the call returns immediately with a task id, and you'll be notified when one completes — the agent's report arrives as a task notification while you keep working, or on its own if you are idle. Never fabricate or predict a pending agent's results — the notification is never something you write yourself; if the user asks before it arrives, say it's still running. Call task_output only if your next step cannot proceed without the result (block=true waits); stop a run with task_stop. Both are deferred — load them with tool_search first. (Exception: in a one-shot print session the call blocks and returns the report directly — no notification follows.)\n" +
-			"\n" +
-			"## Usage notes\n" +
-			"- Give a complete, self-contained task: the agent cannot ask follow-up questions.\n" +
-			"- If an agent's description says it should be used proactively, try your best to use it without the user having to ask first.\n" +
-			'- `subagent_type: "fork"` clones this conversation instead of starting fresh; a fork always runs on this conversation\'s model and reasoning settings. If you are the fork, execute your assigned task directly — don\'t re-delegate.\n' +
-			'- `isolation: "worktree"` gives the agent its own git worktree when it will edit files.\n' +
-			"- Each run gets a name — SendMessage reaches it live while it runs and continues it after it finishes. `action: \"list\"` re-prints the agent catalog.\n" +
-			"- The agent's final report is not shown to the user, so relay what matters.",
+		description: agentDescription("short", projectConfigDirName()),
 		promptSnippet: "Delegate scoped work to a specialist agent in its own context",
 		parameters: SubagentParams,
+		prepareArguments: prepareAgentArguments as (args: unknown) => Static<typeof SubagentParams>,
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const agents = loadAgents(ctx.cwd);
 
@@ -1479,11 +2059,10 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			const taskText = params.task ?? params.prompt;
 
 			// A call carrying run options (a task, a name, a model/thinking/isolation
-			// override, or action:"run") but no `subagent_type` is a run that forgot
-			// to name its agent. Fail loudly with a diagnostic rather than silently
-			// returning the catalog: a weaker model reads the catalog as a
-			// non-sequitur and invents wrong reasons for it, instead of learning it
-			// omitted `subagent_type`.
+			// override, or action:"run") is a run; prepareAgentArguments gave one that
+			// named no agent general-purpose, as Claude Code does (a tiny model
+			// repeated such a call 30 times against an error naming the fix, battery
+			// round 7). A call with neither lists the catalog.
 			const wantsRun =
 				params.action === "run" ||
 				taskText != null ||
@@ -1499,19 +2078,6 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				};
 			}
 
-			if (!params.subagent_type) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `No \`subagent_type\` given, but you passed run options — this looks like a run that forgot to name its agent. Set \`subagent_type\` to one of the names below (or "fork" to clone this conversation). To only browse the catalog, call with action:"list".\n\nAvailable agents:\n${describeAgents(ctx.cwd)}`,
-						},
-					],
-					details: {},
-					isError: true,
-				};
-			}
-
 			// A run needs a task. A CC-shaped call that put its instruction in an
 			// unrecognized key, or none at all, must fail loud rather than start a
 			// child prompted with "" (H1). Fork included — cloning to do nothing is
@@ -1544,6 +2110,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					agent: entry.agent,
 					task: entry.task,
 					name,
+					description: params.description?.trim() || undefined,
 					fork: entry.agent === FORK_AGENT,
 					model: params.model,
 					thinking: params.thinking,
@@ -1551,86 +2118,8 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				};
 			});
 
-			// A fork continues this conversation; running it on a different model or
-			// reasoning effort is how the fork-confabulation incident happened (a
-			// minimal-thinking fork resumed the inherited topic instead of its task).
-			// Claude Code silently ignores `model` for forks; we fail loud instead.
-			if (requested.some((r) => r.fork) && (params.model || params.thinking)) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: '`model`/`thinking` overrides are not applied to fork runs — a fork continues this conversation and keeps its exact model and reasoning settings. Drop the override, or use a named agent (e.g. "general-purpose") to run the task with different settings.',
-						},
-					],
-					details: {},
-					isError: true,
-				};
-			}
-
 			const sessionFile = ctx.sessionManager.getSessionFile();
-			if (requested.some((r) => r.fork) && !sessionFile) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "Cannot fork: this session is not persisted (started with --no-session), so there is no transcript to clone. Use a named agent instead.",
-						},
-					],
-					details: {},
-					isError: true,
-				};
-			}
-
-			const unknown = requested.filter((r) => !r.fork && !agents.some((a) => a.name === r.agent));
-			if (unknown.length > 0) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Unknown agent(s): ${unknown.map((u) => u.agent).join(", ")}\n\nAvailable agents:\n${describeAgents(ctx.cwd)}`,
-						},
-					],
-					details: {},
-					isError: true,
-				};
-			}
-
-			if (requested.some((r) => r.worktree) && !(await isGitRepo(ctx.cwd))) {
-				return {
-					content: [{ type: "text", text: 'isolation: "worktree" needs a git repository; this directory is not one.' }],
-					details: {},
-					isError: true,
-				};
-			}
-
-			const prepared: PreparedRun[] = requested.map((request) => {
-				const taskId = generateTaskId();
-				return {
-					request,
-					agentDef: request.fork ? undefined : agents.find((a) => a.name === request.agent),
-					record: {
-						name: request.name,
-						agent: request.agent,
-						taskId,
-						sessionSearchDir: runSessionDir(ctx, taskId) ?? "",
-						cwd: ctx.cwd,
-						model: request.model,
-						thinking: request.thinking,
-						depth: 0,
-					},
-				};
-			});
-
-			/**
-			 * Model resolution happens here, in the parent, against the real
-			 * registry — never in the child, whose `--model` fuzzy-matches across
-			 * every configured provider. The child is spawned with a concrete
-			 * `provider/id`; anything surprising (a fallback, a provider crossing)
-			 * is said out loud rather than happening silently.
-			 */
-			const available = usableModels(ctx);
-			const configuredDefault = applicableSubagentDefault(loadSubagentDefault(os.homedir()), ctx.model);
+			let prepared: PreparedRun[] = [];
 			/**
 			 * What the model is told about its own model choice: the same sentences
 			 * the user gets, plus the model each child actually runs on. Deduped —
@@ -1638,99 +2127,187 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			 * once. See `subagentModelNotes` for why the model needs this.
 			 */
 			const modelNotes = new Set<string>();
-			for (const p of prepared) {
-				// A fork inherits the parent transcript, so it must continue on THIS
-				// conversation's exact model — never a configured default or the
-				// automatic same-provider pick, which would move the inherited context
-				// onto a different (often weaker) model. Leaving model undefined makes
-				// the forked session restore its own model. (Per-call `model` on a fork
-				// is already rejected above.)
-				if (p.request.fork) continue;
-				// No per-call or agent-frontmatter override → the automatic default,
-				// which is stable for the session, so reuse the cached resolution
-				// instead of re-ranking the catalog per spawn. An override varies per
-				// call and always resolves fresh.
-				const resolution =
-					p.request.model || p.agentDef?.model
-						? resolveSubagentModel({
-								requested: p.request.model,
-								agentModel: p.agentDef?.model,
-								configuredDefault: configuredDefault,
-								sessionModel: ctx.model,
-								available,
-								requireImageInput: supportsImageInput(ctx.model),
-							})
-						: resolveAutoDefault(ctx.model, available, configuredDefault);
-				if (resolution.unresolved) {
-					// The main model chose this string; the menu lets it retry.
-					const fallback = resolveSubagentModel({
-						configuredDefault: configuredDefault,
-						sessionModel: ctx.model,
-						available,
-						requireImageInput: supportsImageInput(ctx.model),
-					});
+			// Every check before the records land: a rejection, or a throw on the way,
+			// frees the spawn's names for the retry.
+			let landed = false;
+			try {
+				// A fork continues this conversation; running it on a different model or
+				// reasoning effort is how the fork-confabulation incident happened (a
+				// minimal-thinking fork resumed the inherited topic instead of its task).
+				// Claude Code silently ignores `model` for forks; we fail loud instead.
+				if (requested.some((r) => r.fork) && (params.model || params.thinking)) {
 					return {
 						content: [
 							{
 								type: "text",
-								text:
-									`${resolution.unresolvedReason ?? `Unknown model "${resolution.unresolved}" — no available model matches it.`}\n\n` +
-									subagentModelsReminder({
-										available,
-										sessionModel: ctx.model,
-										defaultModel: fallback.model,
-										defaultSource: fallback.source,
-										requireImageInput: supportsImageInput(ctx.model),
-									}),
+								text: '`model`/`thinking` overrides are not applied to fork runs — a fork continues this conversation and keeps its exact model and reasoning settings. Drop the override, or use a named agent (e.g. "general-purpose") to run the task with different settings.',
 							},
 						],
 						details: {},
 						isError: true,
 					};
 				}
-				const gate = expensiveModelGate(resolution, ctx.model, params.allow_expensive);
-				if (gate) {
-					const fallback = resolveSubagentModel({
-						configuredDefault: configuredDefault,
-						sessionModel: ctx.model,
-						available,
-						requireImageInput: supportsImageInput(ctx.model),
-					});
+
+				if (requested.some((r) => r.fork) && !sessionFile) {
 					return {
 						content: [
 							{
 								type: "text",
-								text:
-									`${gate}\n` +
-									"If the user explicitly asked for this model, retry with allow_expensive: true; " +
-									"otherwise pick a cheaper model or omit the field.\n\n" +
-									subagentModelsReminder({
-										available,
-										sessionModel: ctx.model,
-										defaultModel: fallback.model,
-										defaultSource: fallback.source,
-										requireImageInput: supportsImageInput(ctx.model),
-									}),
+								text: "Cannot fork: this session is not persisted (started with --no-session), so there is no transcript to clone. Use a named agent instead.",
 							},
 						],
 						details: {},
 						isError: true,
 					};
 				}
-				for (const notice of resolution.notices) notifyModelOnce(ctx, notice);
-				for (const note of subagentModelNotes(resolution)) modelNotes.add(note);
-				const resolved = resolution.model ? modelSpec(resolution.model) : undefined;
-				p.request.model = resolved;
-				p.request.fallbackModel = spawnFallbackModel(resolved, resolution.source, ctx.model);
-				p.record.model = resolved;
-			}
 
-			for (const p of prepared) registry.add(p.record);
-			const records = prepared.map((p) => p.record);
+				const unknown = requested.filter((r) => !r.fork && !agents.some((a) => a.name === r.agent));
+				if (unknown.length > 0) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Unknown agent(s): ${unknown.map((u) => u.agent).join(", ")}\n\nAvailable agents:\n${describeAgents(ctx.cwd)}`,
+							},
+						],
+						details: {},
+						isError: true,
+					};
+				}
 
-			// One-shot modes (`-p` / `--mode json`) exit when the turn settles, so
-			// a background run would be orphaned with its report undelivered — run
-			// blocking there and return the report in the tool result instead.
+				if (requested.some((r) => r.worktree) && !(await isGitRepo(workCwd(ctx)))) {
+					return {
+						content: [{ type: "text", text: 'isolation: "worktree" needs a git repository; this directory is not one.' }],
+						details: {},
+						isError: true,
+					};
+				}
+
+				prepared = requested.map((request) => {
+					const taskId = generateTaskId();
+					return {
+						request,
+						agentDef: request.fork ? undefined : agents.find((a) => a.name === request.agent),
+						record: {
+							name: request.name,
+							agent: request.agent,
+							taskId,
+							sessionSearchDir: runSessionDir(ctx, taskId) ?? "",
+							cwd: workCwd(ctx),
+							model: request.model,
+							thinking: request.thinking,
+							depth: 0,
+							...(request.description ? { description: request.description } : {}),
+						},
+					};
+				});
+
+				/**
+				 * Model resolution happens here, in the parent, against the real
+				 * registry — never in the child, whose `--model` fuzzy-matches across
+				 * every configured provider. The child is spawned with a concrete
+				 * `provider/id`; anything surprising (a fallback, a provider crossing)
+				 * is said out loud rather than happening silently.
+				 */
+				const available = usableModels(ctx);
+				const configuredDefault = applicableSubagentDefault(loadSubagentDefault(os.homedir()), ctx.model);
+				for (const p of prepared) {
+					// A fork inherits the parent transcript, so it must continue on THIS
+					// conversation's exact model — never a configured default or the
+					// automatic same-provider pick, which would move the inherited context
+					// onto a different (often weaker) model. Leaving model undefined makes
+					// the forked session restore its own model. (Per-call `model` on a fork
+					// is already rejected above.)
+					if (p.request.fork) continue;
+					// No per-call or agent-frontmatter override → the automatic default,
+					// which is stable for the session, so reuse the cached resolution
+					// instead of re-ranking the catalog per spawn. An override varies per
+					// call and always resolves fresh.
+					const resolution =
+						p.request.model || p.agentDef?.model
+							? resolveSubagentModel({
+									requested: p.request.model,
+									agentModel: p.agentDef?.model,
+									configuredDefault: configuredDefault,
+									sessionModel: ctx.model,
+									available,
+									requireImageInput: supportsImageInput(ctx.model),
+								})
+							: resolveAutoDefault(ctx.model, available, configuredDefault);
+					if (resolution.unresolved) {
+						// The main model chose this string; the menu lets it retry.
+						const fallback = resolveSubagentModel({
+							configuredDefault: configuredDefault,
+							sessionModel: ctx.model,
+							available,
+							requireImageInput: supportsImageInput(ctx.model),
+						});
+						return {
+							content: [
+								{
+									type: "text",
+									text:
+										`${resolution.unresolvedReason ?? `Unknown model "${resolution.unresolved}" — no available model matches it.`}\n\n` +
+										subagentModelsReminder({
+											available,
+											sessionModel: ctx.model,
+											defaultModel: fallback.model,
+											defaultSource: fallback.source,
+											requireImageInput: supportsImageInput(ctx.model),
+										}),
+								},
+							],
+							details: {},
+							isError: true,
+						};
+					}
+					const gate = expensiveModelGate(resolution, ctx.model, params.allow_expensive);
+					if (gate) {
+						const fallback = resolveSubagentModel({
+							configuredDefault: configuredDefault,
+							sessionModel: ctx.model,
+							available,
+							requireImageInput: supportsImageInput(ctx.model),
+						});
+						return {
+							content: [
+								{
+									type: "text",
+									text:
+										`${gate}\n` +
+										"If the user explicitly asked for this model, retry with allow_expensive: true; " +
+										"otherwise pick a cheaper model or omit the field.\n\n" +
+										subagentModelsReminder({
+											available,
+											sessionModel: ctx.model,
+											defaultModel: fallback.model,
+											defaultSource: fallback.source,
+											requireImageInput: supportsImageInput(ctx.model),
+										}),
+								},
+							],
+							details: {},
+							isError: true,
+						};
+					}
+					for (const notice of resolution.notices) notifyModelOnce(ctx, notice);
+					for (const note of subagentModelNotes(resolution)) modelNotes.add(note);
+					const resolved = resolution.model ? modelSpec(resolution.model) : undefined;
+					p.request.model = resolved;
+					p.request.fallbackModel = spawnFallbackModel(resolved, resolution.source, ctx.model);
+					p.record.model = resolved;
+				}
+
+				for (const p of prepared) registry.add(p.record);
+				landed = true;
+			} finally {
+				if (!landed) for (const request of requested) registry.release(request.name);
+			}
+			const records = prepared.map((p) => p.record);
+
+			// One-shot modes (`-p` / `--mode json`) exit when the turn settles, so
+			// a background run would be orphaned with its report undelivered — run
+			// blocking there and return the report in the tool result instead.
 			if (!sessionOutlivesTurn(ctx.mode)) {
 				// Stream progress through onUpdate (tool_execution_update) like the
 				// old foreground path — a headless JSON/RPC consumer has no panel,
@@ -1742,6 +2319,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					onUpdate?.({ content: [{ type: "text", text: line }], details: {} });
 				};
 				report();
+				mainCallFor.set(prepared[0].record.taskId, toolCallId);
 				const result = await executeRun(prepared[0], ctx, signal, sessionFile ?? undefined, undefined, (toolCalls, text, usage) => {
 					progress = { toolCalls, text, usage };
 					report();
@@ -1753,7 +2331,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					actions: result.actions ?? [],
 				} satisfies SubagentActionsPayload);
 				const stats = formatStats(result.toolCalls, result.usage);
-				const worktreeNote = result.worktreePath ? `\n\n(Changes left in worktree ${result.worktreePath} — review or merge them.)` : "";
+				const worktreeNote = result.worktreePath ? `\n\n${keptWorktreeNote(result.worktreePath, result.worktreeBranch)}` : "";
 				// The report arrives inline with no frame, no task id and no note, so a
 				// model told to "retrieve the result with task_output" chased an id that
 				// was never registered (WEAK-MODEL-REVIEW-2026-09-06 M3). Say it up
@@ -1770,7 +2348,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					content: [
 						{
 							type: "text",
-							text: `${notes.length ? `${notes.join("\n")}\n\n` : ""}${inlineNote}\n\n${result.output}${worktreeNote}\n\n(${stats})`,
+							text: `${notes.length ? `${notes.join("\n")}\n\n` : ""}${inlineNote}\n\n${bounded(result.output, `${prepared[0].record.taskId}-report`, OUTPUT_CAP)}${worktreeNote}\n\n(${stats})`,
 						},
 					],
 					details: { results: [result], agentRuns: records },
@@ -1783,181 +2361,16 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			// steered system notification, and the child stays resident so
 			// SendMessage can reach it live (steer mid-turn, prompt when idle).
 			const lines: string[] = [...renamed, ...modelNotes];
-			const runtime = await getRuntime(ctx);
+			const runtime = await runtimeOrError(ctx);
+			if (typeof runtime === "string") {
+				// Nothing launched: forget the runs so list_agents and SendMessage never offer them.
+				for (const p of prepared) registry.remove(p.record.taskId);
+				return { content: [{ type: "text", text: `Could not start the agent: ${runtime}` }], details: {}, isError: true };
+			}
 			for (const p of prepared) {
-				let worktree: Worktree | undefined;
-				if (p.request.worktree) {
-					try {
-						worktree = await isolateInWorktree(ctx, p.record, p.request.name);
-					} catch (error) {
-						lines.push(`✗ ${p.record.name}: could not create a worktree: ${(error as Error).message}`);
-						continue;
-					}
-				}
-
-				const logPath = outputLogPath(p.record);
-				let lastLogWrite = 0;
-				let finish!: () => void;
-				const finished = new Promise<void>((resolve) => {
-					finish = resolve;
-				});
-
-				// The child's final output. task.output() falls back to this
-				// because handle.snapshot().text can be blank at a turn boundary —
-				// the same reason the log write below uses `|| outcome.output`.
-				// Keeps task_output consistent with the log and the completion
-				// notification rather than showing an empty body in that case.
-				let lastOutput = "";
-				// The initial task's own report. task_output for THIS task must return the
-				// first turn's reply — not the resident's growing multi-turn transcript —
-				// the same way a SendMessage task returns one reply (review S12).
-				let firstTurnOutput: string | undefined;
-				const live = trackLiveRun(p.record, p.request);
-				const resident: Resident = { handle: undefined as never, startedAt: Date.now(), turnHandlers: [] };
-				const worktreeNote = worktree
-					? `\n\n(Running in worktree ${worktree.path} — kept while the agent stays resident.)`
-					: "";
-				resident.turnHandlers.push((outcome, review, stopped) => {
-					task.status = stopped ? "stopped" : outcome.failed ? "failed" : "completed";
-					task.finishedAt = Date.now();
-					firstTurnOutput = outcome.output;
-					finish();
-					notifyHandBack({
-						from: p.record.taskId,
-						taskId: p.record.taskId,
-						name: p.record.name,
-						toolUseId: toolCallId,
-						outputFile: logPath,
-						outcome,
-						stopped,
-						startedAt: task.startedAt,
-						report: `${bounded(outcome.output, `${p.record.taskId}-report`, OUTPUT_CAP)}${worktreeNote}`,
-						review,
-					});
-				});
-
-				// Idle reaper: every run is a resident now, so without this a long
-				// session accumulates one live AgentSession (extension instances,
-				// message array, MCP tool refs) per delegation for its whole life.
-				// After RESIDENT_IDLE_MS idle the session is released quietly; the
-				// agent stays reachable — SendMessage resumes it from its session
-				// file. Worktree residents are exempt: release would remove the
-				// worktree a resume still needs. Armed from every turn end.
-				let reaper: ReturnType<typeof setTimeout> | undefined;
-				const armReaper = () => {
-					if (worktree) return;
-					if (reaper) clearTimeout(reaper);
-					reaper = setTimeout(() => {
-						reaper = undefined;
-						if (handle.exited()) return;
-						if (handle.busy()) {
-							armReaper();
-							return;
-						}
-						handle.release();
-					}, RESIDENT_IDLE_MS);
-					reaper.unref?.();
-				};
-				// Captured as a string: onExit runs from a `.finally` long after this
-				// turn's ctx may be stale (review S5).
-				const parentCwd = ctx.cwd;
-				const forkPrompt = p.request.fork ? ctx.getSystemPrompt() : undefined;
-				if (forkPrompt !== undefined) persistForkPrompt(p.record, forkPrompt);
-				// No `signal` here on purpose: a resident outlives the spawning turn and
-				// is stopped through task_stop / the panel, not by the turn ending (S15).
-				const handle = await runtime.runResident({
-					name: p.record.name,
-					agent: p.agentDef,
-					cwd: p.record.cwd,
-					forkFrom: p.request.fork ? (sessionFile ?? undefined) : undefined,
-					parentSystemPrompt: forkPrompt,
-					sessionDir: p.record.sessionSearchDir || undefined,
-					model: p.request.model,
-					fallbackModel: p.request.fallbackModel,
-					thinking: p.request.thinking,
-					onProgress: (toolCalls, text, usage) => {
-						live.progress(toolCalls, usage);
-						// Throttled: onProgress fires per tool call/message with the whole
-						// turn text so far, and this path now carries EVERY run — an
-						// unthrottled sync rewrite would be O(n²) bytes on the hot path.
-						// onTurnEnd below flushes the final state, so the tail is never lost.
-						if (logPath && text && Date.now() - lastLogWrite > LOG_WRITE_INTERVAL_MS) {
-							lastLogWrite = Date.now();
-							writeFileSync(logPath, text);
-						}
-					},
-					sink: live.sink,
-					onMessageToMain: (message) => notifyAgentMessage(p.record.taskId, p.record.name, message),
-					extraTools: spawnToolsFor(p.record),
-					onTurnEnd: (outcome) => {
-						registry.sessionFileFor(p.record);
-						live.settle();
-						lastOutput = resident.handle.snapshot().text || outcome.output;
-						if (logPath) writeFileSync(logPath, lastOutput);
-						// The handler is claimed now (so a message arriving mid-review pairs
-						// with the NEXT turn), but runs only once auto mode's hand-back
-						// review of this turn's action sequence has answered, so the
-						// verdict rides in the same notification as the report instead of
-						// trailing it. The wait is bounded (hand-back-review.ts) and
-						// answered synchronously when auto mode is off.
-						const handler = resident.turnHandlers.shift();
-						// A stop or resume during review must not change this turn's outcome.
-						const stopped = stoppedTaskIds.has(p.record.taskId);
-						armReaper();
-						void awaitHandBackReview(pi.events, p.record, outcome.actions).then((review) => {
-							if (handler) {
-								handler(outcome, review, stopped);
-							} else {
-								// A turn nobody is waiting on (e.g. a steer that raced past its
-								// target turn and ran on its own) must still surface.
-								notifyHandBack({
-									from: p.record.taskId,
-									taskId: p.record.taskId,
-									name: p.record.name,
-									toolUseId: toolCallId,
-									outputFile: logPath,
-									outcome,
-									stopped,
-									startedAt: resident.startedAt,
-									report: bounded(outcome.output, `${p.record.taskId}-update-${Date.now()}`, OUTPUT_CAP),
-									review,
-									details: { update: true },
-								});
-							}
-						});
-					},
-					onExit: () => {
-						if (reaper) clearTimeout(reaper);
-						live.finish(stoppedTaskIds.has(p.record.taskId) ? "stopped" : false);
-						if (residents.get(p.record.taskId) === resident) residents.delete(p.record.taskId);
-						liveHandles.delete(p.record.taskId);
-						if (worktree) void cleanupWorktree(parentCwd, worktree);
-					},
-				});
-				resident.handle = handle;
-				residents.set(p.record.taskId, resident);
-				liveHandles.set(p.record.taskId, handle);
-
-				const task: BackgroundTask = {
-					id: p.record.taskId,
-					kind: "subagent",
-					ownUI: true, // rendered live by the subagents panel's agent strip
-					description: `${p.record.name}: ${p.request.task.slice(0, 80)}`,
-					status: "running",
-					startedAt: Date.now(),
-					logPath,
-					output: () => firstTurnOutput ?? (handle.snapshot().text || lastOutput),
-					stop: () => stopAgent(p.record.taskId, handle),
-					resident: () => !handle.exited(),
-					finished,
-				};
-				pi.events.emit(TASK_REGISTER_CHANNEL, task);
-				void handle.send(frameTask(p.request, worktree, parentCwd));
-
-				spawnedThisLoop.add(p.record.taskId);
-				lines.push(
-					`⏳ ${p.record.name} (task ${p.record.taskId}) running in background${logPath ? ` — interim output readable at ${logPath}` : ""}`,
-				);
+				const { launched, line } = await launchResident(p, ctx, runtime, { sessionFile: sessionFile ?? undefined, toolCallId });
+				if (launched) spawnedThisLoop.add(p.record.taskId);
+				lines.push(line);
 			}
 			return {
 				content: [
@@ -1970,231 +2383,97 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			};
 		},
 	});
+	const setAgentForm = registerVariantTool<DescriptionForm>(pi, "short", (form) => ({ ...agentTool, description: agentDescription(form, projectConfigDirName()) }));
+	followDescriptionForm(pi, setAgentForm);
 
-	pi.registerTool({
-		name: "SendMessage",
-		label: "Send Message",
-		...ccToolRenderers<{ to?: string; summary?: string; message?: string }>("Send Message", {
-			title: (a) => (a?.to ? `to ${a.to}${a.summary ? `: ${a.summary}` : ""}` : undefined),
-		}),
-		description:
-			'Send a message to a previously spawned agent, addressed by the name from its spawn result (or its task id). To discover the names of running or finished agents, use list_agents (deferred — load it with tool_search select:list_agents). A resident background agent is reached live (mid-turn the message is steered into its current work; when idle it starts a new turn); a finished agent is resumed from its session with full context. Replies arrive as task notifications. (A subagent reporting back to the main conversation uses its own SendMessage with to: "main".)',
-		parameters: Type.Object({
-			to: Type.String({ description: "Agent name (or task id) from a previous Agent run" }),
-			message: Type.String({ description: "Plain text message for the agent" }),
-			summary: Type.Optional(Type.String({ description: "5-10 word preview shown in the UI" })),
-		}),
-		async execute(toolCallId, params, _signal, _onUpdate, ctx) {
-			if (params.to === "main") {
-				// The main conversation's SendMessage only addresses spawned agents; the
-				// "main" recipient exists only on a subagent's own injected SendMessage.
-				return {
-					content: [{ type: "text", text: 'You are the main conversation — "main" is only a valid recipient from inside a subagent.' }],
-					details: {},
-					isError: true,
-				};
-			}
+	const SendMessageParams = Type.Object({
+		to: Type.String({ description: "Agent name (or task id) from a previous Agent run" }),
+		message: Type.String({ description: "Plain text message for the agent" }),
+		summary: Type.Optional(Type.String({ description: "5-10 word preview shown in the UI" })),
+	});
 
-			const record = registry.resolve(params.to);
-			if (!record) {
-				const known = registry.names().join(", ") || "(none)";
-				return {
-					content: [
-						{
-							type: "text",
-							text: `No run named "${params.to}". SendMessage only reaches agent runs already started this session — address them by their run name or task id, not by a catalog agent name. Start one with the Agent tool first if you haven't. Known runs: ${known}.`,
-						},
-					],
-					details: {},
-					isError: true,
-				};
-			}
-			// Resident background agent: reach its in-process session live.
-			const resident = residents.get(record.taskId);
-			if (resident && !resident.handle.exited()) {
-				if (resident.handle.busy()) {
-					let delivery: "started" | "steered";
-					try {
-						delivery = await resident.handle.send(params.message);
-					} catch (error) {
-						return {
-							content: [{ type: "text", text: `Could not deliver the message to ${record.name}: ${(error as Error).message}` }],
-							details: {},
-							isError: true,
-						};
-					}
-					if (delivery === "steered") {
-						return {
-							content: [
-								{
-									type: "text",
-									text: `Message steered into ${record.name}'s running turn — it will be taken into account before the turn completes, and the turn's completion notification will reflect it.`,
-								},
-							],
-							details: { agentRuns: [record], steered: true },
-						};
-					}
-					// The turn had just ended (settle window): the message rides the next
-					// turn, whose reply nobody has claimed yet — announce it as an update.
-					spawnedThisLoop.add(record.taskId); // arm the anti-fabrication backstop (WEAK-MODEL-REVIEW H1)
+	/**
+	 * SendMessage's body, typed on the plain extension context: the agent view
+	 * also sends from an input handler, which has no tool context (pi 0.99's
+	 * `ExtensionToolContext` adds nested tool calls this never makes).
+	 */
+	const sendMessage = async (toolCallId: string, params: Static<typeof SendMessageParams>, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<AgentToolResult<unknown>> => {
+		if (params.to === "main") {
+			// The main conversation's SendMessage only addresses spawned agents; the
+			// "main" recipient exists only on a subagent's own injected SendMessage.
+			return {
+				content: [{ type: "text", text: 'You are the main conversation — "main" is only a valid recipient from inside a subagent.' }],
+				details: {},
+				isError: true,
+			};
+		}
+
+		const record = registry.resolve(params.to);
+		if (!record) {
+			// Recorded runs only: a name reserved by a spawn that then failed validation is not addressable.
+			const known = registry.list().map((run) => run.name).join(", ") || "(none)";
+			return {
+				content: [
+					{
+						type: "text",
+						text: `No run named "${params.to}". SendMessage only reaches agent runs already started this session — address them by their run name or task id, not by a catalog agent name. Start one with the Agent tool first if you haven't. Known runs: ${known}.`,
+					},
+				],
+				details: {},
+				isError: true,
+			};
+		}
+		// Resident background agent: reach its in-process session live.
+		const resident = residents.get(record.taskId);
+		if (resident && !resident.handle.exited()) {
+			// This call now starts (or joins) the agent's turn.
+			mainCallFor.set(record.taskId, toolCallId);
+			if (resident.handle.busy()) {
+				let delivery: "started" | "steered";
+				try {
+					delivery = await resident.handle.send(params.message);
+				} catch (error) {
+					return {
+						content: [{ type: "text", text: `Could not deliver the message to ${record.name}: ${(error as Error).message}` }],
+						details: {},
+						isError: true,
+					};
+				}
+				if (delivery === "steered") {
 					return {
 						content: [
 							{
 								type: "text",
-								text: `${record.name}'s turn had just finished; the message starts its next turn. The reply will arrive as a task notification from ${record.name}. ${PENDING_RESULT_PROHIBITION}`,
+								text: `Message steered into ${record.name}'s running turn — it will be taken into account before the turn completes, and the turn's completion notification will reflect it.`,
 							},
 						],
-						details: { agentRuns: [record] },
+						details: { agentRuns: [record], steered: true },
 					};
 				}
-
-				const taskId = generateTaskId();
-				let finish!: () => void;
-				const finished = new Promise<void>((resolve) => {
-					finish = resolve;
-				});
-				// This task is ONE turn of the resident agent. Its output must be that
-				// turn's reply — the same text the reply notification carries — not the
-				// resident's whole multi-turn transcript, or task_output and the
-				// notification disagree (superset), which weak models conflate.
-				let replyOutput = "";
-				const task: BackgroundTask = {
-					id: taskId,
-					kind: "subagent",
-					ownUI: true, // rendered live by the subagents panel's agent strip
-					description: `message to ${record.name}${params.summary ? `: ${params.summary}` : ""}`,
-					status: "running",
-					startedAt: Date.now(),
-					output: () => replyOutput || resident.handle.snapshot().text,
-					stop: () => stopAgent(record.taskId, resident.handle),
-					resident: () => !resident.handle.exited(),
-					finished,
-				};
-				resident.turnHandlers.push((outcome, review, stopped) => {
-					task.status = stopped ? "stopped" : outcome.failed ? "failed" : "completed";
-					task.finishedAt = Date.now();
-					replyOutput = outcome.output;
-					finish();
-					// `<task-id>` is this message's task (what task_output resolves); `from=`
-					// stays the agent's id, the address a further SendMessage uses. The
-					// tracker's tokens and tool uses span the resident's life, so the
-					// duration does too.
-					notifyHandBack({
-						from: record.taskId,
-						taskId,
-						name: record.name,
-						toolUseId: toolCallId,
-						outputFile: outputLogPath(record),
-						outcome,
-						stopped,
-						startedAt: resident.startedAt,
-						report: bounded(outcome.output, `${taskId}-reply`, OUTPUT_CAP),
-						review,
-					});
-				});
-				pi.events.emit(TASK_REGISTER_CHANNEL, task);
-				void resident.handle.send(params.message);
-				// Same anti-fabrication guard as a fresh spawn (WEAK-MODEL-REVIEW H1):
-				// the reply arrives as a notification, so forbid predicting it and arm
-				// the agent_end backstop (keyed by the agent's persistent id).
-				spawnedThisLoop.add(record.taskId);
+				// The turn had just ended (settle window): the message rides the next
+				// turn, whose reply nobody has claimed yet — announce it as an update.
+				spawnedThisLoop.add(record.taskId); // arm the anti-fabrication backstop (WEAK-MODEL-REVIEW H1)
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Message sent to resident agent ${record.name} (task ${taskId}). The reply will arrive as a task notification on its own; inspect with task_output. ${PENDING_RESULT_PROHIBITION}`,
+							text: `${record.name}'s turn had just finished; the message starts its next turn. The reply will arrive as a task notification from ${record.name}. ${PENDING_RESULT_PROHIBITION}`,
 						},
 					],
-					details: { agentRuns: [record], taskId },
-				};
-			}
-
-			if (runningIds.has(record.taskId)) {
-				return {
-					content: [
-						{ type: "text", text: `Agent ${record.name} is still running — wait for its completion notification, then resend.` },
-					],
-					details: {},
-					isError: true,
-				};
-			}
-			const sessionFile = registry.sessionFileFor(record);
-			// A fork has no agent definition: its identity is the parent's prompt at
-			// spawn time, persisted beside its session. Without it a resume would run
-			// on pi's stock prompt and default tools — refuse instead (review S6).
-			const forkPrompt = record.agent === FORK_AGENT ? readForkPrompt(record) : undefined;
-			if (record.agent === FORK_AGENT && forkPrompt === undefined) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Agent ${record.name} is a fork whose system prompt was not persisted (it ran before fork resume was supported, or its files were removed), so it cannot be resumed faithfully. Start a fresh run instead.`,
-						},
-					],
-					details: {},
-					isError: true,
-				};
-			}
-			if (!sessionFile) {
-				return {
-					content: [
-						{ type: "text", text: `Agent ${record.name} has no persisted session to resume (it may have run before session persistence, or its files were removed).` },
-					],
-					details: {},
-					isError: true,
+					details: { agentRuns: [record] },
 				};
 			}
 
-			// A worktree run whose agent left no changes had its worktree removed at
-			// exit, but the record (persisted in the tool result) still points there.
-			// Resume in the parent cwd instead of a deleted directory, say so in the
-			// reply, and fix the record so later messages don't repeat the note (M2).
-			let relocationNote = "";
-			if (!existsSync(record.cwd)) {
-				relocationNote = `[${record.name}'s working directory ${record.cwd} no longer exists${record.worktree ? " (its isolation worktree was removed when the run left no changes)" : ""}; this turn ran in ${ctx.cwd}.]\n\n`;
-				record.cwd = ctx.cwd;
-				record.worktree = undefined;
-			}
-
 			const taskId = generateTaskId();
 			let finish!: () => void;
 			const finished = new Promise<void>((resolve) => {
 				finish = resolve;
 			});
-
-			runningIds.add(record.taskId);
-			// Re-enter the panel: the finished run's entry flips back to running (or
-			// registers fresh after a session resume) and streams this turn live.
-			const live = trackLiveRun(record, {
-				agent: record.agent,
-				name: record.name,
-				task: params.message,
-				model: record.model,
-				thinking: record.thinking,
-			});
-			const runtime = await getRuntime(ctx);
-			const handle = runtime.run({
-				name: record.name,
-				agent: loadAgents(ctx.cwd).find((a) => a.name === record.agent),
-				task: params.message,
-				cwd: record.cwd,
-				sessionFile,
-				parentSystemPrompt: forkPrompt,
-				model: record.model,
-				// Resume degrades to the session model if the recorded model has become
-				// unavailable since the original run, rather than failing the resume
-				// outright (the note surfaces the swap). Undefined for a fork (record.model
-				// unset — it inherits) or when the record already is the session model.
-				fallbackModel:
-					record.model && ctx.model && record.model !== modelSpec(ctx.model) ? modelSpec(ctx.model) : undefined,
-				thinking: record.thinking,
-				onProgress: (toolCalls, _text, usage) => live.progress(toolCalls, usage),
-				sink: live.sink,
-				onMessageToMain: (message) => notifyAgentMessage(record.taskId, record.name, message),
-				extraTools: spawnToolsFor(record),
-			});
-			liveHandles.set(record.taskId, handle);
-
+			// This task is ONE turn of the resident agent. Its output must be that
+			// turn's reply — the same text the reply notification carries — not the
+			// resident's whole multi-turn transcript, or task_output and the
+			// notification disagree (superset), which weak models conflate.
+			let replyOutput = "";
 			const task: BackgroundTask = {
 				id: taskId,
 				kind: "subagent",
@@ -2202,43 +2481,415 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				description: `message to ${record.name}${params.summary ? `: ${params.summary}` : ""}`,
 				status: "running",
 				startedAt: Date.now(),
-				output: () => handle.snapshot().text,
-				stop: () => stopAgent(record.taskId, handle),
+				output: () => replyOutput || resident.handle.snapshot().text,
+				stop: () => stopAgent(record.taskId, resident.handle),
+				resident: () => !resident.handle.exited(),
 				finished,
 			};
-			pi.events.emit(TASK_REGISTER_CHANNEL, task);
-
-			void handle.result.then((outcome) => {
-				runningIds.delete(record.taskId);
-				const stopped = stoppedTaskIds.has(record.taskId);
-				live.finish(stopped ? "stopped" : Boolean(outcome.failed));
+			resident.turnHandlers.push((outcome, review, stopped) => {
 				task.status = stopped ? "stopped" : outcome.failed ? "failed" : "completed";
 				task.finishedAt = Date.now();
+				replyOutput = outcome.output;
 				finish();
+				// `<task-id>` is this message's task (what task_output resolves); `from=`
+				// stays the agent's id, the address a further SendMessage uses. The
+				// tracker's tokens and tool uses span the resident's life, so the
+				// duration does too.
 				notifyHandBack({
 					from: record.taskId,
 					taskId,
 					name: record.name,
 					toolUseId: toolCallId,
+					outputFile: outputLogPath(record),
 					outcome,
 					stopped,
-					startedAt: task.startedAt,
-					report: `${relocationNote}${bounded(outcome.output, `${taskId}-reply`, OUTPUT_CAP)}`,
-					review: undefined,
+					startedAt: resident.startedAt,
+					report: bounded(outcome.output, `${taskId}-reply`, OUTPUT_CAP),
+					review,
 				});
 			});
-
-			spawnedThisLoop.add(record.taskId); // arm the anti-fabrication backstop (WEAK-MODEL-REVIEW H1)
+			pi.events.emit(TASK_REGISTER_CHANNEL, task);
+			void resident.handle.send(params.message);
+			// Same anti-fabrication guard as a fresh spawn (WEAK-MODEL-REVIEW H1):
+			// the reply arrives as a notification, so forbid predicting it and arm
+			// the agent_end backstop (keyed by the agent's persistent id).
+			spawnedThisLoop.add(record.taskId);
 			return {
 				content: [
 					{
 						type: "text",
-						text: `Message sent to ${record.name} (task ${taskId}). The reply will arrive as a task notification on its own; inspect with task_output. ${PENDING_RESULT_PROHIBITION}`,
+						text: `Message sent to resident agent ${record.name} (task ${taskId}). The reply will arrive as a task notification on its own; inspect with task_output. ${PENDING_RESULT_PROHIBITION}`,
 					},
 				],
 				details: { agentRuns: [record], taskId },
 			};
-		},
+		}
+
+		if (runningIds.has(record.taskId)) {
+			return {
+				content: [
+					{ type: "text", text: `Agent ${record.name} is still running — wait for its completion notification, then resend.` },
+				],
+				details: {},
+				isError: true,
+			};
+		}
+		const sessionFile = registry.sessionFileFor(record);
+		// A fork has no agent definition: its identity is the parent's prompt at
+		// spawn time, persisted beside its session. Without it a resume would run
+		// on pi's stock prompt and default tools — refuse instead (review S6).
+		const forkPrompt = record.agent === FORK_AGENT ? readForkPrompt(record) : undefined;
+		if (record.agent === FORK_AGENT && forkPrompt === undefined) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Agent ${record.name} is a fork whose system prompt was not persisted (it ran before fork resume was supported, or its files were removed), so it cannot be resumed faithfully. Start a fresh run instead.`,
+					},
+				],
+				details: {},
+				isError: true,
+			};
+		}
+		if (!sessionFile) {
+			return {
+				content: [
+					{ type: "text", text: `Agent ${record.name} has no persisted session to resume (it may have run before session persistence, or its files were removed).` },
+				],
+				details: {},
+				isError: true,
+			};
+		}
+
+		// A worktree run whose agent left no changes had its worktree removed at
+		// exit, but the record (persisted in the tool result) still points there.
+		// Resume in the parent cwd instead of a deleted directory, say so in the
+		// reply, and fix the record so later messages don't repeat the note (M2).
+		let relocationNote = "";
+		if (!existsSync(record.cwd)) {
+			const cwd = workCwd(ctx);
+			relocationNote = `[${record.name}'s working directory ${record.cwd} no longer exists${record.worktree ? " (its isolation worktree was removed when the run left no changes)" : ""}; this turn ran in ${cwd}.]\n\n`;
+			record.cwd = cwd;
+			record.worktree = undefined;
+		}
+
+		// Before the run is marked running (L8, as in executeRun).
+		const runtime = await runtimeOrError(ctx);
+		if (typeof runtime === "string") {
+			return { content: [{ type: "text", text: `Could not resume ${record.name}: ${runtime}` }], details: {}, isError: true };
+		}
+
+		const taskId = generateTaskId();
+		let finish!: () => void;
+		const finished = new Promise<void>((resolve) => {
+			finish = resolve;
+		});
+
+		runningIds.add(record.taskId);
+		// Re-enter the panel: the finished run's entry flips back to running (or
+		// registers fresh after a session resume) and streams this turn live.
+		const live = trackLiveRun(record, {
+			agent: record.agent,
+			name: record.name,
+			task: params.message,
+			model: record.model,
+			thinking: record.thinking,
+		});
+		// One-shot modes (`-p`, `--mode json`) exit when the turn settles, so the
+		// resumed turn runs blocking there and the reply is the tool result, as a
+		// spawn's report is (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 M3).
+		const oneShot = !sessionOutlivesTurn(ctx.mode);
+		mainCallFor.set(record.taskId, toolCallId);
+		const handle = runtime.run({
+			name: record.name,
+			agent: loadAgents(ctx.cwd).find((a) => a.name === record.agent),
+			task: params.message,
+			cwd: record.cwd,
+			sessionFile,
+			parentSystemPrompt: forkPrompt,
+			parentRequest: record.agent === FORK_AGENT ? readForkRequest(record) : undefined,
+			// Blocking, so the call's own abort stops it; a background turn is stopped by task_stop.
+			signal: oneShot ? signal : undefined,
+			model: record.model,
+			// Resume degrades to the session model if the recorded model has become
+			// unavailable since the original run, rather than failing the resume
+			// outright (the note surfaces the swap). Undefined for a fork (record.model
+			// unset — it inherits) or when the record already is the session model.
+			fallbackModel:
+				record.model && ctx.model && record.model !== modelSpec(ctx.model) ? modelSpec(ctx.model) : undefined,
+			thinking: record.thinking,
+			onProgress: (toolCalls, _text, usage) => live.progress(toolCalls, usage),
+			sink: live.sink,
+			onMessageToMain: (message) => notifyAgentMessage(record.taskId, record.name, message),
+			extraTools: spawnToolsFor(record),
+			mainToolCallId: () => mainCallOf(record.taskId),
+		});
+		liveHandles.set(record.taskId, handle);
+
+		if (oneShot) {
+			const outcome = await handle.result;
+			runningIds.delete(record.taskId);
+			live.finish(stoppedTaskIds.has(record.taskId) ? "stopped" : Boolean(outcome.failed));
+			// Auto mode reviews the turn's actions; the gate attaches the verdict to this tool result.
+			pi.events.emit(SUBAGENT_ACTIONS_CHANNEL, { toolCallId, actions: outcome.actions } satisfies SubagentActionsPayload);
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							`${record.name}: ${oneShotNote("agent's turn")} Its reply follows here; there is no background task to poll.\n\n` +
+							`${relocationNote}${bounded(outcome.output, `${taskId}-reply`, OUTPUT_CAP)}\n\n(${formatStats(outcome.toolCalls, outcome.usage)})`,
+					},
+				],
+				details: { agentRuns: [record] },
+				isError: outcome.failed ?? false,
+			};
+		}
+
+		let settledOutput: string | undefined;
+		const task: BackgroundTask = {
+			id: taskId,
+			kind: "subagent",
+			ownUI: true, // rendered live by the subagents panel's agent strip
+			description: `message to ${record.name}${params.summary ? `: ${params.summary}` : ""}`,
+			status: "running",
+			startedAt: Date.now(),
+			output: () => settledOutput ?? handle.snapshot().text,
+			stop: () => stopAgent(record.taskId, handle),
+			finished,
+		};
+		pi.events.emit(TASK_REGISTER_CHANNEL, task);
+
+		void handle.result.then(async (outcome) => {
+			runningIds.delete(record.taskId);
+			// Read before the review: a stop or resume during it must not change this turn's outcome.
+			const stopped = stoppedTaskIds.has(record.taskId);
+			live.finish(stopped ? "stopped" : Boolean(outcome.failed));
+			// Auto mode reviews this turn's actions before the reply goes out, as it
+			// does for a resident's turn; a resumed turn once skipped it
+			// (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 M2). The task settles after the
+			// review, so task_output never returns the reply ahead of its verdict.
+			const review = await awaitHandBackReview(pi.events, record, outcome.actions, undefined, mainCallOf(record.taskId));
+			// The outcome includes SubagentHandback and startup/abort errors;
+			// the live snapshot only contains assistant text, not the final report.
+			settledOutput = `${relocationNote}${outcome.output}`;
+			task.status = stopped ? "stopped" : outcome.failed ? "failed" : "completed";
+			task.finishedAt = Date.now();
+			finish();
+			notifyHandBack({
+				from: record.taskId,
+				taskId,
+				name: record.name,
+				toolUseId: toolCallId,
+				outcome,
+				stopped,
+				startedAt: task.startedAt,
+				report: `${relocationNote}${bounded(outcome.output, `${taskId}-reply`, OUTPUT_CAP)}`,
+				review,
+			});
+		});
+
+		spawnedThisLoop.add(record.taskId); // arm the anti-fabrication backstop (WEAK-MODEL-REVIEW H1)
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Message sent to ${record.name} (task ${taskId}). The reply will arrive as a task notification on its own; inspect with task_output. ${PENDING_RESULT_PROHIBITION}`,
+				},
+			],
+			details: { agentRuns: [record], taskId },
+		};
+	};
+
+	const sendMessageTool = defineTool({
+		name: "SendMessage",
+		label: "Send Message",
+		...ccToolRenderers<{ to?: string; summary?: string; message?: string }>("Send Message", {
+			title: (a) => (a?.to ? `to ${a.to}${a.summary ? `: ${a.summary}` : ""}` : undefined),
+		}),
+		description:
+			'Send a message to a previously spawned agent, addressed by the name from its spawn result (or its task id). To discover the names of running or finished agents, use list_agents. A resident background agent is reached live (mid-turn the message is steered into its current work; when idle it starts a new turn); a finished agent is resumed from its session with full context. Replies arrive as task notifications. (A subagent reporting back to the main conversation uses its own SendMessage with to: "main".)',
+		parameters: SendMessageParams,
+		execute: (toolCallId, params, signal, _onUpdate, ctx) => sendMessage(toolCallId, params, signal, ctx),
+	});
+	pi.registerTool(sendMessageTool);
+
+	/**
+	 * What the user submits while viewing an agent goes to that agent, as in
+	 * Claude Code (findings §40): Claude Code's mid-turn wrapper, steered into a
+	 * running turn or starting one on an idle resident, whose reply notifies
+	 * under the agent's own task id. A released or finished agent resumes
+	 * through SendMessage's path. Slash commands, skills and `!` shell lines
+	 * keep their main-conversation meaning.
+	 */
+	const deliverFromView = async (ctx: ExtensionContext, taskId: string, text: string) => {
+		const record = registry.resolve(taskId);
+		const fail = (reason: string) => ctx.ui.notify(`Could not send the message to ${record?.name ?? "the agent"}: ${reason}`, "error");
+		if (!record) return fail("the agent is gone.");
+		const wrapped = userMessageForAgent(text);
+		const resident = residents.get(record.taskId);
+		if (resident && !resident.handle.exited()) {
+			liveRuns.block(record.taskId, { kind: "user", text });
+			try {
+				await resident.handle.send(wrapped);
+			} catch (error) {
+				fail((error as Error).message);
+			}
+			return;
+		}
+		const result = await sendMessage(`view-${Date.now()}`, { to: record.taskId, message: wrapped }, undefined, ctx);
+		if (result.isError) fail(result.content.map((block) => (block.type === "text" ? block.text : "")).join(" "));
+	};
+	pi.on("input", (event, ctx) => {
+		const taskId = view ? panel.viewedTaskId() : undefined;
+		if (!taskId || event.source !== "interactive") return undefined;
+		const text = event.text.trim();
+		if (!text || text.startsWith("/") || text.startsWith("!")) return undefined;
+		void deliverFromView(ctx, taskId, event.text).catch((error: unknown) => {
+			ctx.ui.notify(`Could not send the message: ${error instanceof Error ? error.message : String(error)}`, "error");
+		});
+		return { action: "handled" as const };
+	});
+
+	/** A run's model as Claude Code names it in `/tasks` (`Sonnet 5`), else its spec. */
+	const modelLabel = (ctx: ExtensionContext, spec: string | undefined): string | undefined => {
+		if (!spec) return undefined;
+		try {
+			return findConfigured(ctx.modelRegistry.getAvailable(), spec)?.name ?? spec;
+		} catch {
+			return spec; // no registry (a torn-down session)
+		}
+	};
+
+	/**
+	 * `/tasks`: Claude Code's Background dialog (findings §40): running shells,
+	 * running agents, and the finished agents the user viewed. Enter views an
+	 * agent or shows a shell's details in the dialog, x stops the selected
+	 * running task, Esc closes. Enter on the shells chip below the editor opens
+	 * it too.
+	 */
+	const openTasksDialog = async (ctx: ExtensionContext) => {
+		if (!canShowCustomUi(ctx)) {
+			if (ctx.mode !== "rpc") return;
+			const lines = [
+				...shellRows(shellTasks.list(), Date.now()).map((task) => `- ${task.id} [shell, ${task.status}] ${task.command ?? task.description}`),
+				...liveRuns.list().filter((run) => run.depth === 0).map((run) => `- ${run.taskId} [${run.name}, ${run.status}] ${run.label}`),
+			];
+			ctx.ui.notify([
+				"The interactive task viewer requires TUI mode; showing a task snapshot instead.",
+				...(lines.length ? lines : ["No background tasks in this session."]),
+				"Use task_output to inspect a task and task_stop to stop it.",
+			].join("\n"), "info");
+			return;
+		}
+		const build = () => {
+			const runs = liveRuns.list().filter((run) => run.depth === 0);
+			// The shells the chip counts, so Enter on a chip whose shell just finished finds it.
+			const shells = shellRows(shellTasks.list(), Date.now()).map((task) => ({
+				kind: "shell" as const,
+				id: task.id,
+				text: task.command ?? task.description,
+				running: task.status === "running",
+				status: task.status,
+			}));
+			const agents = [
+				...runs.filter((run) => run.status === "running"),
+				...runs.filter((run) => run.status !== "running" && run.viewed),
+			].map((run) => ({ kind: "agent" as const, taskId: run.taskId, text: run.label, model: modelLabel(ctx, run.model), running: run.status === "running" }));
+			return { shells, agents };
+		};
+		let selected = 0;
+		// Rebuilt when a run or shell changes, not per frame or keystroke.
+		let snapshot = build();
+		// The rows on screen: keys act on what the user sees, even when a change
+		// has rebuilt the snapshot and its render is still pending.
+		let shown = tasksItems(snapshot);
+		// The list, or one shell's details inside the same dialog.
+		let dialogView: TasksView = { mode: "list" };
+		const shellById = (id: string) => shellTasks.list().find((task) => task.id === id);
+		const stopShell = (task: { stop(): void } | undefined) => {
+			try {
+				task?.stop();
+			} catch {
+				// A dead process's stop() throwing must not break the dialog.
+			}
+		};
+		const chosen = await panelUi(pi.events, ctx.ui).custom<string | null>((tui, theme, _keybindings, done) => {
+			const paint = { fg: safeThemePaint(theme), bold: safeThemeBold(theme) };
+			const refresh = () => {
+				snapshot = build();
+				tui.requestRender();
+			};
+			const unsubscribe = liveRuns.subscribe(refresh);
+			const unsubscribeShells = shellTasks.subscribe(refresh);
+			// A running shell's details follow its runtime and output once a second,
+			// and the list drops a finished shell once its linger window ends, as
+			// the chip does (a rebuild only when that row set changes).
+			const ticker = setInterval(() => {
+				if (dialogView.mode === "shell") {
+					if (shellById(dialogView.id)?.status === "running") tui.requestRender();
+				} else if (snapshot.shells.some((shell) => !shell.running) && shellRows(shellTasks.list(), Date.now()).length !== snapshot.shells.length) {
+					refresh();
+				}
+			}, 1000);
+			ticker.unref?.();
+			const finish = (value: string | null) => {
+				clearInterval(ticker);
+				unsubscribe();
+				unsubscribeShells();
+				done(value);
+			};
+			return {
+				render: (width: number) => {
+					const task = dialogView.mode === "shell" ? shellById(dialogView.id) : undefined;
+					dialogView = settleTasksView(dialogView, task !== undefined);
+					if (dialogView.mode === "shell" && task) {
+						return ["", ...renderShellDetail(task, width - 2, Date.now(), paint).map((line) => `  ${line}`), ""].map((line) => truncateLine(line, width));
+					}
+					shown = tasksItems(snapshot);
+					selected = Math.max(0, Math.min(selected, shown.length - 1));
+					return ["", ...renderTasksDialog({ ...snapshot, selected, width }, paint), ""].map((line) => truncateLine(line, width));
+				},
+				handleInput: (data: string) => {
+					if (isKeyRelease(data)) return;
+					const id = keyId(data);
+					if (dialogView.mode === "shell") {
+						const task = shellById(dialogView.id);
+						const action = shellDetailKey(id, keyText(data), task?.status === "running");
+						if (action === "close") return finish(null);
+						if (action === "back") dialogView = { mode: "list" };
+						else if (action === "stop") stopShell(task);
+						tui.requestRender();
+						return;
+					}
+					const items = shown;
+					if (id === "escape") return finish(null);
+					if (id === "up" || id === "down") {
+						selected = moveTasksSelection(selected, id, items.length);
+						tui.requestRender();
+						return;
+					}
+					const item = items[selected];
+					if (id === "enter" && item?.kind === "agent") return finish(item.taskId);
+					if (id === "enter" && item?.kind === "shell") {
+						dialogView = { mode: "shell", id: item.id };
+						tui.requestRender();
+						return;
+					}
+					if (keyText(data)?.toLowerCase() === "x" && item?.running) {
+						if (item.kind === "agent") void stopAgent(item.taskId);
+						else stopShell(shellById(item.id));
+						tui.requestRender();
+					}
+				},
+				invalidate: () => {},
+			};
+		});
+		if (chosen) openView(ctx, chosen);
+	};
+	registerLocalCommand(pi, "tasks", {
+		description: "List background tasks: shells, running agents, and the agents you viewed",
+		handler: async (_args, ctx) => openTasksDialog(ctx as ExtensionContext),
 	});
 	pi.events.emit(DEFER_CHANNEL, { name: "SendMessage", keywords: ["message", "agent", "resume", "continue", "teammate"] });
 
@@ -2279,7 +2930,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			};
 		},
 	});
-	pi.events.emit(DEFER_CHANNEL, { name: "list_agents", keywords: ["agents", "list", "running", "spawned", "subagents", "who"] });
+	// Eager, as Claude Code's ListAgents is: not emitted on the deferral channel.
 
 	registerLocalCommand(pi, "agents", {
 		description: "Open the live subagent panel, or list available agents",
@@ -2287,7 +2938,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			// With live children, focus the strip on the newest and open its view
 			// (Claude Code's agent panel); otherwise there is nothing running, so
 			// list the catalog the way the tool's action:"list" does.
-			if (ctx.hasUI && panel.rowCount() > 1) {
+			if (ctx.hasUI && ctx.mode === "tui" && panel.rowCount() > 1) {
 				panel.setFocus(1); // row 0 is `main`; 1 is the newest live child
 				const run = panel.selectedRun();
 				if (run) {
@@ -2295,6 +2946,14 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					return;
 				}
 			}
+			if (ctx.mode === "rpc" && registry.list().length) {
+				ctx.ui.notify([
+					"The live subagent panel requires TUI mode; showing spawned agents instead.",
+					...registry.list().map((run) => `- ${run.name} [${run.agent}] — ${agentStatus(run)} (task ${run.taskId})`),
+					"Use /tasks for task status; task_output and task_stop inspect or stop a task.",
+				].join("\n"), "info");
+				return;
+			}
 			ctx.ui.notify(`Available agents:\n${describeAgents(ctx.cwd)}`, "info");
 		},
 	});
@@ -2317,6 +2976,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 					: "subagentModel: (not set)",
 				`effective: ${resolution.model ? `${resolution.model.provider}/${resolution.model.id}` : "none"} (${resolution.source})`,
 				...(resolution.notices.length ? [resolution.notices.join("\n")] : []),
+				...(resolution.source === "default" && resolution.model
+					? chosenModelWarnings({ available, sessionModel: ctx.model, chosen: resolution.model, role: "subagent", suggestNewer: readSuggestNewerModels(os.homedir()) }).map((warning) => `! ${warning.text} ${warning.fix}`)
+					: []),
 				"Set it with /subagent <provider/model-id|sonnet|opus|haiku|fable|inherit>, or clear with /subagent clear.",
 			].join("\n"),
 			"info",
@@ -2388,16 +3050,23 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			ctx.ui.notify("Could not save subagent model: " + (error as Error).message, "error");
 			return;
 		}
-		emitModelStatus(ctx);
 		ctx.ui.notify(`Subagent default set to "${spec}" (saved to ~/.onecode/settings.json).`, "info");
+		// What the choice costs, shown now even if an earlier choice already
+		// raised the same line; marked noticed so the status refresh is quiet.
+		if (resolved) {
+			for (const warning of chosenModelWarnings({ available, sessionModel: ctx.model, chosen: resolved, role: "subagent", suggestNewer: readSuggestNewerModels(os.homedir()) })) {
+				const message = `${warning.text} ${warning.fix}`;
+				noticedModels.add(message);
+				ctx.ui.notify(message, "warning");
+			}
+		}
+		emitModelStatus(ctx);
 	};
 
 	registerLocalCommand(pi, "subagent", {
 		description: "Set the default model for subagent/workflow runs: /subagent [provider/model-id|inherit|status|clear]",
-		getArgumentCompletions: (prefix) =>
-			["inherit", "status", "clear"]
-				.filter((value) => value.startsWith(prefix.trim().toLowerCase()))
-				.map((value) => ({ value, label: value })),
+		argumentHint: "[provider/model-id|inherit|status|clear]",
+		getArgumentCompletions: (prefix) => extendingCompletions(prefix, ["inherit", "status", "clear"].map((value) => ({ value, label: value }))),
 		handler: async (args, ctx) => {
 			const typed = args.trim();
 			if (typed === "clear") {
@@ -2441,7 +3110,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			const current = configured && configured.spec.includes("/") ? configured.spec : undefined;
 			const entries = toPickerEntries(available);
 
-			const chosen = await ctx.ui.custom<PickerEntry | null>((tui, theme, _keybindings, done) =>
+			const chosen = await panelUi(pi.events, ctx.ui).custom<PickerEntry | null>((tui, theme, _keybindings, done) =>
 				modelPickerComponent(
 					{
 						entries,