one-code-extension 0.5.0 → 0.6.0

package/extensions/subagents/index.ts

@@ -29,7 +29,7 @@ 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, agentFileSources, BUNDLED_AGENTS_DIR, discoverAgents } from "./agents.ts";
+import { type AgentDefinition, agentFileSources, agentSourcesStamp, 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";
@@ -53,7 +53,7 @@ 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 { DEFER_CHANNEL, queryDeferred } from "../lib/deferred.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";
@@ -63,10 +63,10 @@ import { type DescriptionForm, followDescriptionForm, registerVariantTool } from
 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 { pendingClaimReminder, runningAfterCompactionReminder } from "./pending-claim.ts";
 import { watchPermissionBridge } from "../permissions/subagent-gate.ts";
 import { watchHookBridge } from "../hooks/subagent-bridge.ts";
-import { CONTEXT_ORDER, REMINDER_CHANNEL, type ReminderPayload } from "../lib/reminders.ts";
+import { CONTEXT_ORDER, REMINDER_CHANNEL, RENDER_CHANNEL, type RenderRequest, type ReminderPayload, toldBlockFact } 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";
@@ -112,8 +112,7 @@ import { createMarkdownProse } from "./prose.ts";
 import { asScrollableViewport, ViewportMirror } from "./viewport-mirror.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
 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 { readStringsState, recordState } from "../lib/ledger/state.ts";
 import { panelUi } from "../lib/panel-focus.ts";
 import { dockRowsReporter, trackDockRows } from "../lib/dock-rows.ts";
 
@@ -229,6 +228,15 @@ const SubagentParams = Type.Object({
 });
 
 
+/** The Agent tool's schema inside a non-fork child: the nested run's options only. */
+const NESTED_AGENT_PARAMS = Type.Object({
+	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>)" })),
+});
+
 /**
  * The anti-fabrication sentence, carried by the tool RESULT of a background
  * spawn and not only by the Agent tool's description. Claude Code puts it in the
@@ -274,6 +282,16 @@ function residentPending(resident: Resident): boolean {
 	return !resident.handle.exited() && (resident.handle.busy() || resident.turnHandlers.length > 0 || resident.reviewing > 0);
 }
 
+/** The three capability blocks subagents owns on message 1. */
+type SubagentBlockKey = "subagent-models" | "subagent-agents" | "subagent-delegation";
+const BLOCK_ORDER: Record<SubagentBlockKey, number> = {
+	"subagent-models": CONTEXT_ORDER.subagentModels,
+	"subagent-agents": CONTEXT_ORDER.agents,
+	"subagent-delegation": CONTEXT_ORDER.delegation,
+};
+/** The `one-code:state` key of the models this account refused (lib/model-unusable.ts). */
+const REFUSED_MODELS_STATE = "subagents:refused-models";
+
 export default function subagentsExtension(pi: ExtensionAPI) {
 	const requestTier = sessionModelTier(pi);
 	const registry = new RunRegistry();
@@ -410,6 +428,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	const rememberUnusable = (model: string) => {
 		if (unusableModels.has(model)) return false;
 		unusableModels.add(model);
+		// A refusal is a durable fact of the account, not UI prose: a resumed
+		// session must not pick the same model and announce it again.
+		recordState(pi, REFUSED_MODELS_STATE, [...unusableModels]);
 		return true;
 	};
 	pi.events.on(MODEL_UNUSABLE_CHANNEL, (data) => {
@@ -455,6 +476,9 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				if (lastCtx) emitModelStatus(lastCtx, lastCtx.model, model);
 			},
 			(path, agent) => pi.events.emit(CHILD_WROTE_CHANNEL, { path, ...(agent ? { agent } : {}) } satisfies ChildWrote),
+			() => queryDeferred(pi.events),
+			// The mode a fork's calls are checked in, read live at each of its requests (parent-mode.ts).
+			() => permissionMode,
 		).catch((error: unknown) => {
 			runtimePromise = undefined;
 			throw error;
@@ -519,13 +543,19 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		};
 	};
 
-	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.
+	// Plugin agents sit between bundled and user definitions, and are exposed
+	// namespaced (`<plugin>:<agent>`) so two plugins can ship the same name.
+	const agentSources = (cwd: string) => {
+		const plugins = discoverPlugins(defaultDiscoverRoots(getAgentDir(), cwd));
+		return { plugins, fileSources: agentFileSources(cwd, os.homedir(), plugins.agentDirs) };
+	};
+	type AgentSources = ReturnType<typeof agentSources>;
+
+	/** `sources` when the caller already resolved them (the catalog stamp). */
+	const loadAgents = (cwd: string, sources: AgentSources = agentSources(cwd)) => {
 		// 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);
+		const { plugins, fileSources } = sources;
 		// 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));
@@ -544,9 +574,11 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		return a.source === "built-in" || a.source.startsWith(BUNDLED_AGENTS_DIR) ? " (Tools: *)" : " (Tools: All tools)";
 	};
 
-	const describeAgents = (cwd: string) => {
-		const agents = loadAgents(cwd);
-		const lines = agents.map((a) => `- ${a.name}: ${a.description || "(no description)"}${toolsClause(a)}`);
+	/** One catalog row per agent, the shape every catalog the model reads uses. */
+	const catalogLines = (agents: AgentDefinition[]): string[] => agents.map((a) => `- ${a.name}: ${a.description || "(no description)"}${toolsClause(a)}`);
+
+	const describeAgents = (cwd: string, sources?: AgentSources) => {
+		const lines = catalogLines(loadAgents(cwd, sources));
 		lines.push(`- ${FORK_AGENT}: clone this conversation, with its full context, to work on a task in parallel`);
 		return lines.join("\n");
 	};
@@ -619,29 +651,46 @@ 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 });
+	// The three blocks are live state: what an epoch's message 1 says. Inside an
+	// epoch message 1 is the record (extensions/ledger), so a refused model, a
+	// /model or a /subagent change rides the request's tail, decided at render
+	// time from the text the epoch last told, never a rewrite of the menu that
+	// would re-cache the conversation and drop its earlier thinking (findings §46).
+	/** The live text of each block; null when the block is absent. */
+	const liveBlocks: Record<SubagentBlockKey, string | null> = { "subagent-models": null, "subagent-agents": null, "subagent-delegation": null };
+	/** A model the account refused since the menu was last told: its narrow correction stands in for the whole menu. */
+	let refusal: { refused: string[]; replacement: Model<Api> | undefined } | undefined;
+	const publishBlock = (key: SubagentBlockKey, text: string | null) => {
+		liveBlocks[key] = text;
+		if (text === null) pi.events.emit(REMINDER_CHANNEL, { key, remove: true });
+		else pi.events.emit(REMINDER_CHANNEL, { text, key, placement: "first-prepend", order: BLOCK_ORDER[key], facts: [toldBlockFact(key, text)] });
 	};
-	pi.on("context", () => {
-		requestSent = true;
+	pi.events.on(RENDER_CHANNEL, (data) => {
+		const request = data as RenderRequest;
+		if (request.epoch) {
+			refusal = undefined;
+			return;
+		}
+		for (const key of Object.keys(liveBlocks) as SubagentBlockKey[]) {
+			const text = liveBlocks[key];
+			// An absent block is told as its empty text; one never told needs no withdrawal.
+			const told = request.toldBlocks.get(key);
+			const fact = toldBlockFact(key, text ?? "");
+			if (told === fact.hash || (text === null && told === undefined)) continue;
+			const facts = [fact];
+			if (text === null) request.blocks.push({ text: "The subagent delegation guidance previously shown for this conversation is no longer active.", facts });
+			else if (key === "subagent-models" && refusal) request.blocks.push({ text: refusal.refused.map((model) => refusedModelNote(model, refusal?.replacement)).join("\n"), facts });
+			else request.blocks.push({ text, facts });
+		}
+		refusal = undefined;
 	});
 
 	/**
 	 * 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.
+	 * `refused` names a model the account just refused: inside an epoch that
+	 * change rides a narrow correction instead of the whole menu.
 	 */
-	const emitModelStatus = (ctx: ExtensionContext, sessionModel = ctx.model, refused?: string) => {
+	const modelMenu = (ctx: ExtensionContext, sessionModel = ctx.model) => {
 		const available = usableModels(ctx);
 		const configured = applicableSubagentDefault(loadSubagentDefault(os.homedir()), sessionModel);
 		const resolution = resolveAutoDefault(sessionModel, available, configured);
@@ -649,6 +698,10 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			available, sessionModel, defaultModel: resolution.model, defaultSource: resolution.source, configured,
 			requireImageInput: supportsImageInput(sessionModel),
 		});
+		return { available, configured, resolution, text };
+	};
+	const emitModelStatus = (ctx: ExtensionContext, sessionModel = ctx.model, refused?: string) => {
+		const { available, configured, resolution, text } = modelMenu(ctx, sessionModel);
 		for (const notice of resolution.notices) notifyModelOnce(ctx, notice);
 		// 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.
@@ -657,61 +710,38 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				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,
-		});
+		// Every refusal since the menu was last told, each named, with the default as it is now.
+		if (refused !== undefined) refusal = { refused: [...(refusal?.refused ?? []).filter((model) => model !== refused), refused], replacement: resolution.model };
+		else if (refusal) refusal = { ...refusal, replacement: resolution.model };
+		publishBlock("subagent-models", text);
 		pi.events.emit(SUBAGENT_STATUS_CHANNEL, subagentStatusModel(configured, resolution));
 	};
 
+	/** The last catalog text and the stamp of the agent files it was built from. */
+	let catalogMemo: { stamp: string; text: string } | undefined;
 	/**
 	 * The agent catalog as an every-turn reminder, as Claude Code does ("Available
 	 * agent types are listed in <system-reminder> messages") — without it the
-	 * model has to guess names or make a discovery call first. Keyed and
-	 * byte-stable within a session, so it costs nothing in prompt-cache terms.
+	 * model has to guess names or make a discovery call first. Rebuilt only when
+	 * the agent files changed: every run start asks, and stating the files is
+	 * cheaper than reading and parsing each one. The sources are resolved once
+	 * per check (the plugin discovery behind them is a process-wide memo), and a
+	 * rebuild reads the same ones the stamp stated.
 	 */
-	const emitAgentCatalog = (ctx: ExtensionContext) => {
-		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 agentCatalog = (ctx: ExtensionContext) => {
+		const sources = agentSources(ctx.cwd);
+		const stamp = `${ctx.cwd}\n${agentSourcesStamp(sources.fileSources)}`;
+		if (catalogMemo?.stamp !== stamp) {
+			catalogMemo = {
+				stamp,
+				text: `Available agent types for the Agent tool:\n${describeAgents(ctx.cwd, sources)}\n\nWhen you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.`,
+			};
+		}
+		return catalogMemo.text;
 	};
+	const emitAgentCatalog = (ctx: ExtensionContext) => publishBlock("subagent-agents", agentCatalog(ctx));
 
-	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 });
-	};
+	const emitDelegationSteer = () => publishBlock("subagent-delegation", requestTier() === "tiny" ? DELEGATION_STEER : null);
 
 	let shuttingDown = false;
 
@@ -725,6 +755,11 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		const tier = requestTier();
 		return tier === "cheap" || tier === "tiny";
 	};
+	/** A run that is still working: a live child, or a resident with a turn pending. */
+	const stillRunning = (taskId: string): boolean => {
+		const resident = residents.get(taskId);
+		return (resident !== undefined && residentPending(resident)) || runningIds.has(taskId);
+	};
 	pi.on("agent_start", () => {
 		spawnedThisLoop.clear();
 		parentBusy = true;
@@ -740,10 +775,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		// lookups below would be discarded work on every turn that delegated.
 		if (!backstopApplies()) return undefined;
 		const pending = spawned
-			.filter((taskId) => {
-				const resident = residents.get(taskId);
-				return (resident !== undefined && residentPending(resident)) || runningIds.has(taskId);
-			})
+			.filter(stillRunning)
 			.map((taskId) => registry.resolve(taskId))
 			.filter((record): record is AgentRunRecord => record !== undefined)
 			.map((record) => ({ name: record.name, taskId: record.taskId }));
@@ -753,17 +785,9 @@ 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);
+		// The account's refusals follow the branch: restore the selection floor
+		// before building the menu, or this process picks the refused model again.
+		for (const model of readStringsState(ctx, REFUSED_MODELS_STATE)) 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" /
@@ -789,7 +813,55 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		const live = liveUiCtx(lastCtx);
 		if (live) emitModelStatus(live);
 	});
-	pi.on("session_tree", (_event, ctx) => reconstructRuns(ctx));
+	/**
+	 * The main conversation's runs still going at the last compaction, and the
+	 * compaction entry they belong to: named on the next request, as far as
+	 * they are still going then.
+	 */
+	let runningAtCompaction: { entryId: string | undefined; taskIds: string[] } | undefined;
+	// A compaction opens an epoch, which renders the three blocks from live state:
+	// refresh them, so a catalog that changed on disk since is current. The calls
+	// that started the background runs went into the summary, so the runs still
+	// going are named once on the new epoch's first request. Only the main
+	// conversation's own runs: a nested run reports to the agent that spawned it.
+	pi.on("session_compact", (event, ctx) => {
+		emitModelStatus(ctx);
+		emitAgentCatalog(ctx);
+		emitDelegationSteer();
+		const taskIds = [...registry.list()].filter((record) => (record.depth ?? 0) === 0 && stillRunning(record.taskId)).map((record) => record.taskId);
+		runningAtCompaction = taskIds.length > 0 ? { entryId: event?.compactionEntry?.id, taskIds } : undefined;
+	});
+	// Named when the request is built, not at the compaction: the next request can
+	// come much later (a manual /compact waits for the next prompt), and a run that
+	// finished meanwhile is not running. The run's own notification says it ended.
+	// A /tree to a branch without that compaction still shows the calls.
+	pi.on("turn_start", (_event, ctx) => {
+		const owed = runningAtCompaction;
+		if (!owed) return;
+		runningAtCompaction = undefined;
+		if (owed.entryId !== undefined && !ctx.sessionManager.getBranch().some((entry) => entry.id === owed.entryId)) return;
+		const going = owed.taskIds
+			.filter(stillRunning)
+			.map((taskId) => registry.resolve(taskId))
+			.filter((record): record is AgentRunRecord => record !== undefined)
+			.map((record) => ({ name: record.name, taskId: record.taskId }));
+		const text = runningAfterCompactionReminder(going);
+		if (text) pi.events.emit(REMINDER_CHANNEL, { text, key: "subagents-running-after-compaction", untilCompaction: true });
+	});
+	// The catalog is read from disk at each run's start, so an agent file added
+	// or deleted mid-session reaches the model: the render step announces a
+	// changed catalog, live minus what the epoch told (R3-M28).
+	pi.on("before_agent_start", (_event, ctx) => {
+		emitAgentCatalog(ctx);
+	});
+	// The selected branch's runs: the abandoned branch's finished ones are not
+	// addressable from it (SendMessage, list_agents), as on a resume. A run still
+	// going, a resident between turns and a nested run (recorded only in memory)
+	// stay reachable, and so do names held for spawns in flight.
+	pi.on("session_tree", (_event, ctx) => {
+		registry.retain((record) => liveRuns.get(record.taskId)?.status === "running" || residents.has(record.taskId) || parentTaskOf.has(record.taskId));
+		reconstructRuns(ctx);
+	});
 	pi.on("session_shutdown", async () => {
 		// Teardown — at process exit AND on /clear, /new, /resume (pi replaces the
 		// session and re-runs this factory; afterwards every use of this
@@ -1440,9 +1512,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 	const childCatalog = (cwd: string): string => {
 		let text = childCatalogCache.get(cwd);
 		if (text === undefined) {
-			text = loadAgents(cwd)
-				.map((a) => `- ${a.name}: ${a.description || "(no description)"}${toolsClause(a)}`)
-				.join("\n");
+			text = catalogLines(loadAgents(cwd)).join("\n");
 			childCatalogCache.set(cwd, text);
 		}
 		return text;
@@ -1469,17 +1539,17 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 			// accepted as `task`, `description` is tolerated, and the agent name is
 			// matched case-insensitively — a nested subagent is just as likely to be
 			// CC-trained.
-			parameters: Type.Object({
-				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,
+			// A fork inherits the parent's tools block byte for byte (its first request
+			// extends the parent's recorded one, decisions/caching.md), so its spawn
+			// tool takes the parent's Agent schema: the ledger keeps the recorded
+			// declaration only while the live schema matches it, and pi validates the
+			// call against the live one. The options a nested run lacks are refused in
+			// execute() with the fix named.
+			parameters: (parentRecord.agent === FORK_AGENT ? SubagentParams : NESTED_AGENT_PARAMS) 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; description?: unknown };
+				const p = (params ?? {}) as { subagent_type?: unknown; task?: unknown; prompt?: unknown; name?: unknown; description?: unknown; model?: unknown; thinking?: unknown; isolation?: unknown; action?: 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 : "";
@@ -1488,10 +1558,13 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 				if (!ctx) return err("The host session is not ready to spawn agents — retry shortly.");
 				if (agentName.toLowerCase() === FORK_AGENT) return err('"fork" is only available to the main conversation — pick a named agent instead.');
 				const agents = loadAgents(parentRecord.cwd);
+				// Only a fork's schema (the parent's) offers these; a nested run has none of them.
+				if (p.action === "list") return { content: [{ type: "text" as const, text: `Available agents:\n${catalogLines(agents).join("\n")}` }], details: {} };
+				const unsupported = (["model", "thinking", "isolation"] as const).filter((key) => p[key] != null);
+				if (unsupported.length > 0) return err(`${unsupported.map((key) => `\`${key}\``).join(", ")} ${unsupported.length === 1 ? "is" : "are"} not available to an Agent call made inside a subagent: a nested agent runs blocking, in this agent's directory, on its definition's model. Call again without ${unsupported.length === 1 ? "it" : "them"}.`);
 				const agentDef = agents.find((a) => a.name.toLowerCase() === agentName.toLowerCase());
 				if (!agentDef) {
-					const catalog = agents.map((a) => `- ${a.name}: ${a.description || "(no description)"}${toolsClause(a)}`).join("\n");
-					return err(`${agentName ? `Unknown agent "${agentName}"` : "`subagent_type` is required"}. Available agents:\n${catalog}`);
+					return err(`${agentName ? `Unknown agent "${agentName}"` : "`subagent_type` is required"}. Available agents:\n${catalogLines(agents).join("\n")}`);
 				}
 				if (!task) return err("`task` is required: a complete, self-contained instruction for the agent (Claude Code names this parameter `prompt` — either is accepted).");
 
@@ -1608,7 +1681,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 		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(() => {
+		void resident.handle.send(fire.text(resident.handle.conversation)).catch(() => {
 			pi.events.emit(AGENT_CRON_CHANNEL, { op: "delete", agentId: fire.agentId, id: fire.jobId } satisfies AgentCronRequest);
 		});
 	});

package/extensions/subagents/outcome.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ChildAction } from "../auto-mode/actions.ts";
+import type { FireConversation } from "../lib/agent-cron.ts";
 import type { UsageTotals } from "./usage.ts";
 
 export const OUTPUT_CAP = 50_000;
@@ -72,6 +73,8 @@ export interface RpcChildHandle {
 	 * the caller never reports a delivery that did not happen.
 	 */
 	send(message: string): Promise<"started" | "steered">;
+	/** The agent's own session: a cron fire's `/loop` sentinel reads and records its delivery there (lib/agent-cron.ts). */
+	conversation: FireConversation;
 	busy(): boolean;
 	exited(): boolean;
 	/**

package/extensions/subagents/parent-mode.ts

@@ -0,0 +1,50 @@
+/**
+ * A fork's permission mode, told as the parent's (lifecycle-grid-hunt round 3,
+ * R3-L15). A fork's tool calls are checked by the parent's gate, in the
+ * parent's live mode, but the fork has no permissions or plan-mode extension
+ * of its own: its history shows the mode only as the sticky block it
+ * inherited at spawn. So the mode is live state with a told fact, like every
+ * capability owner's: at each request the fork renders, a mode that differs
+ * from what the fork was told (or, before any notice, from the mode its
+ * branch recorded at spawn) is announced on the tail, once. An epoch's request
+ * always tells it: an epoch renders the history from the stored messages, which
+ * hold neither the inherited block nor an earlier notice.
+ *
+ * An inline child extension; the getter reads the parent's live mode.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readState } from "../lib/ledger/state.ts";
+import { RENDER_CHANNEL, type RenderRequest, toldBlockFact } from "../lib/reminders.ts";
+import { PERMISSION_MODE_STATE } from "../permissions/modes.ts";
+import { normalizePermissionMode } from "../permissions/settings.ts";
+
+/** The told fact's key. */
+const PARENT_MODE_FACT = "parent-permission-mode";
+
+export function parentModeText(mode: string): string {
+	const plan = mode === "plan" ? " Only read-only tools run now: do not edit files or change state." : "";
+	return `The main session's permission mode is now "${mode}", and your tool calls are checked against it from here on.${plan}`;
+}
+
+export function parentModeExtension(getMode: () => string) {
+	return (pi: ExtensionAPI) => {
+		/** The mode the fork's branch recorded: the parent's at spawn, which the inherited history shows. */
+		let atSpawn: string | undefined;
+		pi.on("session_start", (_event, ctx) => {
+			atSpawn = normalizePermissionMode(readState(ctx, PERMISSION_MODE_STATE));
+		});
+		pi.events.on(RENDER_CHANNEL, (data) => {
+			const request = data as RenderRequest;
+			const live = getMode();
+			const fact = toldBlockFact(PARENT_MODE_FACT, live);
+			// The fork has no stack block to carry the mode, so an epoch tells it again.
+			if (request.epoch) {
+				request.blocks.push({ text: parentModeText(live), facts: [fact] });
+				return;
+			}
+			const told = request.toldBlocks.get(PARENT_MODE_FACT);
+			if (told === fact.hash || (told === undefined && atSpawn === live)) return;
+			request.blocks.push({ text: parentModeText(live), facts: [fact] });
+		});
+	};
+}

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, ` +