one-code-extension 0.4.1 → 0.6.0

package/extensions/subagents/pending-claim.ts

@@ -28,6 +28,23 @@ export interface PendingRun {
 	taskId: string;
 }
 
+/** The runs by name and task id, comma-separated. */
+function namedRuns(runs: readonly PendingRun[]): string {
+	return runs.map((run) => `${run.name} (task ${run.taskId})`).join(", ");
+}
+
+/**
+ * The background agents still working when a compaction summarized the calls
+ * that started them: the new epoch's history no longer shows them, so a model
+ * that is not told could start the same work again or report a result it
+ * never got (lifecycle-grid-hunt round 3, R3-M27; Claude Code re-attaches its
+ * task status after a compaction).
+ */
+export function runningAfterCompactionReminder(runs: readonly PendingRun[]): string | undefined {
+	if (runs.length === 0) return undefined;
+	return `Background agents you started before this conversation was compacted are still running: ${namedRuns(runs)}. Each one notifies you when it finishes; do not start the same work again. Use task_output to check on one, or task_stop to end it.`;
+}
+
 /**
  * The one-shot for a turn that ended with runs still pending, or undefined when
  * there is nothing to say. Named runs, so a model with several in flight knows
@@ -35,7 +52,7 @@ export interface PendingRun {
  */
 export function pendingClaimReminder(runs: readonly PendingRun[]): string | undefined {
 	if (runs.length === 0) return undefined;
-	const named = runs.map((run) => `${run.name} (task ${run.taskId})`).join(", ");
+	const named = namedRuns(runs);
 	const subject = runs.length === 1 ? "It has" : "They have";
 	return (
 		`You ended that turn while ${named} ${runs.length === 1 ? "was" : "were"} still running. ${subject} not reported yet, ` +

package/extensions/subagents/runner.ts

@@ -12,19 +12,25 @@
  * `<sessionDir>/subagents/<taskId>/`, so a finished run can be resumed from disk.
  */
 
+import { childWriteWatcher } from "../lib/child-writes.ts";
 import { createHash } from "node:crypto";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { existsSync } from "node:fs";
 import { type AgentSession, type ExtensionError, getAgentDir, SessionManager, type ToolDefinition } from "@earendil-works/pi-coding-agent";
-import type { Api, Model } from "@earendil-works/pi-ai";
+import type { Api, Message, Model } from "@earendil-works/pi-ai";
 import { whenAborted } from "../lib/abort.ts";
-import { type AgentLoaderOptions, buildAgentLoader, createSharedModelRuntime, openChildSession } from "../lib/agent-loader.ts";
+import { type AgentLoaderOptions, buildAgentLoader, createSharedModelRuntime, disposeChildSession, openChildSession } from "../lib/agent-loader.ts";
 import { agentPromptIdentity, PrefixWarmGate, prefixWarmKey, type Release } from "../lib/prefix-warm-gate.ts";
 import type { PermissionBridge } from "../permissions/subagent-gate.ts";
 import type { HookBridge } from "../hooks/subagent-bridge.ts";
 import { findConfigured, modelSpec } from "../lib/model-policy.ts";
 import { isModelUnavailableError } from "../auto-mode/model-select.ts";
-import { type AgentDefinition, childToolAllowlist, usableAllowlistedTools } from "./agents.ts";
+import { type AgentDefinition, agentToolOptions, unusableAllowlistError } from "./agents.ts";
+import { CHILD_EXTENSION_PATHS } from "../lib/child-extensions.ts";
+import { type HandbackSlot, SUBAGENT_HANDBACK, subagentHandbackExtension } from "../lib/subagent-handback.ts";
+import type { RequestCapture } from "../lib/request-replay.ts";
+import { forkCacheExtension } from "./fork-cache.ts";
+import { parentModeExtension } from "./parent-mode.ts";
+import { type DeferRequest, deferLikeParentExtension, injectedByParent } from "../lib/deferred.ts";
 import type { ChildHandle, ChildOutcome, RpcChildHandle } from "./outcome.ts";
 import { sendToMainTool } from "./send-to-main-tool.ts";
 import { SessionTurnTracker } from "./session-turns.ts";
@@ -53,34 +59,12 @@ const WALL_CLOCK_CAP_MS = 30 * 60 * 1000;
 
 /**
  * Tools the runtime injects into a child; the permission gate must never gate
- * them. `Agent` is the injected child-spawn tool (index.ts) — the spawn itself
+ * them. `SubagentHandback` only returns the child's report to its caller.
+ * `Agent` is the injected child-spawn tool (index.ts) — the spawn itself
  * is free (matching the main conversation's auto-allowed Agent tool); every
  * tool call the spawned grandchild makes still runs through the real gate.
  */
-const NEVER_GATE = new Set(["structured_output", "SendMessage", "Agent"]);
-
-/**
- * The curated extensions loaded into a subagent session (via additionalExtensionPaths,
- * which the loader loads even under noExtensions). Broadly Claude Code's model — a
- * subagent gets project context + freshness + a working toolset, but NOT the frontier
- * chrome (banner/spinner/recap) or the orchestration EXTENSIONS. Nested spawning
- * (CC parity: subagents spawn subagents) is instead an injected `Agent` custom tool
- * (index.ts childAgentTool, passed via extraTools) that delegates to the PARENT
- * extension's runtime — one registry, one panel, one permission gate — and is
- * depth-capped there.
- *
- * `lsp` is deliberately NOT here (matching CC, findings §17.3): a child session is torn
- * down with the raw AgentSession.dispose(), which never fires session_shutdown, so lsp's
- * cleanup would never run and any language server it started would leak for the life of
- * the parent session. MCP is also not listed: its
- * tools are shared in from the parent as customTools (getMcpTools), not reconnected.
- *
- * Order mirrors the package's load order: reminder/deferral sinks (system-reminder,
- * tool-search) first, before anything emitting on their channels (the bus does not replay).
- */
-const EXTENSIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
-const CHILD_EXTENSIONS = ["system-reminder", "tool-search", "claude-context", "file-tracker", "search-tools", "skill", "web", "web-fetch", "notebook"];
-const CHILD_EXTENSION_PATHS = CHILD_EXTENSIONS.map((name) => join(EXTENSIONS_DIR, name, "index.ts"));
+const NEVER_GATE = new Set(["structured_output", "SendMessage", SUBAGENT_HANDBACK, "Agent"]);
 
 type Session = AgentSession;
 
@@ -92,8 +76,15 @@ interface ChildSessionSpec {
 	agent?: AgentDefinition;
 	/** Parent session file — present for a fork run (inherit the parent transcript). */
 	forkFrom?: string;
+	/** Messages appended to a fork's transcript before its task (e.g. `/btw`'s side exchange). */
+	forkMessages?: Message[];
 	/** The parent's current system prompt, applied to a fork so it continues as the parent. */
 	parentSystemPrompt?: string;
+	/**
+	 * The parent's last provider request, for a fork: every fork request is
+	 * built from it so the fork reads the parent's prompt cache (fork-cache.ts).
+	 */
+	parentRequest?: RequestCapture;
 	/** Existing persisted session to resume (SendMessage to a finished agent). */
 	sessionFile?: string;
 	/** Where a new run's persisted session lands; falls back to an in-memory session. */
@@ -111,6 +102,12 @@ interface ChildSessionSpec {
 	onMessageToMain?: (message: string, summary?: string) => void;
 	/** Extra injected tools (e.g. the child-spawn Agent tool for depth-0 children). */
 	extraTools?: ToolDefinition[];
+	/**
+	 * The main session's tool call that started the run's current turn, read
+	 * per gated call (a SendMessage can start a later turn). The permission
+	 * bridge passes it on as `ChildToolCall.parentToolCallId`.
+	 */
+	mainToolCallId?: () => string | undefined;
 }
 
 export interface SubagentRunOptions extends ChildSessionSpec {
@@ -125,11 +122,33 @@ export interface ResidentRunOptions extends Omit<ChildSessionSpec, "sessionFile"
 	onProgress: (toolCalls: number, lastText: string, usage: UsageTotals) => void;
 	/** Fires at the end of EVERY turn (initial task and later messages alike). */
 	onTurnEnd: (outcome: ChildOutcome) => void;
-	onExit?: () => void;
+	/** Fires once when the resident exits; a returned promise (worktree cleanup) is part of kill()'s settle. */
+	onExit?: () => void | Promise<unknown>;
 	/** Optional live sink for the subagent panel (activity + transcript blocks). */
 	sink?: LiveSink;
 }
 
+/**
+ * A child's session manager: a resume reopens its file; otherwise a fork
+ * clones the parent transcript (when the parent has written one) and anything
+ * else starts empty, and `forkMessages` are appended so the child sees them before
+ * its task and a later resume finds them in its file. Exported for tests.
+ */
+export function newChildSessionManager(spec: Pick<ChildSessionSpec, "cwd" | "forkFrom" | "forkMessages" | "sessionFile" | "sessionDir">): SessionManager {
+	// The resume cwd is passed explicitly: a worktree run's persisted cwd may
+	// be gone by the time it is messaged (index.ts substitutes the parent cwd).
+	if (spec.sessionFile) return SessionManager.open(spec.sessionFile, undefined, spec.cwd);
+	// pi writes a session file with its first assistant reply, so a parent with
+	// no transcript yet (or run with --no-session) has nothing to clone.
+	const manager = spec.forkFrom && existsSync(spec.forkFrom)
+		? SessionManager.forkFrom(spec.forkFrom, spec.cwd, spec.sessionDir)
+		: spec.sessionDir
+			? SessionManager.create(spec.cwd, spec.sessionDir)
+			: SessionManager.inMemory(spec.cwd);
+	for (const message of spec.forkMessages ?? []) manager.appendMessage(message);
+	return manager;
+}
+
 /** Prepend a one-time spawn note (e.g. a model fallback) to an outcome's output. */
 function withNote(outcome: ChildOutcome, note: string | undefined): ChildOutcome {
 	return note ? { ...outcome, output: `${note}\n\n${outcome.output}` } : outcome;
@@ -145,6 +164,10 @@ export class SubagentRuntime {
 	 * still-connecting (possibly empty) one.
 	 */
 	private readonly getMcpTools: () => ToolDefinition[] | Promise<ToolDefinition[]>;
+	/** The tools the parent session defers (lib/deferred.ts queryDeferred): a child defers the ones injected into it the same way. */
+	private readonly getParentDeferred: () => DeferRequest[];
+	/** The main session's live permission mode, for a fork: told to it when it differs from what it was told (parent-mode.ts). */
+	private readonly getParentMode: (() => string) | undefined;
 	/**
 	 * The parent's permission decision closure (undefined until permissions
 	 * publishes it), wrapped so every call carries the asking run's name: the
@@ -158,10 +181,14 @@ export class SubagentRuntime {
 	/** A child extension handler threw (pi swallows it otherwise); surfaced to the user by index.ts. */
 	private readonly onExtensionError: (runName: string | undefined, error: ExtensionError) => void;
 	private readonly onModelUnusable: (model: string, reason: string) => void;
+	/** A child's edit or write changed a file (lib/child-writes.ts); index.ts tells the parent's file-tracker. */
+	private readonly onChildWrite: (path: string, runName: string | undefined) => void;
 	/** Child session id → run name, for the bridge wrapper above. */
 	private readonly runNames = new Map<string, string>();
 	/** Child session id → agent type (`explore`, …), for the hook payload's `agent_type`. */
 	private readonly agentTypes = new Map<string, string>();
+	/** Child session id → the main-session call that started its turn, for the bridge wrapper. */
+	private readonly mainToolCalls = new Map<string, () => string | undefined>();
 	/**
 	 * Parallel children with the same request prefix (same agent prompt and
 	 * model; forks share the parent's) let the first one start streaming before
@@ -178,8 +205,14 @@ export class SubagentRuntime {
 		getHookBridge: () => HookBridge | undefined,
 		onExtensionError: (runName: string | undefined, error: ExtensionError) => void,
 		onModelUnusable: (model: string, reason: string) => void,
+		onChildWrite: (path: string, runName: string | undefined) => void,
+		getParentDeferred: () => DeferRequest[],
+		getParentMode: (() => string) | undefined,
 	) {
 		this.modelRuntime = modelRuntime;
+		this.getParentDeferred = getParentDeferred;
+		this.getParentMode = getParentMode;
+		this.onChildWrite = onChildWrite;
 		this.baseCwd = baseCwd;
 		this.getMcpTools = getMcpTools;
 		this.getHookBridge = getHookBridge;
@@ -191,7 +224,11 @@ export class SubagentRuntime {
 		const namedBridge: PermissionBridge = (call) => {
 			const bridge = getPermissionBridge();
 			if (!bridge) throw new Error("the parent's permission bridge is no longer available");
-			return bridge({ ...call, agent: call.agent ?? (call.sessionId ? this.runNames.get(call.sessionId) : undefined) });
+			return bridge({
+				...call,
+				agent: call.agent ?? (call.sessionId ? this.runNames.get(call.sessionId) : undefined),
+				parentToolCallId: call.parentToolCallId ?? (call.sessionId ? this.mainToolCalls.get(call.sessionId)?.() : undefined),
+			});
 		};
 		this.getPermissionBridge = () => (getPermissionBridge() ? namedBridge : undefined);
 	}
@@ -203,11 +240,14 @@ export class SubagentRuntime {
 		getHookBridge: () => HookBridge | undefined = () => undefined,
 		onExtensionError: (runName: string | undefined, error: ExtensionError) => void = () => {},
 		onModelUnusable: (model: string, reason: string) => void = () => {},
+		onChildWrite: (path: string, runName: string | undefined) => void = () => {},
+		getParentDeferred: () => DeferRequest[] = () => [],
+		getParentMode?: () => string,
 	): Promise<SubagentRuntime> {
 		const modelRuntime = await createSharedModelRuntime(getAgentDir());
 		// Prime the catalog once; spawns read the live snapshot (see resolveModel).
 		await modelRuntime.getAvailable();
-		return new SubagentRuntime(modelRuntime, cwd, getMcpTools, getPermissionBridge, getHookBridge, onExtensionError, onModelUnusable);
+		return new SubagentRuntime(modelRuntime, cwd, getMcpTools, getPermissionBridge, getHookBridge, onExtensionError, onModelUnusable, onChildWrite, getParentDeferred, getParentMode);
 	}
 
 	/**
@@ -234,15 +274,27 @@ export class SubagentRuntime {
 	 * prompt and default tools, review S6); a named agent carries its own; a
 	 * plain run gets pi's base prompt. Built fresh per session (agent-loader.ts).
 	 */
-	private childLoaderOptions(spec: ChildSessionSpec): AgentLoaderOptions {
-		const systemPrompt = SubagentRuntime.isFork(spec) ? spec.parentSystemPrompt : spec.agent?.systemPrompt;
+	private childLoaderOptions(spec: ChildSessionSpec, handback: HandbackSlot): AgentLoaderOptions {
+		const fork = SubagentRuntime.isFork(spec);
+		const systemPrompt = fork ? spec.parentSystemPrompt : spec.agent?.systemPrompt;
 		return {
 			cwd: this.baseCwd,
 			agentDir: getAgentDir(),
 			systemPrompt,
 			neverGate: NEVER_GATE,
 			extraExtensionPaths: CHILD_EXTENSION_PATHS,
-			// claude-context (above) injects # claudeMd on the child's session_start;
+			// Every child hands back through SubagentHandback (deferred in a fork,
+			// lib/subagent-handback.ts). Inline extensions load after the paths
+			// above, so the fork-cache one, last, sees the final body.
+			extraFactories: [
+				// The tools injected below (the spawn and cron tools, the shared MCP
+				// tools) are deferred as the parent defers them: their owners run there.
+				deferLikeParentExtension(this.getParentDeferred(), injectedByParent(spec.extraTools ?? [])),
+				subagentHandbackExtension(handback, { deferred: fork }),
+				...(fork && this.getParentMode ? [parentModeExtension(this.getParentMode)] : []),
+				...(fork && spec.parentRequest ? [forkCacheExtension(spec.parentRequest)] : []),
+			],
+			// claude-context (above) injects the CLAUDE.md instructions on the child's session_start;
 			// pi must not append the same files to the system prompt as well.
 			noContextFiles: true,
 			getPermissionBridge: this.getPermissionBridge,
@@ -271,7 +323,7 @@ export class SubagentRuntime {
 	/**
 	 * Hold a run until a sibling with the same request prefix has started
 	 * streaming (see `warmGate`): same prompt identity, same cwd (the child's
-	 * `# claudeMd` block names its paths) and same model. Resolves to the release
+	 * instructions block names its paths) and same model. Resolves to the release
 	 * for the caller's `finally`.
 	 */
 	private admitPrefix(spec: Pick<ChildSessionSpec, "cwd" | "forkFrom" | "parentSystemPrompt" | "agent">, session: Session): Promise<Release> {
@@ -288,9 +340,12 @@ export class SubagentRuntime {
 		onSettled?: () => void,
 		sink?: LiveSink,
 	): () => void {
+		const childWrote = childWriteWatcher(session.sessionManager?.getCwd?.() ?? this.baseCwd);
 		return session.subscribe((event) => {
 			try {
 				const settled = tracker.process(event as never);
+				const wrote = childWrote(event as never);
+				if (wrote) this.onChildWrite(wrote, this.runNames.get(session.sessionId));
 				const e = event as { type?: string; toolName?: string; args?: unknown; isError?: boolean; result?: unknown; message?: { role?: string; content?: unknown } };
 				if (e.type === "tool_execution_start") {
 					sink?.onBlock?.({ kind: "call", tool: e.toolName ?? "tool", text: summarizeArgs(e.args) });
@@ -350,20 +405,14 @@ export class SubagentRuntime {
 	 * inherits the parent transcript + system prompt; a fresh named run gets the
 	 * agent's own prompt and toolset.
 	 */
-	private async buildChildSession(spec: ChildSessionSpec): Promise<{ session: Session; note?: string }> {
-		const [loader, mcpTools] = await Promise.all([buildAgentLoader(this.childLoaderOptions(spec)), this.getMcpTools()]);
-		const newSessionManager = () =>
-			// The resume cwd is passed explicitly: a worktree run's persisted cwd may
-			// be gone by the time it is messaged (index.ts substitutes the parent cwd).
-			spec.sessionFile
-				? SessionManager.open(spec.sessionFile, undefined, spec.cwd)
-				: spec.forkFrom
-					? SessionManager.forkFrom(spec.forkFrom, spec.cwd, spec.sessionDir)
-					: spec.sessionDir
-						? SessionManager.create(spec.cwd, spec.sessionDir)
-						: SessionManager.inMemory(spec.cwd);
-		// A fork keeps the parent's toolset; only a named agent carries an allowlist.
-		const allowlist = spec.forkFrom ? undefined : spec.agent?.tools;
+	private async buildChildSession(spec: ChildSessionSpec, handback: HandbackSlot): Promise<{ session: Session; note?: string }> {
+		// The MCP wait first: the loader takes the parent's deferrals, which a server
+		// connecting during the wait adds to (it is instant once the connects settled).
+		const mcpTools = await this.getMcpTools();
+		const loader = await buildAgentLoader(this.childLoaderOptions(spec, handback));
+		const newSessionManager = () => newChildSessionManager(spec);
+		// A fork keeps the parent's toolset; only a named agent carries tool lists.
+		const agent = spec.forkFrom ? undefined : spec.agent;
 		const make = async (model: string | undefined): Promise<Session> => {
 			const resolvedModel = model ? await this.resolveModel(model) : undefined;
 			const session = await openChildSession({
@@ -374,10 +423,9 @@ export class SubagentRuntime {
 					modelRuntime: this.modelRuntime,
 					model: resolvedModel as never,
 					thinkingLevel: spec.thinking as never,
-					tools: childToolAllowlist(allowlist),
-					// Denylist grants (CC's "All tools except …" shape) — filters built-ins,
-					// extension tools, and injected customTools alike.
-					excludeTools: spec.forkFrom ? undefined : spec.agent?.excludeTools,
+					// The allowlist with the plumbing re-added, and the denylist (CC's "All
+					// tools except …" shape), which filters injected customTools too.
+					...agentToolOptions(agent),
 					customTools: [sendToMainTool((m, s) => spec.onMessageToMain?.(m, s)), ...(spec.extraTools ?? []), ...mcpTools],
 					sessionManager: newSessionManager(),
 				},
@@ -386,21 +434,17 @@ export class SubagentRuntime {
 			});
 			// An allowlist that matched nothing real would run a tool-less agent
 			// (pi drops unknown names silently). Fail loud with the fix named.
-			if (
-				allowlist &&
-				usableAllowlistedTools(
-					session.getAllTools().map((t) => t.name),
-					allowlist,
-				).length === 0
-			) {
+			const unusable = unusableAllowlistError(
+				agent,
+				session.getAllTools().map((t) => t.name),
+			);
+			if (unusable) {
 				this.discard(session);
-				throw new Error(
-					`Agent "${spec.agent?.name}" lists tools (${allowlist.join(", ")}) that match no available tool. ` +
-						"Use Claude Code names (Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, NotebookEdit, Skill, Agent, SendMessage) or pi names (read, edit, write, bash, grep, find, ls, …) in the agent file's `tools` list.",
-				);
+				throw new Error(unusable);
 			}
 			if (spec.name) this.runNames.set(session.sessionManager.getSessionId(), spec.name);
 			if (spec.agent) this.agentTypes.set(session.sessionManager.getSessionId(), spec.agent.name);
+			if (spec.mainToolCallId) this.mainToolCalls.set(session.sessionManager.getSessionId(), spec.mainToolCallId);
 			return session;
 		};
 		try {
@@ -421,7 +465,8 @@ export class SubagentRuntime {
 	private discard(session: Session): void {
 		this.runNames.delete(session.sessionManager.getSessionId());
 		this.agentTypes.delete(session.sessionManager.getSessionId());
-		session.dispose();
+		this.mainToolCalls.delete(session.sessionManager.getSessionId());
+		disposeChildSession(session);
 	}
 
 	/**
@@ -452,17 +497,17 @@ export class SubagentRuntime {
 				// corrupt session file, loader error) must resolve to a failed
 				// outcome, never reject handle.result — call sites like the
 				// SendMessage resume path consume it with a bare .then().
-				const built = await this.buildChildSession(options);
+				const built = await this.buildChildSession(options, tracker);
 				session = built.session;
 				spawnNote = built.note;
 				unsubscribe = this.wireTracker(session, tracker, options.onProgress, undefined, options.sink);
 				// A resume continues a unique history; only a fresh run shares a prefix.
 				const releasePrefix = options.sessionFile ? undefined : await this.admitPrefix(options, session);
 				try {
-					// The abort listener calls session.abort(), a no-op while nothing runs
-					// yet: a cancellation that landed during the gate wait must stop the
-					// turn from starting at all, not let it run to completion unnoticed.
-					if (options.signal?.aborted) throw new Error("cancelled before the first request was sent");
+					// abort() is a no-op before the prompt starts. Every cancellation
+					// source (signal, kill, wall-clock cap) marks the tracker first,
+					// including one that landed during construction or the prefix wait.
+					if (tracker.aborted) throw new Error("cancelled before the first request was sent");
 					// No template/command expansion: a task starting with "/" is text, not
 					// a command lookup (pi's own sendUserMessage does the same — L2).
 					await session.prompt(options.task, { expandPromptTemplates: false });
@@ -504,11 +549,12 @@ export class SubagentRuntime {
 	 * while an idle resident lives until task_stop / session shutdown.
 	 */
 	async runResident(options: ResidentRunOptions): Promise<RpcChildHandle> {
-		const built = await this.buildChildSession(options);
+		const tracker = new SessionTurnTracker();
+		const built = await this.buildChildSession(options, tracker);
 		const session = built.session;
 		let spawnNote = built.note;
-		const tracker = new SessionTurnTracker();
 		let exited = false;
+		let exitPromise: Promise<void> | undefined;
 		let turnActive = false;
 		let firstTurn = true;
 		let turnTimer: ReturnType<typeof setTimeout> | undefined;
@@ -632,10 +678,18 @@ export class SubagentRuntime {
 				await session.steer(message);
 				return "steered";
 			},
+			// The background extension is not loaded in a child, so the parent's
+			// cron fires record what they sent straight into the child's session.
+			conversation: {
+				getBranch: () => session.sessionManager.getBranch(),
+				appendEntry: (customType, data) => {
+					session.sessionManager.appendCustomEntry(customType, data);
+				},
+			},
 			busy: () => turnActive || !session.isIdle,
 			exited: () => exited,
 			kill: () => {
-				if (exited) return Promise.resolve();
+				if (exited) return exitPromise ?? Promise.resolve();
 				exited = true;
 				pendingSend = undefined;
 				// Report an in-flight turn as terminated, not as a normal completion:
@@ -645,14 +699,15 @@ export class SubagentRuntime {
 				finishTurn(tracker.turnOutcome());
 				// onExit only after the abort settles: it triggers worktree cleanup,
 				// which must not race an aborting session still writing files. The
-				// returned promise lets session_shutdown wait for exactly that.
-				return session
+				// returned promise settles after that cleanup too, so session_shutdown
+				// waits for exactly that.
+				return (exitPromise = session
 					.abort()
 					.catch(() => undefined)
-					.finally(() => {
+					.then(async () => {
 						discard();
-						options.onExit?.();
-					});
+						await Promise.resolve(options.onExit?.()).catch(() => undefined);
+					}));
 			},
 			release: () => {
 				if (exited || turnActive || !session.isIdle) return;

package/extensions/subagents/runs.ts

@@ -10,6 +10,11 @@
 import { readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+/** The synthetic agent type of a run that clones the calling conversation. */
+export const FORK_AGENT = "fork";
+/** The agent a run that names none starts, as in Claude Code. */
+export const DEFAULT_AGENT = "general-purpose";
+
 export interface AgentRunRecord {
 	name: string;
 	agent: string;
@@ -23,6 +28,12 @@ export interface AgentRunRecord {
 	worktree?: boolean;
 	model?: string;
 	thinking?: string;
+	/**
+	 * The run's short title, Claude Code's `description`: the Agent call's
+	 * `description`, or a `/btw` fork's question. The strip, `/tasks` and the
+	 * notification summary show it (findings §40); absent, they show the name.
+	 */
+	description?: string;
 	/**
 	 * Nesting level: 0 = spawned by main, 1 = spawned by a child's own Agent
 	 * tool. Set once at creation and read by every spawn-tool handout (the
@@ -38,13 +49,23 @@ export interface AgentRunRecord {
 	inline?: boolean;
 }
 
+/** `<base>-<n>` with the lowest n ≥ `from` not in `taken`. */
+function firstFreeSuffixed(taken: ReadonlySet<string>, base: string, from: number): string {
+	for (let n = from; ; n++) {
+		const candidate = `${base}-${n}`;
+		if (!taken.has(candidate)) return candidate;
+	}
+}
+
 /** `<agent>-<n>` with the lowest n not already taken. */
 export function nextRunName(existing: Iterable<string>, agent: string): string {
+	return firstFreeSuffixed(new Set(existing), agent, 1);
+}
+
+/** `base` when free, else `<base>-<n>` with the lowest n ≥ 2 not taken (Claude Code's fork naming). */
+export function freeRunName(existing: Iterable<string>, base: string): string {
 	const taken = new Set(existing);
-	for (let n = 1; ; n++) {
-		const candidate = `${agent}-${n}`;
-		if (!taken.has(candidate)) return candidate;
-	}
+	return taken.has(base) ? firstFreeSuffixed(taken, base, 2) : base;
 }
 
 /**
@@ -119,11 +140,21 @@ export class RunRegistry {
 		this.reserved.clear();
 	}
 
-	/** Hold a name until its record is added (a spawn that fails validation leaves it held — harmless). */
+	/** Keep only the records `keep` accepts; names held for runs being spawned stay held. */
+	retain(keep: (record: AgentRunRecord) => boolean): void {
+		for (const record of [...this.byId.values()]) if (!keep(record)) this.remove(record.taskId);
+	}
+
+	/** Hold a name until its record is added. */
 	reserve(name: string): void {
 		this.reserved.add(name);
 	}
 
+	/** Free a held name whose spawn failed validation, so a corrected retry gets it. */
+	release(name: string): void {
+		this.reserved.delete(name);
+	}
+
 	/** Latest wins per name, matching Claude Code's semantics. */
 	add(record: AgentRunRecord): void {
 		this.reserved.delete(record.name);
@@ -131,6 +162,14 @@ export class RunRegistry {
 		this.byId.set(record.taskId, record);
 	}
 
+	/** Forget a run that never started, so neither list_agents nor a resume offers it. */
+	remove(taskId: string): void {
+		const record = this.byId.get(taskId);
+		if (!record) return;
+		this.byId.delete(taskId);
+		if (this.byName.get(record.name) === record) this.byName.delete(record.name);
+	}
+
 	/** Every name in use: recorded runs plus names reserved for runs being spawned. */
 	names(): string[] {
 		return [...new Set([...this.byName.keys(), ...this.reserved])];

package/extensions/subagents/send-to-main-tool.ts

@@ -27,7 +27,7 @@ export function sendToMainTool(onMessage: (message: string, summary?: string) =>
 		}) as never,
 		async execute(_toolCallId: string, params: unknown) {
 			const p = (params ?? {}) as { to?: unknown; message?: unknown; summary?: unknown };
-			// Fail loud (docs/decisions/tools.md): a wrong recipient or a missing
+			// Fail loud (working-docs/decisions/tools.md): a wrong recipient or a missing
 			// message returns isError with the fix named, never a silent success.
 			if (p.to !== undefined && p.to !== "main") {
 				return {

package/extensions/subagents/session-turns.ts

@@ -12,7 +12,8 @@
  */
 
 import { recordAction, type ChildAction } from "../auto-mode/actions.ts";
-import { type ChildOutcome, OUTPUT_CAP } from "./outcome.ts";
+import type { HandbackSlot } from "../lib/subagent-handback.ts";
+import type { ChildOutcome } from "./outcome.ts";
 import { addUsage, emptyUsage, type UsageTotals } from "./usage.ts";
 
 /** The subset of AgentSession events this tracker reads. */
@@ -23,7 +24,12 @@ interface TrackedEvent {
 	message?: { role?: string; content?: unknown; usage?: unknown; stopReason?: string; errorMessage?: string };
 }
 
-export class SessionTurnTracker {
+/**
+ * The tracker is also the run's `HandbackSlot`: a `SubagentHandback` call
+ * records the turn's report here, and the turn's outcome is that report, or
+ * the turn's final assistant text when the child never called the tool.
+ */
+export class SessionTurnTracker implements HandbackSlot {
 	toolCalls = 0;
 	/** What the child did this turn, for auto mode's return review. */
 	actions: ChildAction[] = [];
@@ -43,12 +49,15 @@ export class SessionTurnTracker {
 	aborted: string | undefined;
 	/** Every turn's final text joined, for task_output on a resident agent. */
 	transcript = "";
+	/** The report this turn handed back through SubagentHandback, if it did. */
+	handback: string | undefined;
 
 	/** Call when a new turn is started (a prompt sent while idle). */
 	beginTurn(): void {
 		this.turnText = "";
 		this.providerError = undefined;
 		this.aborted = undefined;
+		this.handback = undefined;
 		// Per turn, not per session: the review that reads this judges the turn just finished.
 		this.actions = [];
 	}
@@ -60,6 +69,17 @@ export class SessionTurnTracker {
 		this.aborted ??= reason;
 	}
 
+	recordHandback(message: string): boolean {
+		if (this.handback !== undefined) return false;
+		this.handback = message;
+		return true;
+	}
+
+	/** What the turn returns: the handed-back report, else the final assistant text. */
+	private get result(): string {
+		return this.handback ?? this.turnText;
+	}
+
 	/** Feed one subscribed event. Returns true when a turn just settled. */
 	process(event: TrackedEvent): boolean {
 		switch (event.type) {
@@ -83,8 +103,8 @@ export class SessionTurnTracker {
 				return false;
 			}
 			case "agent_settled": {
-				if (this.turnText.trim()) {
-					this.transcript = this.transcript ? `${this.transcript}\n\n---\n\n${this.turnText}` : this.turnText;
+				if (this.result.trim()) {
+					this.transcript = this.transcript ? `${this.transcript}\n\n---\n\n${this.result}` : this.result;
 				}
 				return true;
 			}
@@ -95,7 +115,7 @@ export class SessionTurnTracker {
 
 	/** The outcome of the turn that just settled. */
 	turnOutcome(): ChildOutcome {
-		return finishOutcome(this.turnText, this.providerError, this.toolCalls, this.usage, this.actions, this.aborted);
+		return finishOutcome(this.result, this.providerError, this.toolCalls, this.usage, this.actions, this.aborted);
 	}
 }
 
@@ -103,16 +123,20 @@ export class SessionTurnTracker {
  * Shape a run/turn's collected state into a ChildOutcome, matching the spawned
  * child's messages. `aborted` (a reason) wins over everything: an aborted turn's
  * partial text is reported as terminated and failed, never as the answer.
+ *
+ * The text is kept whole. Every consumer bounds it with `persistIfLarge`, which
+ * saves an oversized report to a file and points at it; a cut here left the
+ * persist step nothing over its limit, so a long report lost its end with no
+ * marker (SUBAGENTS-WORKFLOWS-REVIEW-2026-09-26 M1).
  */
 export function finishOutcome(
-	rawOutput: string,
+	output: string,
 	providerError: string | undefined,
 	toolCalls: number,
 	usage: UsageTotals,
 	actions: ChildAction[],
 	aborted?: string,
 ): ChildOutcome {
-	const output = rawOutput.slice(0, OUTPUT_CAP);
 	if (aborted) {
 		return {
 			output: output.trim() ? `${output}\n\n[${aborted}]` : `Subagent ${aborted}.`,
@@ -134,5 +158,5 @@ export function finishOutcome(
 		};
 	}
 	if (output.trim()) return { output, toolCalls, usage, actions };
-	return { output: "Subagent produced no output.", toolCalls, usage, actions, failed: true };
+	return { output: "(Subagent completed but returned no output.)", toolCalls, usage, actions };
 }