one-code-extension 0.1.4 → 0.3.1

package/extensions/subagents/model-select.ts

@@ -16,15 +16,30 @@
  * child is spawned with a concrete `provider/id`:
  *
  * - Claude Code aliases (`sonnet`/`opus`/`haiku`/`fable`) resolve **within the
- *   session's provider** (and contained route/model family on gateways); where the name
- *   matches nothing, the session model serves and the parent says so.
- * - An exact model reference resolves anywhere — the user (or an agent file the
- *   user installed) naming a model is choosing it — but crossing providers is
- *   announced, never silent.
- * - A configured default that cannot resolve degrades to the session model with
- *   a notice naming the knob; without one, a reviewed same-provider role profile
- *   chooses an economical default before the session fallback. Only a bad
- *   *per-call* request errors, because the model can read the menu and retry.
+ *   session's provider** (and contained route/model family on gateways): by
+ *   name where a model carries it, else as the Claude Code *tier* the alias
+ *   names — `haiku` the cheapest capable contained model, `sonnet` the cheapest
+ *   workhorse-class one, `opus`/`fable` the session model — and the parent says
+ *   so (2026-09-11; before, an off-family alias landed on the session model,
+ *   the most expensive answer available, and a global "use Sonnet for
+ *   subagents" instruction did exactly that on every non-Anthropic provider).
+ * - An exact per-call reference (the main model's `model` field) or the user's
+ *   own `subagentModel` setting resolves anywhere — naming a model is choosing
+ *   it — but crossing providers is announced, never silent.
+ * - An `.claude/agents` model field is a Claude Code convention: honored on a
+ *   Claude-family session, but on any other provider a cross-provider one is
+ *   *not* honored (a fork inherits the parent transcript, so subagents stay on
+ *   the session's provider) — the configured default or the automatic
+ *   same-provider profile serves instead.
+ * - A configured default or agent-file model that cannot resolve degrades, with
+ *   a notice naming the knob, to the automatic same-provider pick — the
+ *   cheapest contained model at the session's capability floor, the SAME floor
+ *   the auto-mode classifier applies (`capableContainedCandidates`) — and only
+ *   then to the session model. Only an explicit `inherit` names the session
+ *   model outright. A bad *per-call* request first falls through to the agent's
+ *   own model and the configured default (running the subagent on its intended
+ *   model, with a notice); only when nothing downstream resolves does it error,
+ *   so the model can read the menu and retry.
  *
  * The menu keeps the main model informed without dumping a 300-model gateway
  * catalog into every request: vendor-contained, variant- and unpriced-filtered,
@@ -33,16 +48,19 @@
  */
 
 import type { Api, Model } from "@earendil-works/pi-ai";
+import type { SubagentDefault } from "./default-model.ts";
 import {
-	allowsDynamicSubagentSelection,
+	crossesProvider,
 	findConfigured,
-	findRoleProfileModel,
-	hasSmallModelName,
-	hintRank,
-	modelIdentity,
+	isClaudeFamilyModel,
+	isDatedDuplicate,
+	isSnapshotDatedId,
+	isStaleContainmentStamp,
 	modelsContainedToSession,
+	modelSpec as spec,
 	pricedInput,
 } from "../lib/model-policy.ts";
+import { atLeastTier, capableContainedCandidates, economicalContainedCandidates, intrinsicTier, type PromptTier } from "../lib/model-tier.ts";
 
 /**
  * Cross-extension channel carrying the resolved default subagent model, so the
@@ -82,8 +100,13 @@ export function subagentStatusModel(
 	return { model: spec(resolution.model), via };
 }
 
-/** Claude Code's Agent-tool aliases, resolved as name matches within the session's provider. */
-const CLAUDE_CODE_ALIASES = new Set(["sonnet", "opus", "haiku", "fable"]);
+/**
+ * Claude Code's Agent-tool aliases, read as the tiers they name: `haiku` the
+ * cheap line, `sonnet` the workhorse line, `opus`/`fable` the frontier. An alias
+ * resolves by NAME within the session's provider family when a model carries it
+ * (an Anthropic session), else as its tier there — see `resolveAlias`.
+ */
+const ALIAS_TIER: Record<string, PromptTier> = { haiku: "cheap", sonnet: "workhorse", opus: "frontier", fable: "frontier" };
 
 export type SubagentModelSource = "call" | "agent" | "default" | "automatic" | "session";
 
@@ -92,8 +115,14 @@ export interface ResolveInput {
 	requested?: string;
 	/** The agent definition's frontmatter `model`. */
 	agentModel?: string;
-	/** CLAUDE_CODE_SUBAGENT_MODEL / `subagentModel` setting, user or managed scope. */
-	configuredDefault?: string;
+	/**
+	 * The `subagentModel` setting / `CLAUDE_CODE_SUBAGENT_MODEL`, with its knob
+	 * (`source`) and, for the setting, the session provider it was stamped for
+	 * (`setForProvider`). A cross-provider setting stamped for a provider since
+	 * left — or unstamped (hand-edited) — is stale and skipped so a same-provider
+	 * model runs; see the resolve loop.
+	 */
+	configuredDefault?: SubagentDefault;
 	sessionModel?: Model<Api>;
 	available: Model<Api>[];
 }
@@ -111,28 +140,81 @@ export interface SubagentModelResolution {
 	notices: string[];
 }
 
-const spec = (model: Model<Api>): string => `${model.provider}/${model.id}`;
+/**
+ * The model-facing form of a resolution's notices, for the spawn tool's result.
+ *
+ * Every notice above says what was NOT honored ("falling back to the agent's
+ * configured model or the session default"); none of them names where the walk
+ * actually landed, because it is written before the chain finishes. The user
+ * can see the answer in the banner, but the model that asked for `sonnet` could
+ * not: on a non-Anthropic session — where a global "use Sonnet for subagents"
+ * memory shared with Claude Code makes that the standing request — it spawned
+ * children believing they ran on Sonnet and reasoned about their cost and
+ * capability on that basis (WEAK-MODEL-REVIEW-2026-09-06 L4).
+ *
+ * So the concrete spec is appended whenever there is a notice at all. It is
+ * stated rather than inferred even when a notice already mentions that spec:
+ * the notices name models in every position — the session ("no sonnet model in
+ * this session's provider family (openai/gpt-5.1)"), the one refused, the one
+ * honored — and a reader cannot tell which mention is the answer.
+ *
+ * The source rides along because it is the question the answer raises. The
+ * notices used to end by listing which knob might serve next; naming the one
+ * that actually did is the same information after the fact, and true.
+ */
+const SOURCE_LABEL: Record<SubagentModelSource, string> = {
+	call: "the model this call named",
+	agent: "the agent's own model",
+	default: "the configured default",
+	automatic: "the automatic smaller default",
+	session: "this session's model",
+};
+
+export function subagentModelNotes(resolution: Pick<SubagentModelResolution, "model" | "notices" | "source">): string[] {
+	if (resolution.notices.length === 0) return [];
+	if (!resolution.model) return [...resolution.notices];
+	return [...resolution.notices, `This subagent runs on ${spec(resolution.model)} (${SOURCE_LABEL[resolution.source]}).`];
+}
 
-const isDated = (id: string): boolean => /-20\d{6}$/.test(id);
+interface AliasResolution {
+	model: Model<Api>;
+	/** "name": a contained model carries the alias; "tier": the alias's Claude Code tier, resolved here. */
+	how: "name" | "tier";
+}
 
 /**
- * Resolve a Claude Code alias by name within the contained set, preferring
- * undated alias ids and then the newest id. Returns undefined off-family —
- * "sonnet" on a Groq session names nothing, and inventing a mapping would be
- * choosing a model the user never described.
+ * Resolve a Claude Code alias within the session's provider family: by name
+ * first (preferring undated alias ids, then the newest id), else as the tier
+ * the alias names — the cheapest contained model at or above it
+ * (`economicalContainedCandidates` order: never tiny, prior-generation or
+ * tool-less; cheap → workhorse → frontier, then price), `frontier` meaning the
+ * session model itself, the strongest model the user chose on this provider.
+ * Never off-family: "sonnet" on a Codex session is the cheapest workhorse-class
+ * Codex model, not Anthropic's Sonnet. The aliases ARE Claude Code's tier
+ * names, so the tier reading honors what the alias meant rather than
+ * substituting a model nobody described. Undefined only when the provider has
+ * nothing capable to offer (unpriced/opaque) or there is no session model.
  */
-function resolveAlias(alias: string, contained: Model<Api>[]): Model<Api> | undefined {
+function resolveAlias(
+	alias: string,
+	contained: Model<Api>[],
+	available: Model<Api>[],
+	sessionModel: Model<Api> | undefined,
+): AliasResolution | undefined {
 	const matches = contained.filter((model) => model.id.toLowerCase().includes(alias));
-	if (matches.length === 0) return undefined;
-	const undated = matches.filter((model) => !isDated(model.id));
-	const pool = undated.length > 0 ? undated : matches;
-	return pool.sort((a, b) => b.id.localeCompare(a.id))[0];
-}
-
-/** Whether an explicit model leaves the session's provider/route/family boundary. */
-export function crossesProvider(model: Model<Api>, sessionModel: Model<Api>): boolean {
-	if (model.provider !== sessionModel.provider) return true;
-	return modelIdentity(model).containment !== modelIdentity(sessionModel).containment;
+	if (matches.length > 0) {
+		const undated = matches.filter((model) => !isSnapshotDatedId(model.id));
+		const pool = undated.length > 0 ? undated : matches;
+		return { model: pool.sort((a, b) => b.id.localeCompare(a.id))[0], how: "name" };
+	}
+	if (!sessionModel) return undefined;
+	const tier = ALIAS_TIER[alias];
+	if (tier === "frontier") return { model: sessionModel, how: "tier" };
+	// Name-class only, deliberately: an explicit alias asks for a *class* of model,
+	// so a measured pass (which lets a strong flash serve the automatic default)
+	// does not lift a lean-named model into "sonnet" here.
+	const byTier = economicalContainedCandidates(available, sessionModel, contained).find((model) => atLeastTier(intrinsicTier(model), tier));
+	return byTier ? { model: byTier, how: "tier" } : undefined;
 }
 
 export function resolveSubagentModel(input: ResolveInput): SubagentModelResolution {
@@ -143,11 +225,23 @@ export function resolveSubagentModel(input: ResolveInput): SubagentModelResoluti
 	if (input.requested) chain.push({ value: input.requested, source: "call", knob: "the model field" });
 	if (input.agentModel) chain.push({ value: input.agentModel, source: "agent", knob: "the agent file's model" });
 	if (input.configuredDefault) {
-		chain.push({ value: input.configuredDefault, source: "default", knob: "the configured subagent default" });
+		chain.push({ value: input.configuredDefault.spec, source: "default", knob: "the configured subagent default" });
 	}
 
 	const contained = sessionModel ? modelsContainedToSession(available, sessionModel) : [];
 	let suppressAutomatic = false;
+	// A per-call `model` that did not resolve — deferred, not errored (see the
+	// "per-call request" paragraph in the module doc above).
+	let callFailed: string | undefined;
+
+	// The `subagentModel` setting is stale when it was stamped for a different
+	// provider than this session (or never stamped — a hand-edited setting): the
+	// user switched the session's provider since setting it, so a cross-provider
+	// value is not honored and a same-provider model runs instead. A deliberate
+	// choice made on this provider (stamp matches) is still honored + announced.
+	const settingIsStale =
+		input.configuredDefault?.source === "subagentModel setting" &&
+		isStaleContainmentStamp(input.configuredDefault.setForContainment, sessionModel);
 
 	for (const entry of chain) {
 		const wanted = entry.value.trim();
@@ -157,19 +251,57 @@ export function resolveSubagentModel(input: ResolveInput): SubagentModelResoluti
 		}
 
 		const alias = wanted.toLowerCase();
-		if (CLAUDE_CODE_ALIASES.has(alias)) {
-			const resolved = resolveAlias(alias, contained);
-			if (resolved) return { model: resolved, source: entry.source, notices };
-			notices.push(
-				`No "${alias}" model exists within ${sessionModel ? spec(sessionModel) : "this session"} — the session model runs this subagent instead.`,
-			);
-			suppressAutomatic = true;
-			break;
+		if (alias in ALIAS_TIER) {
+			const resolved = resolveAlias(alias, contained, available, sessionModel);
+			if (resolved?.how === "name") return { model: resolved.model, source: entry.source, notices };
+			// SCOPE the claim. "No sonnet model exists" is false at machine level
+			// whenever Anthropic is also authenticated, and a model relaying it tells
+			// the user "Sonnet is not available" — wrong, and the everyday case given
+			// a global "use Sonnet for subagents" memory on another provider. What is
+			// true is narrower: the alias cannot leave this session's containment.
+			// "Provider family" covers both a plain provider and a gateway, where
+			// containment is the model-creator namespace (`modelsContainedToSession`).
+			const family = sessionModel ? ` (${spec(sessionModel)})` : "";
+			if (resolved) {
+				// The tier reading: what the alias meant, on this provider. Stated so
+				// the model that asked for "sonnet" knows which model actually runs
+				// (WEAK-MODEL-REVIEW-2026-09-06 L4) — `subagentModelNotes` repeats the
+				// spec, but this line says WHY it is not Sonnet.
+				notices.push(`No "${alias}" model in this session's provider family${family}; read as its Claude Code tier, "${alias}" resolves to ${spec(resolved.model)} here.`);
+				return { model: resolved.model, source: entry.source, notices };
+			}
+			// Nothing capable contained at all (an unpriced/opaque provider, or no
+			// session model): keep walking the chain — the agent's model / configured
+			// default may still resolve — then the automatic pick or the session
+			// model serve below. Never `unresolved`: unlike a literal typo, an
+			// off-family alias is a naming mismatch, not a retryable mistake.
+			notices.push(`No "${alias}" model in this session's provider family${family}.`);
+			continue;
 		}
 
 		const resolved = findConfigured(available, wanted);
 		if (resolved) {
 			if (sessionModel && crossesProvider(resolved, sessionModel)) {
+				// An `.claude/agents` model is a Claude Code convention; on a
+				// non-Claude session it does not get to move a subagent (which
+				// inherits the parent transcript) onto another provider. Skip it and
+				// let the configured default or the automatic same-provider profile
+				// serve. Per-call `model` and the user's own `subagentModel` setting
+				// are explicit choices, so their crossings are still honored + announced.
+				if (entry.source === "agent" && !isClaudeFamilyModel(sessionModel)) {
+					notices.push(
+						`The agent file's model ${spec(resolved)} is a different provider than this session (${spec(sessionModel)}); ` +
+							"on a non-Claude session subagents stay on this provider, so a same-provider model runs this subagent instead.",
+					);
+					continue;
+				}
+				if (entry.source === "default" && settingIsStale) {
+					notices.push(
+						`The configured subagent default ${spec(resolved)} was set for a different provider than this session (${spec(sessionModel)}); ` +
+							"a same-provider model runs this subagent instead. Re-set it with /subagent on this session to use it here.",
+					);
+					continue;
+				}
 				notices.push(
 					`Subagent model ${spec(resolved)} is a different provider/family than this session (${spec(sessionModel)}) — it was named via ${entry.knob}, so it is honored.`,
 				);
@@ -178,45 +310,53 @@ export function resolveSubagentModel(input: ResolveInput): SubagentModelResoluti
 		}
 
 		if (entry.source === "call") {
-			// The main model chose this string; give it the menu and let it retry.
-			return { source: "call", unresolved: wanted, notices };
+			// Defer to the rest of the chain (see the module doc): record the
+			// failure and keep walking, erroring after the loop only if nothing
+			// downstream resolves.
+			callFailed = wanted;
+			notices.push(
+				`Requested subagent model "${wanted}" is not available — falling back to the agent's configured model or the session default.`,
+			);
+			continue;
 		}
-		// An explicit choice failed; automatic selection would substitute a model
-		// nobody described, so the remaining chain and the session model serve.
-		suppressAutomatic = true;
+		// An explicit choice failed: the rest of the chain, then the automatic
+		// same-provider pick, then the session model serve. The automatic pick is
+		// no more "a model nobody described" than the session model is, and it is
+		// the cheaper of the two (2026-09-11; before, this dropped straight to the
+		// session model).
 		notices.push(
 			entry.source === "agent"
-				? `Subagent model "${wanted}" (from ${entry.knob}) is not available — falling back to the configured default or the session model.`
-				: `Subagent model "${wanted}" (from ${entry.knob}) is not available — the session model runs this subagent instead.`,
+				? `Subagent model "${wanted}" (from ${entry.knob}) is not available — falling back to the configured default, the automatic same-provider pick, or the session model.`
+				: `Subagent model "${wanted}" (from ${entry.knob}) is not available — the automatic same-provider pick or the session model runs this subagent instead.`,
 		);
 	}
 
+	// Per-call model failed and nothing downstream resolved: surface it so the
+	// caller shows the menu and the model retries, rather than silently dropping
+	// to the automatic/session pick for a model the main model named.
+	if (callFailed) return { source: "call", unresolved: callFailed, notices };
+
 	// Automatic selection is a cost optimisation, so it needs price evidence:
-	// with either price unknown there is no demonstrable saving, and the profile
-	// order alone could silently *upgrade* a cheap session (haiku → sonnet).
-	const sessionPrice = sessionModel ? pricedInput(sessionModel) : undefined;
-	if (sessionModel && sessionPrice !== undefined && !suppressAutomatic) {
-		const isDifferentAndCheaper = (model: Model<Api>) => {
-			if (spec(model) === spec(sessionModel)) return false;
-			const candidatePrice = pricedInput(model);
-			return candidatePrice !== undefined && candidatePrice < sessionPrice;
-		};
-		const profiled = findRoleProfileModel(available, sessionModel, "subagent", isDifferentAndCheaper);
-		if (profiled) return { model: profiled, source: "automatic", notices };
-
-		// Price-ranked fallback for a stale profile. A name hint is required and
-		// ranks first: raw cheapest would pick nano/lite-tier (or wholly unknown)
-		// models as the default *coding* worker, so mini-class wins over a cheaper
-		// nano, and a model nobody labelled small never wins at all.
-		if (allowsDynamicSubagentSelection(sessionModel)) {
-			const cheaper = contained
-				.map((model) => ({ model, price: pricedInput(model), rank: hintRank(model) }))
-				.filter((entry): entry is { model: Model<Api>; price: number; rank: number } => entry.price !== undefined)
-				.filter((entry) => spec(entry.model) !== spec(sessionModel))
-				.filter((entry) => entry.price < sessionPrice && hasSmallModelName(entry.model))
-				.sort((a, b) => a.rank - b.rank || a.price - b.price)[0]?.model;
-			if (cheaper) return { model: cheaper, source: "automatic", notices };
-		}
+	// with the session price unknown there is no demonstrable saving, and picking
+	// a cheap-tier model could silently *upgrade* an (unpriced) cheap session. The
+	// floor-gated selector — the cheapest same-provider model at the session's
+	// capability floor (workhorse-or-better for a workhorse-or-better session,
+	// Claude Code's min(main, sonnet); never `tiny`) — is the SAME one the
+	// auto-mode classifier uses, so a session screens and delegates on one
+	// model. A delegated worker writes code and calls tools for many turns; a
+	// weaker one spends the saving on retries (2026-09-11 — before, subagents
+	// took the cheapest capable model with no floor). It excludes unpriced/opaque
+	// providers by construction, which subsumes the old dynamic-selection gate;
+	// those degrade to the session model below.
+	if (sessionModel && !suppressAutomatic) {
+		// `strict` requires a genuinely cheaper model and yields nothing when the
+		// session price is unknown, so a cheap-tier pick never silently upgrades an
+		// unpriced session. Reuse the `contained` set computed above for the hot path.
+		// With an Artificial Analysis snapshot (lib/capability-index.ts) the floor
+		// is measured — coding index ≥ min(session, Sonnet 5), no tolerance —
+		// and passers rank by price; unscored candidates are judged by name-class tier.
+		const cheaper = capableContainedCandidates(available, sessionModel, "subagent", { strict: true, contained })[0];
+		if (cheaper) return { model: cheaper, source: "automatic", notices };
 	}
 
 	if (sessionModel) return { model: sessionModel, source: "session", notices };
@@ -259,6 +399,13 @@ export interface MenuOptions {
 	defaultSource?: SubagentModelSource;
 	/** How many cheaper-option lines to include. */
 	maxCheaper?: number;
+	/**
+	 * The configured default and which knob set it, so the reminder can tell the
+	 * main model when the user has *manually* pinned the subagent model via the
+	 * `subagentModel` setting (as opposed to Claude Code's env var or automatic
+	 * selection). Only the setting triggers the notice.
+	 */
+	configured?: SubagentDefault;
 }
 
 const price = (model: Model<Api>): string => {
@@ -297,11 +444,7 @@ export function subagentModelMenu({ available, sessionModel, defaultModel, defau
 			.map((model) => ({ model, input: pricedInput(model) }))
 			.filter((entry): entry is { model: Model<Api>; input: number } => entry.input !== undefined)
 			// Collapse dated duplicates when the undated alias is also present.
-			.filter(
-				(entry) =>
-					!isDated(entry.model.id) ||
-					!contained.some((other) => other.id !== entry.model.id && entry.model.id.startsWith(other.id)),
-			)
+			.filter((entry) => !isDatedDuplicate(entry.model, contained))
 			.sort((a, b) => a.input - b.input);
 		const sessionPrice = pricedInput(sessionModel);
 		for (const entry of priced) {
@@ -332,15 +475,42 @@ export function defaultCostsMoreWarning({ sessionModel, defaultModel }: MenuOpti
 	);
 }
 
+/**
+ * One line informing the main model when the user has manually pinned the
+ * subagent default via the `subagentModel` setting — so the model knows what
+ * subagents run on, and (when that model is a different provider than the
+ * session) that it can keep a subagent's inherited transcript on this provider
+ * by passing a listed same-provider model. Silent for the automatic default and
+ * for Claude Code's env var, which are not the user's manual per-harness choice.
+ */
+export function settingOverrideNotice({ sessionModel, defaultModel, defaultSource, configured }: MenuOptions): string | undefined {
+	// Only when the setting is actually in effect: a stale cross-provider setting
+	// that was overridden resolves to an automatic/session model (defaultSource
+	// != "default"), and its user-facing "set for a different provider" warning
+	// already explains the override — no "runs on it" line for the model then.
+	if (configured?.source !== "subagentModel setting" || defaultSource !== "default" || !defaultModel) return undefined;
+	const cross = sessionModel && crossesProvider(defaultModel, sessionModel);
+	return (
+		`The user pinned the subagent default to ${spec(defaultModel)} via the subagentModel setting; ` +
+		"subagents run on it unless you pass a different model in the `model` field" +
+		(cross
+			? ` — it is a different provider than this session (${spec(sessionModel as Model<Api>)}), so a subagent's inherited transcript goes to that provider; pass a listed same-provider model to keep it here.`
+			: ".")
+	);
+}
+
 /** The every-turn reminder body. Kept short: its tokens are paid on every call. */
 export function subagentModelsReminder(options: MenuOptions): string {
 	const menu = subagentModelMenu(options);
+	const setting = settingOverrideNotice(options);
 	const warning = defaultCostsMoreWarning(options);
 	return [
 		"Models for the subagent/workflow `model` field (omit it to use the default; set the default with /subagent):",
 		...menu,
+		...(setting ? [setting] : []),
 		...(warning ? [warning] : []),
-		'Aliases sonnet|opus|haiku|fable resolve within this session\'s provider; "inherit" means the session model. ' +
+		"Aliases sonnet|opus|haiku|fable resolve within this session's provider — by name when a model carries it, else as the tier it names " +
+			'(haiku: the cheapest capable model, sonnet: the cheapest workhorse-class model, opus/fable: this session\'s model); "inherit" means the session model. ' +
 			"Any exact provider/model-id the user asked for also works, even from another provider (that is announced to the user) or unlisted here — this is a menu, not a whitelist.",
 	].join("\n");
 }

package/extensions/subagents/outcome.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared result/handle contracts for a subagent run, plus the fork framing.
+ * (These outlived child.ts, the retired process-spawning runner; the runner is
+ * now in-process — see runner.ts.)
+ */
+
+import type { ChildAction } from "../auto-mode/actions.ts";
+import type { UsageTotals } from "./usage.ts";
+
+export const OUTPUT_CAP = 50_000;
+
+/** A fork running in an isolation worktree: where it is, and where the inherited paths pointed. */
+export interface ForkIsolation {
+	worktreePath: string;
+	parentCwd: string;
+}
+
+/**
+ * Framing wrapped around a fork child's task. A fork inherits the parent's
+ * entire transcript; without this, a weaker model tends to abandon its assigned
+ * task and continue (or confabulate about) the inherited topic — then its output
+ * returns to the parent looking like independent confirmation. See
+ * docs/features/tools/records/tool-ambiguity-hardening.md (fork confabulation).
+ *
+ * With `isolation`, the fork is told that its working directory moved: the
+ * inherited system prompt and transcript name the parent's checkout in every
+ * path, so without this line a worktree fork edits the main tree (the guard in
+ * lib/worktree-isolation.ts then refuses the write, but the model needs to know
+ * where to write instead — SUBAGENT-REVIEW H3).
+ */
+export function forkTaskMessage(task: string, isolation?: ForkIsolation): string {
+	const lines = [
+		"You are a forked subagent. The conversation above is inherited context, for reference only — do NOT continue its open threads, verify its claims, or act on its plans. Do ONLY the task below; your final message is returned to the parent conversation verbatim, as data. You cannot see the parent's background tasks: its task ids are not addressable from here.",
+	];
+	if (isolation) {
+		lines.push(
+			"",
+			`You are isolated in your own git worktree: your working directory is now ${isolation.worktreePath}, a checkout of the same repository at HEAD. Every path under ${isolation.parentCwd} in the inherited context refers to the shared checkout, which you must NOT modify — read, edit and run things at the corresponding path under ${isolation.worktreePath} instead (writes into the shared checkout are refused). Your changes stay on this worktree's branch for the parent to review.`,
+		);
+	}
+	lines.push("", "Task:", task);
+	return lines.join("\n");
+}
+
+export interface ChildOutcome {
+	output: string;
+	toolCalls: number;
+	usage: UsageTotals;
+	failed?: boolean;
+	/**
+	 * What the child actually did, names and short subjects only. Auto mode
+	 * reviews this when the child returns, to catch a sequence whose individual
+	 * steps each passed. Never carries tool output — see auto-mode/actions.ts.
+	 */
+	actions: ChildAction[];
+}
+
+/** A blocking run handle: await the result, or kill/snapshot it while it runs. */
+export interface ChildHandle {
+	result: Promise<ChildOutcome>;
+	kill(): void;
+	snapshot(): { toolCalls: number; text: string; usage: UsageTotals };
+}
+
+/** A resident (background) agent handle: message it live, inspect it, stop it. */
+export interface RpcChildHandle {
+	/**
+	 * Deliver a message. "started" = the agent was idle and this began a new turn
+	 * (resolves as soon as the turn is dispatched, not when it ends); "steered" =
+	 * the agent was mid-turn and the message joined it. Rejects when the message
+	 * could not be queued at all (pi refuses to steer an extension command), so
+	 * the caller never reports a delivery that did not happen.
+	 */
+	send(message: string): Promise<"started" | "steered">;
+	busy(): boolean;
+	exited(): boolean;
+	/**
+	 * Abort any in-flight turn (reported as terminated) and dispose the session.
+	 * Resolves once the abort has settled and the session is disposed (so a
+	 * shutdown can wait for the exit-time cleanup, e.g. worktree removal).
+	 */
+	kill(): Promise<void>;
+	/**
+	 * Dispose an IDLE session quietly — no turn outcome, no notification. A
+	 * no-op mid-turn. Its persisted session file remains, so SendMessage still
+	 * reaches the agent by resuming from disk instead of live.
+	 */
+	release(): void;
+	snapshot(): { toolCalls: number; text: string; usage: UsageTotals };
+}

package/extensions/subagents/panel-keys.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure key decoding for the below-editor panel — Claude Code's agent-tree
+ * keys. Their meaning depends on whether a transcript view is open (index.ts
+ * owns that split): with no view open, arrows select and Enter opens the
+ * selected agent's transcript; while a view IS open the panel is in "read"
+ * mode, where arrows scroll it a line at a time, PageUp/PageDown scroll a page,
+ * `switch` (Tab) retargets to the next agent, `left` (←) closes the transcript
+ * back to agent selection, and Enter closes it. `x` stops, the `ctrl+x ctrl+k`
+ * chord stops all, esc leaves. `left` also serves the shell-panel stages (back)
+ * and `space` (close); the agents branch uses `left` in read mode (above) and
+ * treats `space` like typing. Raw terminal bytes in, intents out — no side
+ * effects, fully unit-testable.
+ */
+
+const UP = new Set(["\x1b[A", "\x1bOA"]);
+const DOWN = new Set(["\x1b[B", "\x1bOB"]);
+const LEFT = new Set(["\x1b[D", "\x1bOD"]);
+
+export type StripKey = "up" | "down" | "left" | "space" | "switch" | "open" | "leave" | "stop" | "stopAll" | "pageUp" | "pageDown";
+
+/**
+ * Decoder with chord state: `ctrl+x` (\x18) arms the chord (consumed, no key);
+ * a following `ctrl+k` (\x0b) completes it into `stopAll`; any other key
+ * cancels the chord and is decoded normally. A byte that decodes to nothing
+ * (typing) is the caller's signal to drop focus and let the byte through.
+ */
+export function decodeStripKey(data: string, chordArmed: boolean): { key?: StripKey; chordArmed: boolean } {
+	if (chordArmed && data === "\x0b") return { key: "stopAll", chordArmed: false };
+	if (data === "\x18") return { chordArmed: true };
+	if (UP.has(data)) return { key: "up", chordArmed: false };
+	if (DOWN.has(data)) return { key: "down", chordArmed: false };
+	if (LEFT.has(data)) return { key: "left", chordArmed: false };
+	if (data === "\t") return { key: "switch", chordArmed: false };
+	if (data === " ") return { key: "space", chordArmed: false };
+	if (data === "\r" || data === "\n") return { key: "open", chordArmed: false };
+	if (data === "\x1b") return { key: "leave", chordArmed: false };
+	if (data === "x" || data === "X") return { key: "stop", chordArmed: false };
+	if (data === "\x1b[5~") return { key: "pageUp", chordArmed: false };
+	if (data === "\x1b[6~") return { key: "pageDown", chordArmed: false };
+	return { chordArmed: false };
+}