one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/subagent-handback.ts

@@ -0,0 +1,113 @@
+/**
+ * Claude Code's `SubagentHandback`: the tool every child session (an Agent
+ * run, a fork, a workflow agent) returns its result through, and the closing
+ * reminder that tells it so (decisions/subagents-workflows.md, "Every child
+ * hands back through SubagentHandback"). Claude Code gives it to Opus and
+ * Sonnet children only; One Code gives it to every child on every model.
+ *
+ * The tool records the report in the run's `HandbackSlot` and ends the run
+ * (`terminate`, so no further request goes out after a batch of hand-backs).
+ * The runner then reports the recorded text as the child's result, and falls
+ * back to the child's final message when the tool was never called.
+ *
+ * The tool keeps Claude Code's exact name, like `Agent` and `SendMessage`,
+ * because the harness frames that carry its report already name it ("its
+ * SubagentHandback call", lib/notifications.ts). It is harness plumbing: the
+ * child permission and hook gates never gate it, and an agent file's `tools`
+ * allowlist keeps it.
+ *
+ * In a fork the tool is deferred: a fork sends the parent's tool list so it
+ * reads the parent's prompt cache (subagents/fork-cache.ts), and an eager tool
+ * of its own would be dropped from that list. A deferred one reaches the
+ * request through a `tool_search` load, as the fork's `SendMessage` does.
+ */
+
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { DEFER_CHANNEL } from "./deferred.ts";
+import { REMINDER_CHANNEL, type ReminderPayload } from "./reminders.ts";
+
+export const SUBAGENT_HANDBACK = "SubagentHandback";
+
+/** Claude Code's description of the tool. */
+export const SUBAGENT_HANDBACK_DESCRIPTION =
+	"Deliver your final report to the agent that spawned you (your caller). Use it once, for that hand-off only: when your work is complete, call SubagentHandback({message: <your full report>}). The call ends your run, so do everything else first and put everything your caller needs in that one report. It is not a messaging channel: do not use it for progress updates or questions.\n\nOnly a report delivered through SubagentHandback reaches your caller; plain text you write at the end of your run is NOT delivered. There is no recipient parameter: the report can only go to your caller.";
+
+/** Claude Code's closing reminder on the child's task message. */
+export const SUBAGENT_HANDBACK_REMINDER =
+	"Your final report is delivered through SubagentHandback: when your work is complete, call SubagentHandback({message: <your full report>}). The call ends your run, so make it your last step. Only a SubagentHandback call reaches your caller as your result; plain text you write at the end is not delivered.";
+
+/**
+ * One Code's line before the reminder in a fork, where the tool is deferred
+ * (the fork sends its parent's tool list): it names the load step, which the
+ * frozen deferred listing it inherits does not.
+ */
+export const SUBAGENT_HANDBACK_LOAD_FIRST =
+	'SubagentHandback is deferred here: load it first with tool_search (query "select:SubagentHandback").';
+
+/** Claude Code's result texts for the call. */
+export const HANDBACK_DELIVERED = "Report delivered to your caller.";
+export const HANDBACK_ALREADY_DELIVERED =
+	"Nothing was sent: your report was already delivered (SubagentHandback delivers one report). Use SendMessage for anything further, then stop.";
+export const HANDBACK_EMPTY = "message must not be empty: pass your full report as `message`.";
+
+/** Where a run keeps the report its child handed back. */
+export interface HandbackSlot {
+	/** Record the report; false when this turn already delivered one. */
+	recordHandback(message: string): boolean;
+}
+
+/** A slot for a one-turn run (a workflow agent): the first report wins. */
+export function oneTurnHandbackSlot(): HandbackSlot & { report?: string } {
+	const slot: HandbackSlot & { report?: string } = {
+		report: undefined,
+		recordHandback(message) {
+			if (slot.report !== undefined) return false;
+			slot.report = message;
+			return true;
+		},
+	};
+	return slot;
+}
+
+export function subagentHandbackTool(slot: HandbackSlot): ToolDefinition {
+	return {
+		name: SUBAGENT_HANDBACK,
+		label: "Hand back",
+		description: SUBAGENT_HANDBACK_DESCRIPTION,
+		parameters: Type.Object({ message: Type.String({ description: "Your full report for your caller" }) }, { additionalProperties: false }) as never,
+		async execute(_toolCallId: string, params: unknown) {
+			const message = (params as { message?: unknown } | undefined)?.message;
+			// Fail loud (decisions/tools.md): an empty report would end the run with nothing for the caller.
+			if (typeof message !== "string" || !message.trim()) {
+				return { content: [{ type: "text" as const, text: HANDBACK_EMPTY }], details: {}, isError: true };
+			}
+			if (!slot.recordHandback(message)) {
+				return { content: [{ type: "text" as const, text: HANDBACK_ALREADY_DELIVERED }], details: {}, isError: true };
+			}
+			return { content: [{ type: "text" as const, text: HANDBACK_DELIVERED }], details: { handback: true }, terminate: true };
+		},
+	} as ToolDefinition;
+}
+
+/**
+ * The inline extension a child session loads for the hand-back: the tool,
+ * deferred in a fork, and the closing reminder. The reminder is a standing
+ * block (`sticky-append`) switched on at session start, so it rides the
+ * child's task message and every later message of the run (a resident's
+ * next turns hand back too), and never an inherited message of a fork.
+ */
+export function subagentHandbackExtension(slot: HandbackSlot, options: { deferred?: boolean } = {}) {
+	return (pi: ExtensionAPI) => {
+		pi.registerTool(subagentHandbackTool(slot));
+		if (options.deferred) pi.events.emit(DEFER_CHANNEL, { name: SUBAGENT_HANDBACK, keywords: ["handback", "report", "result", "final", "caller"] });
+		pi.on("session_start", () => {
+			pi.events.emit(REMINDER_CHANNEL, {
+				text: options.deferred ? `${SUBAGENT_HANDBACK_LOAD_FIRST}\n${SUBAGENT_HANDBACK_REMINDER}` : SUBAGENT_HANDBACK_REMINDER,
+				scope: "every-turn",
+				key: "subagent-handback",
+				placement: "sticky-append",
+			} satisfies ReminderPayload);
+		});
+	};
+}

package/extensions/lib/system-role.ts

@@ -0,0 +1,156 @@
+/**
+ * Which models get Claude Code's mid-conversation `role: "system"` message,
+ * and in which wire shape (pure). One function for the system-prompt builder,
+ * the reminder hook and the tool hook, so all three agree on every request.
+ *
+ * The gate is pi's model catalog flag `compat.supportsMidConvoSystemMessages`
+ * alone, no list of our own: pi owns the per-model facts and adds models as it
+ * confirms them (`working-docs/decisions/tools.md`, "Claude Code's request
+ * shape, on every model pi flags for it"). Haiku before 5 is never in it:
+ * Anthropic rejects the role there (findings §52); Haiku 5.5 takes it
+ * (findings §67). Every unflagged model keeps the context in the first user
+ * message.
+ */
+
+import { parseClaudeId } from "./claude-id.ts";
+
+/** The wire shape a system message takes: Anthropic `system`, OpenAI Responses `input`, or Chat Completions `messages`. */
+export type SystemRoleLayout = "anthropic" | "responses" | "completions";
+
+/** The fields of a pi `Model` the gate reads. */
+export interface SystemRoleModel {
+	id: string;
+	api: string;
+	compat?: unknown;
+}
+
+/** pi-ai's Responses APIs: requests carry `input` items and flat `{ type, name }` tools. */
+export const RESPONSES_APIS: ReadonlySet<string> = new Set(["openai-responses", "azure-openai-responses", "openai-codex-responses"]);
+
+/** The wire shape of a pi API, for the three shapes One Code rewrites; undefined for the rest (Google, Bedrock). */
+export function wireShape(api: string): SystemRoleLayout | undefined {
+	if (api === "anthropic-messages") return "anthropic";
+	if (RESPONSES_APIS.has(api)) return "responses";
+	if (api === "openai-completions") return "completions";
+	return undefined;
+}
+
+/** The payload field that holds the conversation for a wire shape. */
+export function messagesKey(shape: SystemRoleLayout): "input" | "messages" {
+	return shape === "responses" ? "input" : "messages";
+}
+
+export function systemRoleLayout(model: SystemRoleModel | undefined): SystemRoleLayout | undefined {
+	if (!model) return undefined;
+	const compat = model.compat as { supportsMidConvoSystemMessages?: unknown } | undefined;
+	if (compat?.supportsMidConvoSystemMessages !== true) return undefined;
+	if (model.api === "anthropic-messages" && isHaikuBeforeFive(model.id)) return undefined;
+	return wireShape(model.api);
+}
+
+/** A Haiku older than Haiku 5 in any provider's spelling; the old `claude-3-5-haiku` order parses as none. */
+function isHaikuBeforeFive(id: string): boolean {
+	const claude = parseClaudeId(id);
+	return claude ? claude.family === "haiku" && claude.major < 5 : id.includes("haiku");
+}
+
+/** One context block that moves: its text as injected on the user message, and its text inside the system message. */
+export interface MovedBlock {
+	/** The block exactly as the user message carries it (`<system-reminder>` frame and suffix included). */
+	framed: string;
+	/** The unwrapped text, as Claude Code's system message joins it. */
+	inner: string;
+}
+
+/**
+ * The role a system message takes on the OpenAI APIs: pi's own rule per API
+ * (`developer` for a reasoning model that accepts it, else `system`).
+ */
+export function instructionRole(layout: SystemRoleLayout, model: { reasoning?: boolean; compat?: unknown }): "system" | "developer" {
+	if (layout === "anthropic") return "system";
+	const developer = (model.compat as { supportsDeveloperRole?: boolean } | undefined)?.supportsDeveloperRole;
+	const accepts = layout === "responses" ? developer !== false : developer === true;
+	return model.reasoning && accepts ? "developer" : "system";
+}
+
+/** A wire message and content part, as far as the payload rewrites read them. */
+export type WireMessage = { role?: unknown; type?: unknown; content?: unknown; output?: unknown; call_id?: unknown; tool_call_id?: unknown };
+export type WirePart = { type?: unknown; text?: unknown; content?: unknown; tool_use_id?: unknown; cache_control?: unknown };
+
+/**
+ * The parts with those `drop` accepts removed, keeping pi's cache mark: when a
+ * removed part carried it, it moves to the new last part. Undefined when every
+ * part would go (a message cannot be left empty) or nothing is removed.
+ */
+export function withoutParts(parts: readonly WirePart[], drop: (part: WirePart, index: number) => boolean): WirePart[] | undefined {
+	let mark: unknown;
+	const kept = parts.filter((part, index) => {
+		if (!drop(part, index)) return true;
+		if (part?.cache_control !== undefined) mark = part.cache_control;
+		return false;
+	});
+	if (kept.length === parts.length || kept.length === 0) return undefined;
+	if (mark === undefined || kept[kept.length - 1].cache_control !== undefined) return kept;
+	return [...kept.slice(0, -1), { ...kept[kept.length - 1], cache_control: mark }];
+}
+
+/**
+ * The value stored under a pi call id for the id a request carries: the same
+ * id, the Responses call id before pi's `|item` suffix, or the id pi-ai's
+ * Anthropic conversion rewrote (any other character to `_`, at most 64), as it
+ * does for a call made on another provider before a model switch.
+ */
+export function byWireCallId<V>(stored: ReadonlyMap<string, V>, wireId: string): V | undefined {
+	if (stored.has(wireId)) return stored.get(wireId);
+	for (const [id, value] of stored) {
+		if (id.split("|")[0] === wireId || id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64) === wireId) return value;
+	}
+	return undefined;
+}
+
+/** A system message with `text` in the API's own shape. */
+export function systemMessage(layout: SystemRoleLayout, role: "system" | "developer", text: string): WireMessage {
+	return layout === "anthropic" ? { role: "system", content: [{ type: "text", text }] } : { role, content: text };
+}
+
+/**
+ * The payload with the moved context blocks lifted off the user message that
+ * carries them and joined, unwrapped and a blank line apart, into one system
+ * message placed right after it, in the API's own shape (Claude Code's layout,
+ * `decisions/tools.md`). Blocks are found by their exact text, never by
+ * position: a fork's request drops the parent's first message, and then nothing
+ * moves. The cache mark is reseated afterwards (anthropic-payload.ts
+ * reseatMessageMark). Undefined when nothing changes.
+ */
+export function withSystemRoleContext(
+	payload: Record<string, unknown>,
+	layout: SystemRoleLayout,
+	moved: readonly MovedBlock[],
+	role: "system" | "developer",
+): Record<string, unknown> | undefined {
+	if (moved.length === 0) return undefined;
+	const key = messagesKey(layout);
+	const messages = payload[key];
+	if (!Array.isArray(messages)) return undefined;
+	const wanted = new Set(moved.map((block) => block.framed));
+	const index = messages.findIndex(
+		(message: WireMessage) => message?.role === "user" && Array.isArray(message.content) && (message.content as WirePart[]).some((part) => wanted.has(part?.text as string)),
+	);
+	if (index === -1) return undefined;
+
+	const carrier = messages[index] as WireMessage & { content: WirePart[] };
+	const found = new Set<string>();
+	const kept = carrier.content.filter((part) => {
+		const text = part?.text;
+		if (typeof text !== "string" || !wanted.has(text) || found.has(text)) return true;
+		found.add(text);
+		return false;
+	});
+	const text = moved
+		.filter((block) => found.has(block.framed))
+		.map((block) => block.inner)
+		.join("\n\n");
+
+	const user: WireMessage = { ...carrier, content: kept };
+	return { ...payload, [key]: [...messages.slice(0, index), user, systemMessage(layout, role, text), ...messages.slice(index + 1)] };
+}

package/extensions/lib/terminal-text.ts

@@ -0,0 +1,114 @@
+/**
+ * Control characters in text that reaches the terminal (pure).
+ *
+ * Tool results, tool arguments, notification bodies, MCP results, fetched
+ * pages and the session title all carry text One Code did not write. Sent to
+ * the terminal raw, an escape sequence in it acts: OSC 0 retitles the
+ * terminal, OSC 52 rewrites the clipboard in kitty, WezTerm, Alacritty and
+ * Windows Terminal, cursor movement rewrites the rows above, SGR conceal hides
+ * text, and a carriage return overwrites the start of the row.
+ *
+ * `sanitizeDisplayText` applies pi's own rule for a tool result
+ * (`render-utils.js getTextOutput`: `stripAnsi`, then `sanitizeBinaryOutput`,
+ * then drop `\r`), and also drops C1 controls, which some terminals act on.
+ * It keeps `\n` and `\t` and never touches styling One Code adds afterwards,
+ * because it runs on the text before painting. `escapeControlText` shows each
+ * control character as a visible `\xHH` escape instead, for consent dialogs,
+ * where the user must see exactly what would run. `sanitizeTitle` is for the
+ * one-line terminal title.
+ *
+ * Display only: the model-facing text is never passed through these.
+ */
+
+// pi's `ansiRegex` (utils/ansi.js, from chalk's ansi-regex) matches an OSC up
+// to the first ST, else CSI and the related ESC forms. Its OSC branch is a lazy
+// scan to the end of the text from every `ESC ]`, quadratic on many
+// unterminated ones (50,000 took 1.8 s), so `stripAnsi` walks the text once
+// with the same alternation and remembers where no terminator is left.
+const CSI_AT = /[\u001B\u009B][[\]()#;?]*(?:\d{1,4}(?:[;:]\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]/y;
+
+/** The index just past the first string terminator (BEL, `ESC \`, or C1 ST) at or after `from`, else -1. */
+function stringTerminatorEnd(text: string, from: number): number {
+	for (let i = from; i < text.length; i++) {
+		const ch = text.charCodeAt(i);
+		if (ch === 0x07 || ch === 0x9c) return i + 1;
+		if (ch === 0x1b && text.charCodeAt(i + 1) === 0x5c) return i + 2;
+	}
+	return -1;
+}
+
+/** `text.replace(ansiRegex, "")` in linear time: the same matches, left to right. */
+function stripAnsi(text: string): string {
+	let out = "";
+	let from = 0;
+	// No string terminator exists at or after this index (a failed search holds for every later start).
+	let noTerminatorFrom = Number.POSITIVE_INFINITY;
+	let i = 0;
+	while (i < text.length) {
+		const ch = text.charCodeAt(i);
+		if (ch !== 0x1b && ch !== 0x9b) {
+			i++;
+			continue;
+		}
+		if (ch === 0x1b && text.charCodeAt(i + 1) === 0x5d && i + 2 < noTerminatorFrom) {
+			const end = stringTerminatorEnd(text, i + 2);
+			if (end !== -1) {
+				out += text.slice(from, i);
+				from = i = end;
+				continue;
+			}
+			noTerminatorFrom = i + 2;
+		}
+		CSI_AT.lastIndex = i;
+		const match = CSI_AT.exec(text);
+		if (match) {
+			out += text.slice(from, i);
+			from = i = i + match[0].length;
+			continue;
+		}
+		i++;
+	}
+	return out + text.slice(from);
+}
+
+/** C0 controls other than tab and newline, DEL, C1 controls, and U+FFF9 to U+FFFB (interlinear annotation). */
+const UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f-]/g;
+const HAS_UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f-]/;
+
+/**
+ * Text safe to write to the terminal: escape sequences removed, then every
+ * control character other than `\n` and `\t` (carriage returns included, as
+ * pi does). Plain text comes back unchanged (same string).
+ */
+export function sanitizeDisplayText(text: string): string {
+	if (!HAS_UNSAFE.test(text)) return text;
+	return stripAnsi(text).replace(UNSAFE, "");
+}
+
+/**
+ * `label` as an OSC 8 hyperlink to `url` (pi-tui's `hyperlink`). Terminals
+ * without OSC 8, and tmux without its `hyperlinks` feature, show the label
+ * alone, so the label must read on its own. Both parts are sanitized, so
+ * neither can end the sequence early.
+ */
+export function terminalLink(label: string, url: string): string {
+	return `\x1b]8;;${sanitizeDisplayText(url)}\x1b\\${sanitizeDisplayText(label)}\x1b]8;;\x1b\\`;
+}
+
+/**
+ * Every control character other than `\n` and `\t` shown as a visible
+ * `\xHH` escape (`\x1b[8m` for an SGR conceal), so nothing in the text can
+ * act on the terminal or hide part of itself.
+ */
+export function escapeControlText(text: string): string {
+	if (!HAS_UNSAFE.test(text)) return text;
+	return text.replace(UNSAFE, (ch) => {
+		const code = ch.charCodeAt(0);
+		return code > 0xff ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`;
+	});
+}
+
+/** One line for the terminal title: escape sequences and every control character removed, whitespace collapsed. */
+export function sanitizeTitle(text: string): string {
+	return sanitizeDisplayText(text).replace(/\s+/g, " ").trim();
+}

package/extensions/lib/text-width.ts

@@ -17,6 +17,10 @@
  * 2-vs-1 decision is byte-identical to pi's without importing pi or adding a
  * package. Grapheme segmentation and the mark/emoji classification use V8's
  * built-in `Intl.Segmenter` and Unicode property regexes.
+ *
+ * Synced with pi-tui 0.99.2. `text-width.test.ts` compares this measure with
+ * pi-tui's over every code point to U+3FFFF and over random strings with
+ * escapes, so a pi bump that changes pi-tui's measure fails the suite.
  */
 
 // --- East Asian wide/fullwidth lookup (get-east-asian-width v1.6.0, Unicode 16) ---
@@ -127,6 +131,7 @@ export function graphemeWidth(segment: string): number {
 		} else if (!nonPrintingCharRegex.test(char)) {
 			const c = char.codePointAt(0)!;
 			if (followsMark || (c >= 0xff00 && c <= 0xffef)) width += eastAsianWidth(c);
+			else if (c === 0x0e33 || c === 0x0eb3) width += 1; // Thai SARA AM, Lao AM
 			followsMark = false;
 		}
 	}
@@ -134,36 +139,35 @@ export function graphemeWidth(segment: string): number {
 }
 
 // --- ANSI / OSC / APC escape handling ---
-// A single terminal control sequence starting at index 0 of `s`, or null.
-// Covers CSI (styling/cursor), OSC (hyperlinks, prompt markers, terminated by
-// BEL or ST) and APC (terminated by ST) — the same families pi-tui strips.
+// The length of the terminal control sequence starting at index `i`, or 0.
+// Mirrors pi-tui's `extractAnsiCode` exactly, because pi-tui validates a line
+// with it: a CSI runs to the first `m`, `G`, `K`, `H` or `J`; an OSC or APC
+// runs to BEL or ST; an unterminated sequence, or any other ESC form, is not
+// a sequence, so its bytes count as text. A broader rule here measured such
+// text narrower than pi-tui and could emit a line pi-tui rejects. Display text
+// never carries those forms once `sanitizeDisplayText` has run.
 function escapeAt(s: string, i: number): number {
 	if (s.charCodeAt(i) !== 0x1b) return 0;
 	const next = s[i + 1];
 	if (next === "[") {
-		// CSI: ESC [ ... final byte 0x40–0x7E
 		let j = i + 2;
-		while (j < s.length) {
-			const c = s.charCodeAt(j);
-			j++;
-			if (c >= 0x40 && c <= 0x7e) return j - i;
-		}
-		return s.length - i;
+		while (j < s.length && !CSI_END.test(s[j])) j++;
+		return j < s.length ? j + 1 - i : 0;
 	}
-	if (next === "]" || next === "_" || next === "P" || next === "^") {
-		// OSC / APC / DCS / PM: ESC <intro> ... terminated by BEL or ST (ESC \)
+	if (next === "]" || next === "_") {
 		let j = i + 2;
 		while (j < s.length) {
 			if (s.charCodeAt(j) === 0x07) return j + 1 - i; // BEL
 			if (s.charCodeAt(j) === 0x1b && s[j + 1] === "\\") return j + 2 - i; // ST
 			j++;
 		}
-		return s.length - i;
+		return 0;
 	}
-	// Other two-byte escapes (ESC c, ESC =, …)
-	return next ? 2 : 1;
+	return 0;
 }
 
+const CSI_END = /[mGKHJ]/;
+
 const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
 
 /**
@@ -174,6 +178,9 @@ const PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
 export function visibleWidth(text: string): number {
 	if (text.length === 0) return 0;
 	if (PRINTABLE_ASCII.test(text)) return text.length;
+	// pi-tui expands tabs before segmenting, so a mark after a tab joins the
+	// last space's cluster; doing the same keeps the two measures identical.
+	if (text.includes("\t")) text = text.replace(/\t/g, "   ");
 	let clean = "";
 	for (let i = 0; i < text.length; ) {
 		const esc = escapeAt(text, i);
@@ -204,6 +211,29 @@ export function sliceColumns(text: string, maxCols: number): { text: string; wid
 	return fitPainted(text, maxCols);
 }
 
+/**
+ * Longest suffix of PLAIN (escape-free) text whose visible width is ≤
+ * `maxCols`, cut on a grapheme boundary: the counterpart of `sliceColumns` for
+ * text that keeps its tail, such as a path whose deepest folders matter most.
+ */
+export function tailColumns(text: string, maxCols: number): { text: string; width: number } {
+	if (maxCols <= 0) return { text: "", width: 0 };
+	if (PRINTABLE_ASCII.test(text)) {
+		const tail = text.slice(Math.max(0, text.length - maxCols));
+		return { text: tail, width: tail.length };
+	}
+	const graphemes = [...graphemeSegmenter.segment(text)].map((s) => s.segment);
+	let width = 0;
+	let start = graphemes.length;
+	while (start > 0) {
+		const w = graphemeWidth(graphemes[start - 1]);
+		if (width + w > maxCols) break;
+		width += w;
+		start--;
+	}
+	return { text: graphemes.slice(start).join(""), width };
+}
+
 /**
  * Hard-wrap text into chunks each ≤ `columns` visible columns, on grapheme
  * boundaries. A single glyph wider than the whole budget occupies its own chunk
@@ -253,7 +283,8 @@ export function fitPainted(line: string, maxCols: number): { text: string; width
 			continue;
 		}
 		// Consume the visible run up to the next escape, segment it into graphemes.
-		let end = i;
+		// An ESC that starts no sequence is text (width 0), so the run starts past it.
+		let end = line.charCodeAt(i) === 0x1b ? i + 1 : i;
 		while (end < line.length && line.charCodeAt(end) !== 0x1b) end++;
 		for (const { segment } of graphemeSegmenter.segment(line.slice(i, end))) {
 			const w = graphemeWidth(segment);

package/extensions/lib/timer-ops.ts

@@ -0,0 +1,20 @@
+/**
+ * An injectable timer (pure), so an idle-timer state machine is unit-tested
+ * with fake timers, and the real adapter both recap and idle-compact run on.
+ */
+
+export interface TimerOps {
+	/** Schedule `cb` after `ms`; return a handle for `clear`. */
+	set(cb: () => void, ms: number): unknown;
+	clear(handle: unknown): void;
+}
+
+/** `setTimeout` with the handle unref'd, so a pending idle timer never keeps a one-shot process alive. */
+export const unrefTimers: TimerOps = {
+	set: (cb, ms) => {
+		const handle = setTimeout(cb, ms);
+		handle.unref?.();
+		return handle;
+	},
+	clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};

package/extensions/lib/tool-additions.ts

@@ -0,0 +1,149 @@
+/**
+ * Claude Code's `tool_addition` for tools that arrive mid-session (pure). One
+ * Code stores the arrival as the deferred-tool addendum one-shot
+ * (lib/deferred.ts deferredAddendumText), which reads correctly on any model.
+ * On a first-party model that takes mid-conversation tool changes, the
+ * addendum leaves the message that carries it for a system message right
+ * after it: Claude Code's sentence and names, then one reference-form
+ * `tool_addition` block per tool, each declared deferred in `tools`. The model
+ * can then call the tool without a `tool_search` round trip (findings §55
+ * P1). Elsewhere the addendum stays as it is.
+ *
+ * An addendum is matched as a whole block, never inside other text: in a tool
+ * result at `context` time, while the result's blocks are still separate and
+ * keyed by its call id (`liftAddenda`), and on a user message as a whole part
+ * (a one-shot pinned there).
+ */
+
+import { MID_CONVERSATION_SYSTEM_BETA, MID_CONVERSATION_TOOL_CHANGES_BETA, reseatMessageMark } from "./anthropic-payload.ts";
+import { byWireCallId, systemRoleLayout, type WireMessage, type WirePart, withoutParts } from "./system-role.ts";
+
+/** The first line of the stored addendum; the names follow, one per line. */
+export const ADDENDUM_HEAD =
+	"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.";
+
+/** Claude Code's sentence before the names, in its tool-addition message. */
+export const TOOLS_AVAILABLE = "The following tools just became available and are ready to use:";
+
+/** Claude Code's betas for a reference-form tool addition in a system message. */
+export const TOOL_ADDITION_BETAS = [MID_CONVERSATION_SYSTEM_BETA, MID_CONVERSATION_TOOL_CHANGES_BETA];
+
+/**
+ * Whether the model takes Claude Code's reference-form `tool_addition`:
+ * first-party Anthropic on the system-role layout, with pi's catalog flag for
+ * mid-conversation tool changes (Opus 5.5, Sonnet 5.5 and Fable 5.1 among them).
+ */
+export function supportsToolAdditions(model: { id?: string; provider?: string; api?: string; compat?: unknown } | undefined): boolean {
+	if (!model || model.provider !== "anthropic" || systemRoleLayout({ id: model.id ?? "", api: model.api ?? "", compat: model.compat }) !== "anthropic") return false;
+	return (model.compat as { supportsMidConvoToolChanges?: boolean } | undefined)?.supportsMidConvoToolChanges === true;
+}
+
+const OPEN = `<system-reminder>\n${ADDENDUM_HEAD}\n`;
+const CLOSE = "\n</system-reminder>";
+
+/** The names a whole framed addendum block lists; undefined for any other text. */
+export function addendumNames(text: string): string[] | undefined {
+	if (!text.startsWith(OPEN) || !text.endsWith(CLOSE)) return undefined;
+	return text
+		.slice(OPEN.length, -CLOSE.length)
+		.split("\n")
+		.filter((line) => line.length > 0);
+}
+
+type StoredBlock = { type?: string; text?: string };
+type StoredMessage = { role: string; toolCallId?: string; content?: unknown };
+
+/**
+ * The context-time step: each tool result's addendum block leaves the result,
+ * its names kept under the call id, for the payload step to send as an
+ * addition after that result. Returns the input when nothing changed.
+ */
+export function liftAddenda<T extends StoredMessage>(messages: T[]): { messages: T[]; byCall: Map<string, string[]> } {
+	const byCall = new Map<string, string[]>();
+	let changed = false;
+	const out = messages.map((message) => {
+		if (message.role !== "toolResult" || !Array.isArray(message.content) || !message.toolCallId) return message;
+		const names: string[] = [];
+		const kept = (message.content as StoredBlock[]).filter((block) => {
+			const found = block?.type === "text" && typeof block.text === "string" ? addendumNames(block.text) : undefined;
+			if (found) names.push(...found);
+			return !found;
+		});
+		if (names.length === 0) return message;
+		changed = true;
+		byCall.set(message.toolCallId, names);
+		return { ...message, content: kept };
+	});
+	return { messages: changed ? out : messages, byCall };
+}
+
+/**
+ * The Anthropic payload with a tool-addition system message after each user
+ * message that answers a call `liftAddenda` lifted an addendum from, or that
+ * carries a pinned addendum part (removed). Also returns every name added: they
+ * must be declared deferred in `tools`. With `references: false` the message
+ * is Claude Code's sentence and names alone, for a request whose tools cannot
+ * be referenced (OAuth renames them): the tools are active, so the model can
+ * still call them. Undefined when there is none.
+ */
+export function withToolAdditions(
+	payload: Record<string, unknown>,
+	byCall: ReadonlyMap<string, readonly string[]>,
+	references = true,
+): { payload: Record<string, unknown>; names: string[] } | undefined {
+	const messages = payload.messages;
+	if (!Array.isArray(messages)) return undefined;
+	const out: WireMessage[] = [];
+	const all = new Set<string>();
+	for (const message of messages as WireMessage[]) {
+		if (message?.role !== "user" || !Array.isArray(message.content)) {
+			out.push(message);
+			continue;
+		}
+		const names: string[] = [];
+		const parts = message.content as WirePart[];
+		for (const part of parts) {
+			const called = part?.type === "tool_result" && typeof part.tool_use_id === "string" ? byWireCallId(byCall, part.tool_use_id) : undefined;
+			if (called) names.push(...called);
+		}
+		const pinnedNames = (part: WirePart) => (part?.type === "text" && typeof part.text === "string" ? addendumNames(part.text) : undefined);
+		// A pinned addendum part goes, keeping pi's cache mark; a message it would empty keeps it.
+		const kept = withoutParts(parts, (part) => pinnedNames(part) !== undefined) ?? parts;
+		if (kept !== parts) for (const part of parts) names.push(...(pinnedNames(part) ?? []));
+		if (names.length === 0) {
+			out.push(message);
+			continue;
+		}
+		const unique = [...new Set(names)];
+		for (const name of unique) all.add(name);
+		out.push(kept.length === parts.length ? message : { ...message, content: kept }, {
+			role: "system",
+			content: [
+				{ type: "text", text: [TOOLS_AVAILABLE, ...unique].join("\n") },
+				...(references ? unique.map((name) => ({ type: "tool_addition", tool: { type: "tool_reference", name } })) : []),
+			],
+		});
+	}
+	if (all.size === 0) return undefined;
+	return { payload: { ...payload, messages: reseatMessageMark(out) }, names: [...all] };
+}
+
+/** A stored message as far as the addendum scan is concerned. */
+type BranchEntry = { type?: string; message?: { role?: string; content?: unknown } };
+
+/**
+ * The names every addendum persisted into a tool result on the branch
+ * announced: on resume they are re-activated, since their addition blocks
+ * are rebuilt from the same stored blocks and the model may call them.
+ */
+export function addendumNamesOnBranch(branch: readonly BranchEntry[]): string[] {
+	const names = new Set<string>();
+	for (const entry of branch) {
+		const message = entry?.type === "message" ? entry.message : undefined;
+		if (message?.role !== "toolResult" || !Array.isArray(message.content)) continue;
+		for (const block of message.content as StoredBlock[]) {
+			for (const name of (typeof block?.text === "string" ? addendumNames(block.text) : undefined) ?? []) names.add(name);
+		}
+	}
+	return [...names];
+}