one-code-extension 0.4.1 → 0.6.0

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,129 @@
+/**
+ * Claude Code's `tool_addition` for tools that arrive mid-session (pure). One
+ * Code renders the arrival as the deferred-tool addendum on the request's
+ * tail (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] };
+}

package/extensions/lib/tool-call-corruption.ts

@@ -0,0 +1,134 @@
+/**
+ * A streamed tool call's damage. `corrupt` is certain (not one JSON value, a
+ * shell command ending inside an open double quote): the call is blocked and
+ * the turn stopped. `suspect` has the shape of a cut but also of a valid
+ * command (an option followed by one trailing blank): the call goes back to the
+ * model once, and a repeat in the same run counts as corrupt.
+ */
+export interface ToolCallDamage {
+	kind: "corrupt" | "suspect";
+	reason: string;
+}
+
+// The last word is an option followed by one blank, or a long option with an
+// empty `=` value: `grep -rn "x"` and `--include="*.py"` cut at the escaped
+// quote (findings §61, Morph). A bare `FOO=` is a valid assignment.
+const CUT_AFTER_OPTION = /(?:^|\s)(-{1,2}[A-Za-z][\w-]*)[ \t]$|(?:^|\s)(--[A-Za-z][\w-]*=)$/;
+// Heredocs and here-strings (bash `<<`, `<<<`; PowerShell `@"…"@`, `@'…'@`)
+// carry quotes the scan below cannot pair, so it does not judge them.
+const HERE_DOCUMENT = /<<|@["']/;
+
+/** Inspect one tool call's raw streamed arguments before pi's tolerant parsing hides damage. */
+export function toolCallCorruptionReason(toolName: string, rawArguments: string): ToolCallDamage | undefined {
+	// A tool with no parameters may stream no argument text at all; pi reads it as {}.
+	if (rawArguments.trim() === "") return;
+	let args: unknown;
+	try {
+		args = JSON.parse(rawArguments);
+	} catch {
+		return { kind: "corrupt", reason: "The raw tool-call arguments are not exactly one JSON value." };
+	}
+	if (toolName !== "bash" && toolName !== "powershell" && toolName !== "monitor") return;
+	if (!args || typeof args !== "object" || !("command" in args) || typeof args.command !== "string") return;
+	const cut = CUT_AFTER_OPTION.exec(args.command);
+	if (cut) {
+		return {
+			kind: "suspect",
+			reason: `The shell command ends with "${cut[1] ?? cut[2]}" and nothing after it, the shape of arguments cut off before a quoted string.`,
+		};
+	}
+	const command = args.command.trimEnd();
+	if (!command.endsWith('"') || HERE_DOCUMENT.test(command)) return;
+
+	let singleQuoted = false;
+	let doubleQuoted = false;
+	const escape = toolName === "powershell" ? "`" : "\\";
+	for (let i = 0; i < command.length; i++) {
+		const char = command[i];
+		if (singleQuoted) {
+			if (char === "'") singleQuoted = false;
+		} else if (char === escape) {
+			i++;
+		} else if (char === "'" && !doubleQuoted) {
+			singleQuoted = true;
+		} else if (char === '"') {
+			doubleQuoted = !doubleQuoted;
+		} else if (char === "#" && !doubleQuoted && (i === 0 || /[\s;&|(]/.test(command[i - 1]))) {
+			// A comment runs to the end of its line.
+			const newline = command.indexOf("\n", i);
+			if (newline === -1) break;
+			i = newline;
+		}
+	}
+	if (doubleQuoted) return { kind: "corrupt", reason: "The shell command ends with an unbalanced double quote, indicating truncated tool-call arguments." };
+}
+
+// GLM's native tool-call tags, which a broken upstream parser leaks into the JSON arguments.
+const TOOL_CALL_MARKUP = /<\/arg_value>\s{0,8}<arg_key>|<\/arg_key>\s{0,8}<arg_value>|<\/tool_call>\s{0,8}<tool_call>/g;
+const LONGEST_MARKUP = 40;
+
+/** The number of markup matches that marks a streaming call as leaked. */
+export const TOOL_CALL_MARKUP_LIMIT = 2;
+/**
+ * The same inside file content (write, edit, notebook_edit), which can quote
+ * the markup legitimately (this repo's tests do); a leak there repeats without
+ * end and passes it within a few thousand characters.
+ */
+export const CONTENT_MARKUP_LIMIT = 50;
+
+// A string value under one of these keys is file content.
+const CONTENT_KEY = /"(?:content|oldText|newText|new_source)"\s*:\s*$/;
+
+/** Whether `index` sits in a string value under a content key: the nearest unescaped quote before it opens that value. */
+function inContentValue(text: string, index: number): boolean {
+	// lastIndexOf clamps a negative start to 0, so stop before it can repeat a quote at 0.
+	for (let quote = index; quote > 0; ) {
+		quote = text.lastIndexOf('"', quote - 1);
+		if (quote < 0) break;
+		let slashes = 0;
+		while (text[quote - 1 - slashes] === "\\") slashes++;
+		if (slashes % 2 === 0) return CONTENT_KEY.test(text.slice(Math.max(0, quote - 32), quote));
+	}
+	return false;
+}
+
+/**
+ * Count native tool-call markup in `text` from `from` on, for a call whose
+ * arguments are still streaming, apart (`contentCount`) inside file content;
+ * `next` is where the following scan resumes, so each delta is scanned once.
+ */
+export function scanToolCallMarkup(text: string, from: number): { count: number; contentCount: number; next: number } {
+	TOOL_CALL_MARKUP.lastIndex = from;
+	let count = 0;
+	let contentCount = 0;
+	let next = from;
+	for (let match = TOOL_CALL_MARKUP.exec(text); match; match = TOOL_CALL_MARKUP.exec(text)) {
+		if (inContentValue(text, match.index)) contentCount++;
+		else count++;
+		next = TOOL_CALL_MARKUP.lastIndex;
+	}
+	return { count, contentCount, next: Math.max(next, text.length - LONGEST_MARKUP) };
+}
+
+/**
+ * Blank space a tool call may stream after its last argument character before
+ * the stream counts as runaway. Only a run holding a raw tab or newline
+ * counts: inside a JSON string those are escaped, so such a run is padding
+ * between tokens, never argument content (a string may hold any run of spaces).
+ */
+export const RUNAWAY_PADDING_LIMIT = 10_000;
+
+export interface TrailingPadding {
+	run: number;
+	structural: boolean;
+}
+
+/** The trailing blank run after one more streamed delta. */
+export function trailingPadding(previous: TrailingPadding | undefined, delta: string): TrailingPadding {
+	const last = delta.search(/\S\s*$/);
+	if (last < 0) {
+		return { run: (previous?.run ?? 0) + delta.length, structural: (previous?.structural ?? false) || /[\t\n\r]/.test(delta) };
+	}
+	const tail = delta.slice(last + 1);
+	return { run: tail.length, structural: /[\t\n\r]/.test(tail) };
+}

package/extensions/lib/tool-path.ts

@@ -0,0 +1,66 @@
+/**
+ * Resolve a file tool's `path` argument exactly as pi's own `read`, `edit` and
+ * `write` do (`resolveToCwd` in pi-coding-agent's `core/tools/path-utils.js`,
+ * over `utils/paths.js normalizePath`), vendored because the package does not
+ * export it. Anything that reasons about the file a pi tool will touch (the
+ * file tracker's read-before-write and stale-edit guards, our notebook tool,
+ * the worktree rewrite of relative paths) must land on the same file, or a spelling pi accepts (`~/x`, `@x`,
+ * `file:///…`, a non-breaking space, Git Bash's `/c/…` on Windows) slips past
+ * the guard (TOOLS-REVIEW-2026-09-26 M1). Pure: no pi imports.
+ *
+ * Mirrors pi 0.87.1 to 0.99.2: Unicode spaces fold to a plain space, one
+ * leading `@` is dropped, on Windows a Git Bash/MSYS/Cygwin/WSL drive path
+ * becomes `C:\…`, `~` and `~/` expand to the home directory (and `~\` on
+ * Windows), a `file://` URL becomes its path, and a relative result resolves
+ * against `cwd`.
+ */
+
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/** pi's `normalizeWindowsShellPath`: `/c/x`, `/mnt/c/x`, `/cygdrive/c/x` to `C:\x`. */
+function windowsShellPath(path: string): string {
+	if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\")) return path;
+	const match = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+	if (!match) return path;
+	return `${match[1].toUpperCase()}:\\${match[2]?.replaceAll("/", "\\") ?? ""}`;
+}
+
+export interface ToolPathOptions {
+	home?: string;
+	platform?: NodeJS.Platform;
+}
+
+/**
+ * `raw` as pi's file tools read it before resolving it against a cwd: the
+ * steps above except the last. Callers that must tell a relative path from an
+ * absolute one the way pi will (the worktree rewrite) judge this, not `raw`.
+ */
+export function normalizeToolPath(raw: string, options: ToolPathOptions = {}): string {
+	const platform = options.platform ?? process.platform;
+	const home = options.home ?? homedir();
+	let path = raw.replace(UNICODE_SPACES, " ");
+	if (path.startsWith("@")) path = path.slice(1);
+	if (platform === "win32") path = windowsShellPath(path);
+	if (path === "~") return home;
+	if (path.startsWith("~/") || (platform === "win32" && path.startsWith("~\\"))) return join(home, path.slice(2));
+	if (/^file:\/\//.test(path)) {
+		// A URL this platform cannot map (`file:///x` on Windows has no drive)
+		// stays as written: pi's tool then fails on it, and a guard must not throw.
+		try {
+			return fileURLToPath(path);
+		} catch {
+			return path;
+		}
+	}
+	return path;
+}
+
+/** The absolute path a pi file tool resolves `raw` to from `cwd`. */
+export function resolveToolPath(raw: string, cwd: string, options: ToolPathOptions = {}): string {
+	const path = normalizeToolPath(raw, options);
+	return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}

package/extensions/lib/tool-variants.ts

@@ -0,0 +1,69 @@
+/**
+ * Tool descriptions that follow the session, as Claude Code's do.
+ *
+ * Claude Code sends its strongest models short tool descriptions and its
+ * weakest the long ones it wrote for Haiku 4.5; its Bash text also changes
+ * with the permission mode. One Code keys the same split on the model's tier
+ * (`working-docs/decisions/system-prompt.md`, "Four registers"): frontier and
+ * workhorse get the short forms, cheap and tiny the long ones, on every
+ * provider.
+ *
+ * pi copies a tool's description when the tool is registered, so a tool whose
+ * text depends on the session is registered again when that text changes
+ * (`registerVariantTool`). This can also move a tool in pi's active tool
+ * order, so only a model-tier change may re-register after the first request.
+ * The tier changes with the model, which starts a new provider cache anyway.
+ * Permission-mode variants freeze at the first request (bash/index.ts); live
+ * changes ride reminders and the permission gate, never the cached tool list.
+ */
+
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { PromptTier } from "./model-tier.ts";
+import { sessionModelTier } from "./session-model-tier.ts";
+
+/** Which of Claude Code's description forms a tool carries. */
+export type DescriptionForm = "short" | "long";
+
+/** Claude Code's short forms on frontier and workhorse; its long forms on cheap and tiny. */
+export function descriptionForm(tier: PromptTier): DescriptionForm {
+	return tier === "cheap" || tier === "tiny" ? "long" : "short";
+}
+
+// Every tool definition shape registerTool accepts; the concrete generics differ per tool.
+type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+/**
+ * Register `define(initial)` now, and return a setter that registers the tool
+ * again with `define(next)` when `next` differs from the variant in force.
+ * Repeated calls with the same variant do nothing, so callers can apply the
+ * session's facts on every event that might change them.
+ */
+export function registerVariantTool<V>(pi: ExtensionAPI, initial: V, define: (variant: V) => AnyToolDefinition): (variant: V) => void {
+	let current = initial;
+	pi.registerTool(define(initial));
+	return (next: V) => {
+		if (next === current) return;
+		current = next;
+		pi.registerTool(define(next));
+	};
+}
+
+/**
+ * Register `tool` with the description `describe` gives the session model's
+ * form, following it through the session: the one call each tool with a
+ * short and a long form makes.
+ */
+export function registerFormTool(pi: ExtensionAPI, tool: AnyToolDefinition, describe: (form: DescriptionForm) => string): void {
+	followDescriptionForm(pi, registerVariantTool<DescriptionForm>(pi, "short", (form) => ({ ...tool, description: describe(form) })));
+}
+
+/** Apply the frozen session tier's form (and the tier it came from) only at session and model boundaries. */
+export function followDescriptionForm(pi: ExtensionAPI, apply: (form: DescriptionForm, tier: PromptTier) => void): void {
+	const requestTier = sessionModelTier(pi);
+	const follow = () => {
+		const tier = requestTier();
+		apply(descriptionForm(tier), tier);
+	};
+	pi.on("session_start", follow);
+	pi.on("model_select", follow);
+}