one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/deferred.ts

@@ -10,19 +10,75 @@
  * `{ name, keywords? }` while extensions are loading (before session_start).
  */
 
+import { createHash } from "node:crypto";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import { toolResultsOnBranch } from "./branch-restore.ts";
-import { parseClaudeVersion } from "./model-tier.ts";
+import { parseClaudeId } from "./claude-id.ts";
+import { leadingToolsItem, toolsItemFor } from "./ledger/wire.ts";
+import { RESPONSES_APIS } from "./system-role.ts";
+import { ADDENDUM_HEAD } from "./tool-additions.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
 
 export const DEFER_CHANNEL = "one-code:defer-tool";
 
+/**
+ * Take a deferred tool out of this session's surface (`{ name }`): it leaves the
+ * deferred registry and the active set, so no request carries it and
+ * `tool_search` cannot load it. An extension withholds its own tool when the
+ * session model must not have it (the task tools on frontier models) and
+ * re-emits DEFER_CHANNEL to bring it back after a model change. Before the
+ * first request the standing listing is rewritten without it; after that the
+ * listing stays frozen and a load reports "not found" (tool-search/announce.ts).
+ */
+export const WITHHOLD_CHANNEL = "one-code:withhold-tool";
+
 export interface DeferRequest {
 	name: string;
 	/** Extra search terms beyond the tool's name and description. */
 	keywords?: string[];
 }
 
+/**
+ * Ask the session's tool-search which tools it defers: emit a `DeferredQuery`
+ * and it adds one request per deferred tool. A subagent defers the same tools
+ * its parent injects into it (MCP, cron, SendMessage), whose owners run only
+ * in the parent.
+ */
+export const DEFERRED_QUERY_CHANNEL = "one-code:deferred-query";
+
+export interface DeferredQuery {
+	tools: DeferRequest[];
+}
+
+/** The tools this session defers, as its tool-search answers DEFERRED_QUERY_CHANNEL (none without one). */
+export function queryDeferred(events: { emit(channel: string, data: unknown): void }): DeferRequest[] {
+	const query: DeferredQuery = { tools: [] };
+	events.emit(DEFERRED_QUERY_CHANNEL, query);
+	return query.tools;
+}
+
+/**
+ * The tools a child gets from its parent rather than its own extensions: the
+ * shared MCP tools (`mcp__*`, which no child extension owns) and `extra`, the
+ * ones the caller injects by name (the spawn and cron tools).
+ */
+export function injectedByParent(extra: readonly { name: string }[]): (name: string) => boolean {
+	const names = new Set(extra.map((tool) => tool.name));
+	return (name) => name.startsWith("mcp__") || names.has(name);
+}
+
+/**
+ * An inline child extension that defers, at load, the parent's deferral of each
+ * tool `injected` names, whose owners run only in the parent. A tool the
+ * child's own extensions own stays theirs to defer or withhold per the child's
+ * model.
+ */
+export function deferLikeParentExtension(parentDeferred: readonly DeferRequest[], injected: (name: string) => boolean) {
+	return (pi: { events: { emit(channel: string, data: unknown): void } }) => {
+		for (const request of parentDeferred) if (injected(request.name)) pi.events.emit(DEFER_CHANNEL, request);
+	};
+}
+
 export interface SearchableTool {
 	name: string;
 	description: string;
@@ -49,6 +105,10 @@ export class DeferredRegistry {
 	has(name: string): boolean {
 		return this.entries.has(name);
 	}
+
+	remove(name: string): boolean {
+		return this.entries.delete(name);
+	}
 }
 
 // The one registry instance is constructed by its owner (tool-search/index.ts):
@@ -80,25 +140,50 @@ export function deferredReminderText(tools: Array<Pick<SearchableTool, "name"> &
  * this rides the tail instead, so the cached prefix holds.
  */
 export function deferredAddendumText(added: readonly string[]): string {
-	return [
-		"Additional deferred tools became available via tool_search since this conversation started (they registered after the first request). Same rules: load with tool_search \"select:<name>\" before calling.",
-		...added,
-	].join("\n");
+	return [ADDENDUM_HEAD, ...added].join("\n");
+}
+
+/**
+ * The one-shot that says deferred tools the conversation was told about are
+ * gone (their MCP server disconnected or was removed, a resume without it).
+ * The earlier listing or addendum stays in the history as sent, and so may
+ * the tool's declaration, so without this the model calls it and gets "Tool
+ * not found".
+ */
+export function deferredRemovedText(removed: readonly string[]): string {
+	return ["The following deferred tools are no longer available. tool_search cannot load them and calls to them fail; do not use them:", ...removed].join("\n");
 }
 
+/** The loader every deferred tool sits behind. */
+export const TOOL_SEARCH = "tool_search";
+
 /**
- * Whether Anthropic accepts client-side `tool_reference` blocks for this model —
- * pi-ai's `defaultSupportsToolReferences` rule, with the model's own compat flag
- * winning: first-party Anthropic, not Haiku, Claude 4.5 or newer.
+ * Whether deferral applies at all: `tool_search` is among pi's registered
+ * tools. A `--tools` allowlist that leaves it out (or `--exclude-tools
+ * tool_search`) unregisters it, and since pi 1.0.4 the allowlist keeps the
+ * `mcp__*` tools registered unless an entry names one (findings §66). Without
+ * the loader nothing can be loaded, so no tool is deferred or listed: the
+ * tools the allowlist kept stay as pi activated them.
+ */
+export function deferralEnabled(tools: readonly { name: string }[]): boolean {
+	return tools.some((tool) => tool.name === TOOL_SEARCH);
+}
+
+/**
+ * Whether Anthropic accepts client-side `tool_reference` blocks for this model,
+ * with the model's own compat flag winning: first-party Anthropic, Claude 4.5
+ * or newer, Haiku 4.5 and later Haikus included (they take references with no
+ * beta, and an eager append there rewrites the whole cache: findings §55 P4
+ * for Haiku 4.5, §67 for Haiku 5.5). Older Haikus stay out.
  */
 export function supportsToolReferences(
 	model: { provider?: string; id?: string; compat?: { supportsToolReferences?: boolean } } | undefined,
 ): boolean {
 	if (!model) return false;
 	if (typeof model.compat?.supportsToolReferences === "boolean") return model.compat.supportsToolReferences;
-	if (model.provider !== "anthropic" || !model.id || model.id.includes("haiku")) return false;
-	const version = parseClaudeVersion(model.id);
-	return version !== undefined && (version.major > 4 || (version.major === 4 && version.minor >= 5));
+	if (model.provider !== "anthropic" || !model.id) return false;
+	const version = parseClaudeId(model.id);
+	return version !== undefined && (version.major > 4 || (version.major === 4 && (version.minor ?? 0) >= 5));
 }
 
 /** The slice of pi's ToolInfo the deferred definitions need. */
@@ -127,7 +212,74 @@ export function toolSearchLoads(branch: readonly SessionEntry[]): Map<string, st
 	}
 	return loads;
 }
-const TOOL_SEARCH_NAMES: ReadonlySet<string> = new Set(["tool_search"]);
+const TOOL_SEARCH_NAMES: ReadonlySet<string> = new Set([TOOL_SEARCH]);
+
+/**
+ * The tools `entries` use: loaded by a `tool_search` result in them (`loads`,
+ * their `toolSearchLoads`), or called by an assistant message in them. A call
+ * the dispatcher failed as "Tool <name> not found" does not count: the tool
+ * was not loaded, and the miss steers the model to `tool_search` to load it.
+ */
+export function toolsInUse(entries: readonly SessionEntry[], loads: ToolSearchLoads = toolSearchLoads(entries)): Set<string> {
+	const inUse = new Set([...loads.values()].flat());
+	const missed = new Set<string>();
+	for (const entry of entries) {
+		const message = entry.type === "message" ? (entry.message as { role?: string; toolCallId?: unknown; isError?: unknown }) : undefined;
+		if (message?.role === "toolResult" && message.isError === true && typeof message.toolCallId === "string" && toolNotFoundName(resultText(message))) missed.add(message.toolCallId);
+	}
+	for (const entry of entries) {
+		const message = entry.type === "message" ? (entry.message as { role?: string; content?: unknown }) : undefined;
+		if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+		for (const block of message.content as Array<{ type?: string; id?: unknown; name?: unknown }>) {
+			if (block?.type === "toolCall" && typeof block.name === "string" && !(typeof block.id === "string" && missed.has(block.id))) inUse.add(block.name);
+		}
+	}
+	return inUse;
+}
+
+/** Why a deferred tool is callable without a fresh `tool_search` load. */
+export interface CallableReasons {
+	/** Loaded by a `tool_search` result in context, or called in context: its history names it. */
+	inUse: ReadonlySet<string>;
+	/** Announced callable by a `tool_addition` in the current epoch (the ledger's told facts). */
+	toldCallable: ReadonlySet<string>;
+	/** Declared eagerly by the recorded head the next request starts from: it stays declared, so it stays callable. */
+	declaredEager: ReadonlySet<string>;
+	/** Announced callable by the next request itself: loadable and untold inside an epoch, on a model that takes `tool_addition`. */
+	announcing: ReadonlySet<string>;
+}
+
+/**
+ * The deferred tools that are callable now, derived from the branch, the model
+ * and the registry (lifecycle-grid-hunt design.md section 6): every other
+ * deferred tool is inactive, whoever activated it. One function decides, so a
+ * resume, `/reload`, `/tree`, a compaction, a model switch and a late defer
+ * cannot disagree with what the wire declares and what the model was told.
+ */
+export function callableDeferredTools(deferred: Iterable<string>, reasons: CallableReasons): Set<string> {
+	const callable = new Set<string>();
+	for (const name of deferred) {
+		if (reasons.inUse.has(name) || reasons.toldCallable.has(name) || reasons.declaredEager.has(name) || reasons.announcing.has(name)) callable.add(name);
+	}
+	return callable;
+}
+
+/**
+ * pi's active set with exactly the `callable` deferred tools active (those
+ * pi has registered) and no `withheld` tool; every other tool as it was. The
+ * input itself when nothing changes.
+ */
+export function reconcileActive(
+	active: readonly string[],
+	deferred: ReadonlySet<string>,
+	callable: ReadonlySet<string>,
+	withheld: ReadonlySet<string>,
+	registered: ReadonlySet<string>,
+): readonly string[] {
+	const kept = active.filter((name) => !withheld.has(name) && (!deferred.has(name) || callable.has(name)));
+	const added = [...callable].filter((name) => registered.has(name) && !withheld.has(name) && !kept.includes(name));
+	return kept.length === active.length && added.length === 0 ? active : [...kept, ...added];
+}
 
 type WireTool = Record<string, unknown> & { name: string };
 type WireBlock = Record<string, unknown> & { type?: unknown };
@@ -157,7 +309,7 @@ function withBreakpointOnLast<T extends Record<string, unknown>>(items: T[], cac
  * An Anthropic request whose `tools` array is byte-identical to request 1's,
  * whatever `tool_search` has loaded since — the client side of Anthropic's
  * deferred-tool contract, which pi 0.86 no longer supplies for One Code
- * (rationale and measurements: docs/decisions/caching.md "Loaded deferred
+ * (rationale and measurements: working-docs/decisions/caching.md "Loaded deferred
  * tools stay deferred on the wire", findings §7).
  *
  * - Every registry tool `isDeferred` that is not eager on the wire is appended
@@ -171,6 +323,9 @@ function withBreakpointOnLast<T extends Record<string, unknown>>(items: T[], cac
  *   ordinary result content). Demotion happens only when that result is on the
  *   wire and precedes every `tool_use` of the tool; otherwise the tool stays
  *   eager (one accepted cache miss, never a request Anthropic rejects).
+ * - A tool the request adds mid-session by `tool_addition` (`additions`,
+ *   lib/tool-additions.ts) is demoted the same way: its addition block
+ *   references it, so it needs no `tool_search` result.
  * - pi's own deferred entries that are not registry tools (its
  *   `__pi_deferred_placeholder__`) stay in place.
  *
@@ -184,6 +339,7 @@ export function stabilizeDeferredTools(
 	tools: readonly DeferrableToolInfo[],
 	isDeferred: (name: string) => boolean,
 	loads: ToolSearchLoads = new Map(),
+	additions: ReadonlySet<string> = new Set(),
 ): Record<string, unknown> | undefined {
 	const existing = payload.tools;
 	if (!Array.isArray(existing) || existing.length === 0) return undefined;
@@ -220,16 +376,7 @@ export function stabilizeDeferredTools(
 				}
 			}
 		});
-		// The earliest on-wire load of each tool.
-		const loaderOf = new Map<string, { callId: string; at: number }>();
-		for (const [callId, names] of loads) {
-			const at = resultAt.get(callId);
-			if (at === undefined) continue;
-			for (const name of names) {
-				const current = loaderOf.get(name);
-				if (current === undefined || at < current.at) loaderOf.set(name, { callId, at });
-			}
-		}
+		const loaderOf = earliestLoads(loads, (callId) => resultAt.get(callId));
 		for (const tool of eager) {
 			if (!isDeferred(tool.name)) continue;
 			const loader = loaderOf.get(tool.name);
@@ -239,8 +386,15 @@ export function stabilizeDeferredTools(
 			demoted.add(tool.name);
 			referencesAt.set(loader.callId, [...(referencesAt.get(loader.callId) ?? []), tool.name]);
 		}
+		// References in the order the query named them, as Claude Code lists them.
+		for (const [callId, names] of referencesAt) {
+			const order = loads.get(callId) ?? [];
+			referencesAt.set(callId, [...names].sort((a, b) => order.indexOf(a) - order.indexOf(b)));
+		}
 	}
 
+	for (const tool of eager) if (additions.has(tool.name) && isDeferred(tool.name)) demoted.add(tool.name);
+
 	// pi puts the tools breakpoint on the last eager tool; if that one is demoted
 	// the breakpoint moves to the new last one, otherwise nothing moves.
 	const last = eager.at(-1);
@@ -285,7 +439,7 @@ function withToolReferences(message: WireMessage, referencesAt: ReadonlyMap<stri
 		if (cache_control !== undefined) movedBreakpoint = cache_control;
 		blocks.push({ ...rest, content: names.map((name) => ({ type: "tool_reference", tool_name: name })) });
 		if (typeof original === "string") {
-			if (original.trim().length > 0) siblings.push({ type: "text", text: original });
+			if (original.trim().length > 0) siblings.push({ type: "text", text: withClaudeCodeLoadText(original) });
 		} else if (Array.isArray(original)) {
 			siblings.push(...(original as WireBlock[]));
 		}
@@ -293,6 +447,148 @@ function withToolReferences(message: WireMessage, referencesAt: ReadonlyMap<stri
 	return { ...message, content: withBreakpointOnLast([...blocks, ...siblings], movedBreakpoint) };
 }
 
+/** `tool_search`'s plain success sentence, which the references stand in for. */
+const LOADED_SENTENCE = /^Loaded [^\n]*\. These tools are now callable\.(?=\n|$)/;
+
+/**
+ * The text beside the references: Claude Code's "Tool loaded." in place of the
+ * plain success sentence, which names what the references already carry. A
+ * sentence with a not-found note, and anything after it, stays as it was.
+ */
+function withClaudeCodeLoadText(text: string): string {
+	return text.replace(LOADED_SENTENCE, "Tool loaded.");
+}
+
+/**
+ * The earliest on-wire load of each tool: the `tool_search` call whose result
+ * sits first in the conversation (`resultAt` is its index, undefined when it is
+ * not on the wire).
+ */
+function earliestLoads(loads: ToolSearchLoads, resultAt: (callId: string) => number | undefined): Map<string, { callId: string; at: number }> {
+	const loaderOf = new Map<string, { callId: string; at: number }>();
+	for (const [callId, names] of loads) {
+		const at = resultAt(callId);
+		if (at === undefined) continue;
+		for (const name of names) {
+			const current = loaderOf.get(name);
+			if (current === undefined || at < current.at) loaderOf.set(name, { callId, at });
+		}
+	}
+	return loaderOf;
+}
+
+
+/** How a Responses model takes a mid-conversation tool load (pi-ai's model `compat` fields). */
+export interface ToolLoadCompat {
+	supportsAdditionalTools?: boolean;
+	supportsToolSearch?: boolean;
+}
+
+/** The model fields that say whether, and how, a Responses request can add a tool mid-conversation. */
+export interface ResponsesToolLoadModel {
+	api?: string;
+	compat?: ToolLoadCompat;
+}
+
+/**
+ * The model's tool-load compat when it takes a mid-conversation tool load in
+ * pi-ai's native Responses shape, else undefined.
+ */
+export function responsesToolLoadCompat(model: ResponsesToolLoadModel | undefined): ToolLoadCompat | undefined {
+	if (!model?.api || !RESPONSES_APIS.has(model.api)) return undefined;
+	const compat = model.compat;
+	return compat?.supportsAdditionalTools === true || compat?.supportsToolSearch === true ? compat : undefined;
+}
+
+type WireItem = Record<string, unknown>;
+
+/**
+ * A Responses request whose starting tools stay request 1's whatever
+ * `tool_search` has loaded since: the OpenAI side of
+ * {@link stabilizeDeferredTools}. pi 0.86 and later put a loaded tool into
+ * `tools` for One Code (its forced system prompt collapses tool changes into
+ * the head, findings §7), so every load re-cached the whole conversation (0
+ * cached tokens on the request after a load on `openai-codex`, findings §45).
+ *
+ * The starting tools are a top-level `tools` array (pi 1.0 to 1.3, and
+ * models pi does not flag) or, from pi 1.4.0, an `additional_tools` item at
+ * the head of the input (findings §78); this reads which from the payload.
+ * A loaded registry tool leaves that list and enters the input right before the
+ * `function_call_output` of the `tool_search` call that loaded it, in pi-ai's
+ * own native shape (`convertResponsesMessages` `appendSystemToolAdditions`):
+ * an `additional_tools` developer item when the request already declares in
+ * items or the model supports one, else a `tool_search_call` +
+ * `tool_search_output` pair whose tools carry `defer_loading: true`. A tool
+ * the model called before that output, or whose loading output is not on the
+ * wire, stays where pi declared it.
+ *
+ * Returns undefined (leave the payload alone) when nothing moves. Never
+ * mutates its input.
+ */
+export function stabilizeResponsesToolLoads(
+	payload: Record<string, unknown>,
+	isDeferred: (name: string) => boolean,
+	loads: ToolSearchLoads,
+	compat: ToolLoadCompat,
+): Record<string, unknown> | undefined {
+	const input = payload.input;
+	if (!Array.isArray(input) || loads.size === 0) return undefined;
+	// Where the request declares its starting tools: a top-level array (pi 1.0
+	// to 1.3, and models pi does not flag), or an `additional_tools` item at the
+	// head of the input (pi 1.4.0 and later, findings §78). Read from the bytes.
+	const headItem = leadingToolsItem(payload.tools, input);
+	const tools = headItem ? headItem.tools : payload.tools;
+	if (!Array.isArray(tools)) return undefined;
+
+	// Input index of each tool output and of each tool's first call. pi sends a
+	// call id as `<call_id>|<item_id>`; the wire's `call_id` is the first part.
+	const outputAt = new Map<string, number>();
+	const firstUse = new Map<string, number>();
+	(input as WireItem[]).forEach((item, index) => {
+		if (item?.type === "function_call_output" && typeof item.call_id === "string") outputAt.set(item.call_id, index);
+		else if ((item?.type === "function_call" || item?.type === "custom_tool_call") && typeof item.name === "string" && !firstUse.has(item.name)) {
+			firstUse.set(item.name, index);
+		}
+	});
+	const loaderOf = earliestLoads(loads, (callId) => outputAt.get(callId.split("|")[0]));
+
+	const movedAt = new Map<number, WireItem[]>();
+	const kept: unknown[] = [];
+	for (const raw of tools) {
+		const tool = raw as WireItem | null;
+		const name = typeof tool?.name === "string" ? tool.name : undefined;
+		const at = name !== undefined && isDeferred(name) ? loaderOf.get(name)?.at : undefined;
+		const use = name !== undefined ? firstUse.get(name) : undefined;
+		if (at === undefined || (use !== undefined && use < at)) {
+			kept.push(raw);
+			continue;
+		}
+		movedAt.set(at, [...(movedAt.get(at) ?? []), tool as WireItem]);
+	}
+	if (movedAt.size === 0) return undefined;
+
+	// A request that declares in items takes another item, shaped like its
+	// head; the top-level shape takes what the model's compat supports.
+	const nextInput: unknown[] = [];
+	(input as WireItem[]).forEach((item, index) => {
+		const moved = movedAt.get(index);
+		if (moved) nextInput.push(...(headItem ? [toolsItemFor(moved, headItem)] : toolLoadItems(moved, String(item.call_id), compat)));
+		nextInput.push(headItem && index === 0 ? { ...headItem, tools: kept } : item);
+	});
+	return headItem ? { ...payload, input: nextInput } : { ...payload, tools: kept, input: nextInput };
+}
+
+/** pi-ai's native items for tools added at one point of a Responses conversation. */
+function toolLoadItems(tools: WireItem[], loaderCallId: string, compat: ToolLoadCompat): WireItem[] {
+	if (compat.supportsAdditionalTools) return [toolsItemFor(tools)];
+	const names = tools.map((tool) => String(tool.name));
+	const callId = `pi_tool_load_${createHash("sha256").update(`${loaderCallId}:${names.join(",")}`).digest("hex").slice(0, 16)}`;
+	return [
+		{ type: "tool_search_call", call_id: callId, execution: "client", status: "completed", arguments: { query: names.join(" "), limit: names.length } },
+		{ type: "tool_search_output", call_id: callId, execution: "client", status: "completed", tools: tools.map((tool) => ({ ...tool, defer_loading: true })) },
+	];
+}
+
 /**
  * The bare error pi's core dispatcher returns when the model calls a tool whose
  * schema isn't in the active set — including every deferred tool before
@@ -326,6 +622,35 @@ export function deferredMissReminderText(name: string): string {
 	].join(" ");
 }
 
+/**
+ * The notice for a resumed session whose first message still lists deferred
+ * tools (that message keeps its bytes) while this run's tool list leaves
+ * tool_search out (`deferralEnabled`): nothing can load them now.
+ */
+export function loaderUnavailableReminderText(): string {
+	return "tool_search is not available in this session, so it cannot load the deferred tools listed earlier in this conversation. Use only the tools defined for this session.";
+}
+
+/**
+ * The correction for a tool WITHHOLD_CHANNEL took away (the task tools on a
+ * frontier or Sonnet 5+ model): unlike an ordinary deferred miss, `tool_search`
+ * cannot load it — the name is gone from the registry, not merely inactive —
+ * so the steer must NOT repeat `deferredMissReminderText`'s "load it with
+ * tool_search" advice, which would just fail again.
+ */
+export function withheldMissReminderText(name: string): string {
+	return `\`${name}\` failed with "Tool ${name} not found" because it was withdrawn for the current model — it is not a deferred tool you can load with tool_search. Do not retry it; continue without it.`;
+}
+
+/**
+ * A call to a tool the conversation still declares (the epoch's recorded
+ * tools stay declared, decisions/caching.md "record once") that this session
+ * no longer runs: a setting turned it off, or an extension stopped offering it.
+ */
+export function unavailableToolReminderText(name: string): string {
+	return `\`${name}\` failed with "Tool ${name} not found" because it is no longer available in this session, although it is still declared. Do not retry it; continue without it.`;
+}
+
 export interface SearchMatch {
 	name: string;
 	score: number;
@@ -340,6 +665,15 @@ export interface SearchMatch {
  * requested names matched nothing instead of silently dropping them.
  */
 export function selectedNames(query: string): string[] | undefined {
+	return selectedRequests(query)?.map((request) => request.name);
+}
+
+/**
+ * {@link selectedNames} with each name as the model wrote it, so a "not found"
+ * note quotes the model's spelling: `select:find,grep,glob` maps `glob` to
+ * `find`, and quoting the mapped names read "find, grep, find".
+ */
+export function selectedRequests(query: string): { name: string; asWritten: string }[] | undefined {
 	const trimmed = query.trim();
 	if (!trimmed.toLowerCase().startsWith("select:")) return undefined;
 	return trimmed
@@ -350,7 +684,7 @@ export function selectedNames(query: string): string[] | undefined {
 		// normalizeToolName lowercases ordinary names but PRESERVES case for
 		// `mcp__…` names; the trailing toLowerCase keeps select: case-insensitive
 		// for those too. Don't drop it as "redundant".
-		.map((n) => normalizeToolName(n).toLowerCase());
+		.map((asWritten) => ({ name: normalizeToolName(asWritten).toLowerCase(), asWritten }));
 }
 
 /**

package/extensions/lib/dock-rows.ts

@@ -0,0 +1,60 @@
+/**
+ * Rows each extension paints below the editor (the "dock": the subagent strip
+ * and shells chip, the workflow status rows), shared over `pi.events` (pure:
+ * no pi imports). A panel that takes the editor's place sizes itself to what
+ * the dock leaves: pi cuts a component taller than its share from the bottom,
+ * which took the viewer's key-hint row when only its own strip was counted.
+ *
+ * Extensions are isolated (jiti), so each one keeps its own `DockRows` fed from
+ * the channel; a source reports through `dockRowsReporter`, which emits only
+ * on a change.
+ */
+
+export const DOCK_ROWS_CHANNEL = "one-code:dock-rows";
+
+export interface DockRowsEvent {
+	/** The reporting strip, e.g. "subagents" or "workflow". */
+	source: string;
+	/** Rows it paints now; 0 when it shows nothing. */
+	rows: number;
+}
+
+interface Emitter {
+	emit(channel: string, data: unknown): void;
+}
+
+/** A source's reporter: call it with the rows painted on each render; it emits only when the count changes. */
+export function dockRowsReporter(events: Emitter, source: string): (rows: number) => void {
+	let last = 0;
+	return (rows) => {
+		if (rows === last) return;
+		last = rows;
+		events.emit(DOCK_ROWS_CHANNEL, { source, rows } satisfies DockRowsEvent);
+	};
+}
+
+/** A `DockRows` fed from `events`, for an extension that sizes a view to the dock. */
+export function trackDockRows(events: { on(channel: string, handler: (data: unknown) => void): unknown }): DockRows {
+	const dock = new DockRows();
+	events.on(DOCK_ROWS_CHANNEL, (data) => dock.note(data));
+	return dock;
+}
+
+/** The dock's rows as reported, by source. */
+export class DockRows {
+	private readonly rows = new Map<string, number>();
+
+	note(data: unknown): void {
+		const event = data as Partial<DockRowsEvent> | undefined;
+		if (typeof event?.source !== "string" || typeof event.rows !== "number") return;
+		if (event.rows > 0) this.rows.set(event.source, event.rows);
+		else this.rows.delete(event.source);
+	}
+
+	/** Rows every source other than `self` paints. */
+	others(self: string): number {
+		let total = 0;
+		for (const [source, rows] of this.rows) if (source !== self) total += rows;
+		return total;
+	}
+}

package/extensions/lib/empty-tool-result.ts

@@ -0,0 +1,27 @@
+/** Claude Code's empty tool_result guard and marker (toolResultStorage). */
+import { ccToolName } from "../hooks/matcher.ts";
+
+export function emptyToolResultText(toolName: string): string {
+	return `(${ccToolName(toolName)} completed with no output)`;
+}
+
+/** Images and other non-text blocks are results, even without accompanying text. */
+function isEmptyToolResultContent(content: unknown): boolean {
+	if (!content) return true;
+	if (typeof content === "string") return content.trim() === "";
+	if (!Array.isArray(content)) return false;
+	return content.every((block) => block !== null && typeof block === "object" && block.type === "text" &&
+		"text" in block && (typeof block.text !== "string" || block.text.trim() === ""));
+}
+
+/** Replacement content, or undefined to retain the tool's own result verbatim. */
+export function emptyToolResultContent(content: unknown, toolName: string): Array<{ type: "text"; text: string }> | undefined {
+	const only = Array.isArray(content) && content.length === 1 && content[0]?.type === "text" && typeof content[0].text === "string" ? content[0] : undefined;
+	// pi Read returns raw file bytes, not Claude Code's numbered lines. Leave
+	// blank selections alone; file-tracker supplies the genuine empty-file warning.
+	if (toolName === "read" && only) return undefined;
+	if (isEmptyToolResultContent(content)) return [{ type: "text", text: emptyToolResultText(toolName) }];
+	// pi's find is Claude Code's Glob; Grep already uses Claude Code's no-match text.
+	if (toolName === "find" && only?.text === "No files found matching pattern") return [{ ...only, text: "No files found" }];
+	return undefined;
+}

package/extensions/lib/environment-block.ts

@@ -0,0 +1,76 @@
+/**
+ * Claude Code's environment block and model line (pure): the first two parts of
+ * its mid-conversation system message, and the first two blocks of the first
+ * user message on a model without one (lib/system-role.ts). They left the
+ * system prompt, which keeps only what never varies per session.
+ */
+
+import { parseClaudeId } from "./model-tier.ts";
+
+export interface EnvironmentFacts {
+	cwd: string;
+	isGitRepo: boolean;
+	platform: string;
+	shell: string;
+	osVersion: string;
+	/** The session's private scratchpad, when one could be made (lib/scratchpad.ts). */
+	scratchpadDir?: string;
+	/** The workspace directories as the session started; listed only when there are some. */
+	workspaceDirs?: string[];
+}
+
+/** Claude Code's `# Environment` block, byte for byte; the trailing space after "environment:" is Claude Code's. */
+export function environmentBlock(env: EnvironmentFacts): string {
+	const lines = [
+		"# Environment",
+		"You have been invoked in the following environment: ",
+		` - Primary working directory: ${env.cwd}`,
+		` - Is a git repository: ${env.isGitRepo}`,
+	];
+	if (env.workspaceDirs?.length) lines.push(" - Additional working directories:", ...env.workspaceDirs.map((dir) => `  - ${dir}`));
+	lines.push(` - Platform: ${env.platform}`, ` - Shell: ${env.shell}`, ` - OS Version: ${env.osVersion}`);
+	if (env.scratchpadDir) {
+		lines.push(
+			` - Scratchpad directory: ${env.scratchpadDir} — always use it for temporary files (intermediate results, scripts, outputs that don't belong in the project) instead of \`/tmp\` or other system temp directories; it is session-specific, isolated from the project, and can generally be used without permission prompts. Only use \`/tmp\` if the user explicitly asks.`,
+		);
+	}
+	return lines.join("\n");
+}
+
+/** Knowledge cutoffs Claude Code states, keyed by family and version. */
+const CLAUDE_CUTOFFS: Record<string, string> = {
+	"opus 4.5": "May 2025",
+	"opus 4.6": "May 2025",
+	"opus 4.7": "January 2026",
+	"opus 4.8": "January 2026",
+	"opus 5": "May 2026",
+	"opus 5.5": "June 2026",
+	"sonnet 4.5": "January 2025",
+	"sonnet 4.6": "August 2025",
+	"sonnet 5": "January 2026",
+	"sonnet 5.5": "June 2026",
+	"haiku 4.5": "February 2025",
+	"haiku 5.5": "June 2026",
+	"fable 5.1": "June 2026",
+};
+
+/** A Claude model's name as Claude Code says it ("Opus 5.5", "Haiku 4.5"), from an id in any provider's spelling. */
+export function claudeDisplayName(id: string): string | undefined {
+	const claude = parseClaudeId(id);
+	if (!claude) return undefined;
+	const family = claude.family[0].toUpperCase() + claude.family.slice(1);
+	return claude.minor === undefined ? `${family} ${claude.major}` : `${family} ${claude.major}.${claude.minor}`;
+}
+
+/**
+ * Claude Code's model sentence. A Claude model gets its name and, where
+ * Claude Code states one, its knowledge cutoff; any other model gets the
+ * catalog's name and no cutoff clause, since the cutoff is a per-model fact.
+ */
+export function modelLine(model: { id: string; name?: string }): string {
+	const claude = claudeDisplayName(model.id);
+	const name = claude ?? (model.name || model.id);
+	const cutoff = claude ? CLAUDE_CUTOFFS[claude.toLowerCase()] : undefined;
+	const base = `You are powered by the model named ${name}. The exact model ID is ${model.id}.`;
+	return cutoff ? `${base} Assistant knowledge cutoff is ${cutoff}.` : base;
+}