one-code-extension 0.3.0 → 0.4.0

package/extensions/hooks/settings.ts

@@ -17,11 +17,19 @@ import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { CC_HOOK_EVENTS, type CcHookEvent } from "./protocol.ts";
 
+/** Claude Code's per-hook `shell` field: which interpreter runs the command string. */
+export type HookShell = "bash" | "powershell";
+
 export interface HookCommand {
 	type: "command";
 	command: string;
 	/** Seconds, CC convention. */
 	timeout?: number;
+	/**
+	 * Unset means the platform default: bash where one exists, PowerShell on
+	 * Windows without Git Bash (Claude Code's rule — executor.ts `defaultHookShell`).
+	 */
+	shell?: HookShell;
 }
 
 export interface HookMatcherEntry {
@@ -97,10 +105,17 @@ export function parseHooksBlock(raw: unknown, origin: string, diagnostics: strin
 					diagnostics.push(`${origin}: ${event} hook of type "${String(candidate?.type)}" skipped (only "command" is supported)`);
 					continue;
 				}
+				const { shell } = hook as { shell?: unknown };
+				let hookShell: HookShell | undefined;
+				if (shell !== undefined) {
+					if (shell === "bash" || shell === "powershell") hookShell = shell;
+					else diagnostics.push(`${origin}: ${event} hook shell "${String(shell)}" ignored (use "bash" or "powershell")`);
+				}
 				hooks.push({
 					type: "command",
 					command: candidate.command,
 					timeout: typeof candidate.timeout === "number" && candidate.timeout > 0 ? candidate.timeout : undefined,
+					shell: hookShell,
 				});
 			}
 			if (hooks.length > 0) {

package/extensions/lib/branch-restore.ts

@@ -18,6 +18,18 @@
 
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 
+/** A tool result as the session stores it (pi's `ToolResultMessage` reaches us only through `SessionEntry`). */
+export type BranchToolResult = Extract<Extract<SessionEntry, { type: "message" }>["message"], { role: "toolResult" }>;
+
+/** Every tool result on the branch from one of `toolNames`, oldest first. */
+export function* toolResultsOnBranch(branch: readonly SessionEntry[], toolNames: ReadonlySet<string>): Generator<BranchToolResult> {
+	for (const entry of branch) {
+		if (entry.type !== "message") continue;
+		const msg = entry.message;
+		if (msg.role === "toolResult" && toolNames.has(msg.toolName)) yield msg;
+	}
+}
+
 export function restoreLatestDetails<T>(
 	branch: SessionEntry[],
 	toolNames: ReadonlySet<string>,

package/extensions/lib/claude-context.ts

@@ -34,7 +34,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { tryReadFile } from "./plugins.ts";
-import { expandTilde } from "./paths.ts";
+import { absoluteFrom, expandTilde } from "./paths.ts";
 
 /** One CLAUDE.md-family file as it appears in the block. `content` is raw (untrimmed). */
 export interface ContextFile {
@@ -116,8 +116,7 @@ function firstOneCodeFile(dir: string): string | null {
 
 /** Resolve an `@import` reference: `~`/`~/` → home, absolute as-is, else relative to `baseDir`. */
 function resolveImportPath(ref: string, baseDir: string, home: string): string {
-	const p = expandTilde(ref, home);
-	return isAbsolute(p) ? p : join(baseDir, p);
+	return absoluteFrom(baseDir, expandTilde(ref, home));
 }
 
 /**

package/extensions/lib/claude-settings.ts

@@ -46,6 +46,25 @@ export function readSettingsFile(path: string): ClaudeSettingsFile | undefined {
 	}
 }
 
+/**
+ * Claude Code's `env` block from the USER settings file only: the string
+ * values it would export into every session. Read for `CLAUDE_CODE_GIT_BASH_PATH`
+ * (lib/shell-spawn.ts). Project and local files are deliberately not merged —
+ * a checked-in `env` that pointed the shell at a `tools/bash` inside the repo
+ * would run that binary for every hook and background command, and the file
+ * is the repository's, not the user's (Claude Code gates the same block behind
+ * its project-trust prompt).
+ */
+export function readSettingsEnv(home: string): Record<string, string> {
+	const env = readSettingsFile(claudeUserSettingsPath(home))?.env;
+	if (!env || typeof env !== "object" || Array.isArray(env)) return {};
+	const out: Record<string, string> = {};
+	for (const [key, value] of Object.entries(env as Record<string, unknown>)) {
+		if (typeof value === "string") out[key] = value;
+	}
+	return out;
+}
+
 /**
  * Claude Code's plugin enabled-state map (`{"name@marketplace": boolean}`),
  * merged across the three settings files — later files win per key.

package/extensions/lib/command-launch.ts

@@ -0,0 +1,71 @@
+/**
+ * How to spawn a user-named command on this platform (pure apart from the
+ * PATH lookup it is given). For every bare `spawn(command, args)` of a command
+ * the user or a config names — a language server, `$EDITOR` — never for the
+ * shell tools, which go through lib/shell-spawn.ts.
+ *
+ * On Windows an npm-installed tool is a `.cmd` shim
+ * (`typescript-language-server.cmd`, VS Code's `code.cmd`): `whichOnPath`
+ * finds it through PATHEXT, but a bare `spawn(command)` does not — libuv tries
+ * the name and `.com`/`.exe` only, so the spawn fails with ENOENT (findings
+ * §22) — and Node refuses to run a batch file without a shell anyway (20.12+,
+ * CVE-2024-27980). Such a shim is started through `cmd.exe /d /s /c` with the
+ * command line quoted the way Node's own `shell: true` does, and the arguments
+ * passed verbatim so Node does not quote them a second time. Anything that
+ * resolves to a real executable, or does not resolve at all (the caller's
+ * ENOENT handling then applies — lsp/install-hints.ts for servers), is spawned
+ * as given. Elsewhere the launch is the command and arguments unchanged.
+ */
+
+import { system32Path } from "./paths.ts";
+import { whichOnPath } from "./which.ts";
+
+export interface CommandLaunch {
+	command: string;
+	args: string[];
+	/** Set for a cmd.exe launch: the single command-line argument is already quoted. */
+	windowsVerbatimArguments?: boolean;
+}
+
+export interface CommandLaunchOptions {
+	platform?: string;
+	which?: (command: string, env: NodeJS.ProcessEnv, platform: string) => string | undefined;
+}
+
+/** A batch-file shim, by extension (the filesystem folds case; PATHEXT spells them upper-case). */
+export function isBatchFile(path: string): boolean {
+	return /\.(cmd|bat)$/i.test(path);
+}
+
+/**
+ * One argument for a cmd.exe command line: quoted when it holds whitespace or
+ * a cmd metacharacter, with the C runtime's rules for what the program the
+ * shim runs will read back — an inner quote is `\"`, and a run of backslashes
+ * directly before a quote (an inner one, or the closing one after a path that
+ * ends in `\`) is doubled, or it would escape that quote. A literal `%` cannot
+ * be protected: cmd.exe expands `%NAME%` before it reads the quotes, the same
+ * limit Node's `shell: true` has, and `.cmd` shims are only reached this way.
+ */
+export function quoteForCmd(arg: string): string {
+	if (arg === "") return '""';
+	if (!/[\s"&|<>^()]/.test(arg)) return arg;
+	const body = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1");
+	return `"${body}"`;
+}
+
+export function commandLaunch(command: string, args: string[], env: NodeJS.ProcessEnv, opts: CommandLaunchOptions = {}): CommandLaunch {
+	const platform = opts.platform ?? process.platform;
+	if (platform !== "win32") return { command, args };
+	const resolved = (opts.which ?? whichOnPath)(command, env, platform);
+	if (!resolved) return { command, args };
+	if (!isBatchFile(resolved)) return { command: resolved, args };
+	const line = [resolved, ...args].map(quoteForCmd).join(" ");
+	// cmd.exe is located from the PROCESS environment, never from `env`: a
+	// server's config may set its own variables (a plugin's `.lsp.json` env
+	// block), and `SystemRoot` among them must not redirect the interpreter.
+	return {
+		command: system32Path("cmd.exe"),
+		args: ["/d", "/s", "/c", `"${line}"`],
+		windowsVerbatimArguments: true,
+	};
+}

package/extensions/lib/deferred.ts

@@ -10,6 +10,8 @@
  * `{ name, keywords? }` while extensions are loading (before session_start).
  */
 
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { toolResultsOnBranch } from "./branch-restore.ts";
 import { parseClaudeVersion } from "./model-tier.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
 
@@ -106,51 +108,189 @@ export interface DeferrableToolInfo {
 	parameters?: { properties?: unknown; required?: unknown };
 }
 
+/** The `tool_search` calls that loaded tools: each call's id → the names it loaded. */
+export type ToolSearchLoads = ReadonlyMap<string, readonly string[]>;
+
+/**
+ * Every load recorded on a session branch: a `tool_search` result whose
+ * persisted `details.added` names the tools it activated. Read once at
+ * session start (a resumed session's earlier loads); loads made during the
+ * session are captured at the call itself.
+ */
+export function toolSearchLoads(branch: readonly SessionEntry[]): Map<string, string[]> {
+	const loads = new Map<string, string[]>();
+	for (const message of toolResultsOnBranch(branch, TOOL_SEARCH_NAMES)) {
+		const added = (message.details as { added?: unknown } | undefined)?.added;
+		if (!Array.isArray(added)) continue;
+		const names = added.filter((n): n is string => typeof n === "string");
+		if (names.length > 0) loads.set(message.toolCallId, names);
+	}
+	return loads;
+}
+const TOOL_SEARCH_NAMES: ReadonlySet<string> = new Set(["tool_search"]);
+
+type WireTool = Record<string, unknown> & { name: string };
+type WireBlock = Record<string, unknown> & { type?: unknown };
+type WireMessage = { role?: unknown; content?: unknown };
+
+/** A deferred definition in pi's own `convertTools` shape (findings §7). */
+function deferredDefinition(tool: DeferrableToolInfo): WireTool {
+	return {
+		name: tool.name,
+		description: tool.description ?? "",
+		input_schema: {
+			type: "object",
+			properties: tool.parameters?.properties ?? {},
+			required: tool.parameters?.required ?? [],
+		},
+		defer_loading: true,
+	};
+}
+
+/** The list with pi's cache breakpoint on its last item (a no-op without one). */
+function withBreakpointOnLast<T extends Record<string, unknown>>(items: T[], cache_control: unknown): T[] {
+	if (cache_control === undefined || items.length === 0) return items;
+	return [...items.slice(0, -1), { ...items[items.length - 1], cache_control }];
+}
+
 /**
- * An Anthropic request with every deferred tool that pi left out appended as a
- * `defer_loading: true` definition, sorted by name (pi's own entries stay first
- * and untouched). Anthropic keeps deferred definitions out of the cached prefix,
- * but ADDING one to `tools` mid-session still re-caches the message history —
- * measured 2026-09-04 on Sonnet 5: the request after a `tool_search` load read
- * only tools + system (8.7k of 25k tokens); with the full deferred set present
- * from request 1 it read all 25k. Unloaded deferred definitions cost no input
- * tokens, so sending them always is free and keeps `tools` byte-stable.
+ * 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
+ * tools stay deferred on the wire", findings §7).
+ *
+ * - Every registry tool `isDeferred` that is not eager on the wire is appended
+ *   as a `defer_loading: true` definition, sorted by name; pi's own rendering
+ *   of a later-deferred registry tool is replaced by ours.
+ * - A loaded tool pi promoted to eager is demoted back to deferred, the tools
+ *   cache breakpoint moves to the last remaining eager tool, and the
+ *   `tool_search` result that loaded it (`loads`) is rewritten to
+ *   `tool_reference` blocks, its own content moving to trailing sibling blocks
+ *   that take the result's breakpoint (Anthropic rejects references mixed with
+ *   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).
+ * - pi's own deferred entries that are not registry tools (its
+ *   `__pi_deferred_placeholder__`) stay in place.
  *
- * Returns undefined (leave the payload alone) when there is nothing to add, the
- * request carries no tools, or the tool names on the wire are not the registry's
- * (pi's OAuth "stealth" mode renames them to Claude Code casing, and a name that
- * cannot be matched must not be duplicated). Schemas follow pi's own
- * `convertTools` shape. Never mutates its input.
+ * Returns undefined (leave the payload alone) when the request carries no
+ * tools or the wire names are not the registry's (pi's OAuth "stealth" mode
+ * renames them to Claude Code casing, and an unmatched name must not be
+ * duplicated). Never mutates its input.
  */
-export function withDeferredToolDefinitions(
+export function stabilizeDeferredTools(
 	payload: Record<string, unknown>,
 	tools: readonly DeferrableToolInfo[],
 	isDeferred: (name: string) => boolean,
+	loads: ToolSearchLoads = new Map(),
 ): Record<string, unknown> | undefined {
 	const existing = payload.tools;
 	if (!Array.isArray(existing) || existing.length === 0) return undefined;
 	const registry = new Set(tools.map((t) => t.name));
-	const present = new Set<string>();
-	for (const tool of existing) {
-		const name = (tool as { name?: unknown } | null)?.name;
-		if (typeof name !== "string" || !registry.has(name)) return undefined;
-		present.add(name);
+
+	const eager: WireTool[] = [];
+	const anchors: WireTool[] = [];
+	for (const raw of existing) {
+		const tool = raw as WireTool | null;
+		if (typeof tool?.name !== "string") return undefined;
+		if (!registry.has(tool.name)) {
+			if (tool.defer_loading === true) anchors.push(tool);
+			else return undefined;
+			continue;
+		}
+		if (tool.defer_loading !== true) eager.push(tool);
+	}
+
+	const messages: WireMessage[] = Array.isArray(payload.messages) ? (payload.messages as WireMessage[]) : [];
+	const referencesAt = new Map<string, string[]>();
+	const demoted = new Set<string>();
+	if (loads.size > 0 && eager.some((tool) => isDeferred(tool.name))) {
+		// Message index of each tool's first use and of each tool result: a
+		// reference is valid only ahead of every use of the tool.
+		const firstUse = new Map<string, number>();
+		const resultAt = new Map<string, number>();
+		messages.forEach((message, index) => {
+			if (!Array.isArray(message?.content)) return;
+			for (const block of message.content as WireBlock[]) {
+				if (block?.type === "tool_use" && typeof block.name === "string" && !firstUse.has(block.name)) {
+					firstUse.set(block.name, index);
+				} else if (block?.type === "tool_result" && typeof block.tool_use_id === "string") {
+					resultAt.set(block.tool_use_id, index);
+				}
+			}
+		});
+		// 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 });
+			}
+		}
+		for (const tool of eager) {
+			if (!isDeferred(tool.name)) continue;
+			const loader = loaderOf.get(tool.name);
+			if (loader === undefined) continue;
+			const use = firstUse.get(tool.name);
+			if (use !== undefined && use < loader.at) continue;
+			demoted.add(tool.name);
+			referencesAt.set(loader.callId, [...(referencesAt.get(loader.callId) ?? []), tool.name]);
+		}
 	}
-	const extra = tools
-		.filter((t) => isDeferred(t.name) && !present.has(t.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);
+	const keptEager = withBreakpointOnLast(
+		eager.filter((tool) => !demoted.has(tool.name)),
+		last !== undefined && demoted.has(last.name) ? last.cache_control : undefined,
+	);
+	if (keptEager.length === 0) return undefined;
+	const eagerNames = new Set(keptEager.map((tool) => tool.name));
+	const deferred = tools
+		.filter((t) => isDeferred(t.name) && !eagerNames.has(t.name))
 		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
-		.map((t) => ({
-			name: t.name,
-			description: t.description ?? "",
-			input_schema: {
-				type: "object",
-				properties: t.parameters?.properties ?? {},
-				required: t.parameters?.required ?? [],
-			},
-			defer_loading: true,
-		}));
-	if (extra.length === 0) return undefined;
-	return { ...payload, tools: [...existing, ...extra] };
+		.map(deferredDefinition);
+	return {
+		...payload,
+		tools: [...keptEager, ...anchors, ...deferred],
+		messages: referencesAt.size === 0 ? payload.messages : messages.map((m) => withToolReferences(m, referencesAt)),
+	};
+}
+
+/**
+ * The user message with each loading `tool_result` rewritten to carry its
+ * `tool_reference` blocks and its original content moved to trailing sibling
+ * blocks; a breakpoint on the rewritten result moves to the new last block so
+ * the whole message stays inside the cached prefix.
+ */
+function withToolReferences(message: WireMessage, referencesAt: ReadonlyMap<string, readonly string[]>): WireMessage {
+	if (message?.role !== "user" || !Array.isArray(message.content)) return message;
+	const content = message.content as WireBlock[];
+	if (!content.some((block) => block?.type === "tool_result" && referencesAt.has(block.tool_use_id as string))) return message;
+
+	const blocks: WireBlock[] = [];
+	const siblings: WireBlock[] = [];
+	let movedBreakpoint: unknown;
+	for (const block of content) {
+		const names = block?.type === "tool_result" ? referencesAt.get(block.tool_use_id as string) : undefined;
+		if (!names) {
+			blocks.push(block);
+			continue;
+		}
+		const { content: original, cache_control, ...rest } = block;
+		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 });
+		} else if (Array.isArray(original)) {
+			siblings.push(...(original as WireBlock[]));
+		}
+	}
+	return { ...message, content: withBreakpointOnLast([...blocks, ...siblings], movedBreakpoint) };
 }
 
 /**

package/extensions/lib/git.ts

@@ -1,8 +1,24 @@
 /** Shared git helpers — pure functions only (safe to import across extensions). */
 
+import { execFile } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
+/**
+ * Whether the checkout at `cwd` has no uncommitted or untracked changes, or
+ * undefined when git could not say (not a repo, git missing). One short
+ * `git status --porcelain`, asynchronous so the tool_call hook it runs from
+ * does not stall the event loop; used for the classifier transcript's
+ * ground-truth line after a `git status` call (permissions/index.ts).
+ */
+export function gitStatusClean(cwd: string): Promise<boolean | undefined> {
+	return new Promise((resolvePromise) => {
+		execFile("git", ["status", "--porcelain"], { cwd, encoding: "utf8", timeout: 5_000, windowsHide: true }, (error, stdout) => {
+			resolvePromise(error ? undefined : stdout.trim().length === 0);
+		});
+	});
+}
+
 /**
  * The nearest checkout root at or above `startDir`: the directory holding a
  * `.git` entry (a directory for a main checkout, a file for a linked worktree

package/extensions/lib/keys.ts

@@ -0,0 +1,38 @@
+/**
+ * Keys that depend on the platform.
+ *
+ * pi rebinds a handful of its own shortcuts on Windows and WSL, where
+ * alt+enter and ctrl+shift+letter do not reach the process reliably: queue
+ * follow-up moves from alt+enter to ctrl+q, fork from ctrl+shift+f to ctrl+f,
+ * paste to alt+v, model select to alt+p (pi-coding-agent core/keybindings.js,
+ * `useWindowsKeybindings`, which pi does not export — the rule is copied
+ * here). So the ctrl+q that cycles permission modes everywhere else collides
+ * there: pi skips a `registerShortcut` on a built-in key with a startup
+ * warning, and mode cycling had no key at all on Windows (seen on the Vultr
+ * VM, 2026-09-19). No ctrl+letter is free on Windows once pi's app and editor
+ * bindings are counted, and pi itself reaches for alt there, so mode cycling
+ * is alt+m on Windows and WSL — docs/decisions/windows.md.
+ */
+
+/** pi's rule for its Windows key table: native Windows, or a WSL distro. */
+export function useWindowsKeybindings(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): boolean {
+	return platform === "win32" || (platform === "linux" && Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP));
+}
+
+/** The key that cycles permission modes: ctrl+q, or alt+m where pi owns ctrl+q. */
+export function modeCycleKey(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): "ctrl+q" | "alt+m" {
+	return useWindowsKeybindings(platform, env) ? "alt+m" : "ctrl+q";
+}
+
+/**
+ * The footer badge's pause icon. Claude Code's is U+23F8 (⏸); Windows Terminal
+ * draws that code point with its emoji font, two cells wide and coloured,
+ * while pi measures one cell, so the icon overlapped the mode name — and the
+ * text-presentation selector (U+FE0E) is ignored there (verified on the Vultr
+ * VM, 2026-09-19: rows A and B of the width test). U+2016 (‖) is a plain
+ * single-cell glyph in Windows Terminal, so it stands in on Windows and WSL,
+ * where the terminal is Windows Terminal either way.
+ */
+export function pauseGlyph(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): "⏸" | "‖" {
+	return useWindowsKeybindings(platform, env) ? "‖" : "⏸";
+}

package/extensions/lib/local-command.ts

@@ -0,0 +1,112 @@
+/**
+ * Local-command breadcrumbs — what Claude Code shows the model when the user
+ * runs a slash command that the harness handles locally (`/clear`, `/model`, a
+ * panel command). Captured from CC 2.1.278 (`captures/sonnet.json`, and this
+ * repo's own sessions after a `/clear`; findings §14, 2026-09-19): three
+ * synthetic user messages that reach the model as consecutive bare text blocks
+ * of the next user message, after the reminder stack and before the user's own
+ * text —
+ *
+ *   <local-command-caveat>Caveat: …</local-command-caveat>\n
+ *   <command-name>/model</command-name>\n
+ *               <command-message>model</command-message>\n
+ *               <command-args></command-args>\n
+ *   <local-command-stdout>Set model to `Sonnet 5` …</local-command-stdout>\n
+ *
+ * (twelve-space indent on the second and third command lines, verbatim from
+ * CC's `formatCommandInputTags`; stdout XML-escaped like CC's `escapeXml`, `&
+ * < >` only). `/clear` carries an EMPTY stdout block and opens the new
+ * conversation. The caveat tells the model not to act on any of it.
+ *
+ * One Code emits these through the reminder queue's `user-prepend` placement
+ * (`lib/reminders.ts`): pi dispatches an extension command BEFORE its `input`
+ * event fires and handles its own built-ins (`/model`, `/name`, …) before
+ * either, so there is no single interception point — every One Code local
+ * command is registered through `registerLocalCommand`, which announces before
+ * the handler runs, and `/model` is announced from the `model_select` event by
+ * the extension that persists the choice. pi built-ins we cannot see
+ * (`/compact`, `/settings`, …) stay silent. The blocks are pinned in process
+ * memory, not written to the session file as CC does — a `--resume` drops them.
+ */
+
+import { REMINDER_CHANNEL, type ReminderPayload } from "./reminders.ts";
+
+/** The slice of pi's ExtensionAPI the announcer needs (its event bus). */
+export interface ReminderEmitter {
+	events: { emit(channel: string, data: unknown): unknown };
+}
+
+/**
+ * How each breadcrumb block begins — what a first message that is NOT the
+ * user's topic starts with (the session-title extension skips these, as CC's
+ * REPL does before naming a session).
+ */
+export const LOCAL_COMMAND_TAG_PREFIXES = ["<local-command-caveat>", "<command-name>", "<command-message>", "<local-command-stdout>"] as const;
+
+export const LOCAL_COMMAND_CAVEAT =
+	"<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>\n";
+
+/** CC's `escapeXml` (utils/xml.ts): `& < >` only. */
+export function escapeXml(s: string): string {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export interface LocalCommand {
+	/** Command name without the slash (`clear`, `model`). */
+	name: string;
+	/** The argument text the user typed after the name; "" when none. */
+	args?: string;
+	/** The command's printed result; "" (the default) is what `/clear` shows. */
+	stdout?: string;
+}
+
+/** CC's `formatCommandInputTags` — the command breadcrumb, indentation included. */
+export function commandInputBlock(name: string, args = ""): string {
+	return `<command-name>/${name}</command-name>\n            <command-message>${name}</command-message>\n            <command-args>${args}</command-args>\n`;
+}
+
+/** CC's `<local-command-stdout>` message; the content is XML-escaped. */
+export function commandStdoutBlock(stdout = ""): string {
+	return `<local-command-stdout>${escapeXml(stdout)}</local-command-stdout>\n`;
+}
+
+/** The three bare text blocks a local command leaves for the model, in CC's order. */
+export function localCommandBlocks(command: LocalCommand): string[] {
+	return [LOCAL_COMMAND_CAVEAT, commandInputBlock(command.name, (command.args ?? "").trim()), commandStdoutBlock(command.stdout ?? "")];
+}
+
+/**
+ * Tell the model a local command ran. Call it from the command's handler
+ * (before a `/clear` resets the session — the queue survives `newSession()`,
+ * so the breadcrumb opens the new conversation exactly as in CC).
+ */
+export function announceLocalCommand(pi: ReminderEmitter, command: LocalCommand): void {
+	localCommandBlocks(command).forEach((text, index) => {
+		// The caveat heads a RUN of commands: a second command before the next
+		// prompt joins the first caveat instead of repeating it.
+		const payload: ReminderPayload = { text, placement: "user-prepend", raw: true, ...(index === 0 ? { once: true } : {}) };
+		pi.events.emit(REMINDER_CHANNEL, payload);
+	});
+}
+
+type CommandOptions = { handler: (args: string, ctx: any) => Promise<void> | void } & Record<string, unknown>;
+
+/**
+ * `pi.registerCommand` for a One Code local command: the breadcrumb is
+ * announced before the handler runs, so no command can forget it. `/clear`
+ * is the one exception — it announces from the NEW session's `session_start`
+ * (see clear/index.ts) and registers plainly.
+ */
+export function registerLocalCommand<O extends CommandOptions>(
+	pi: ReminderEmitter & { registerCommand(name: string, options: O): void },
+	name: string,
+	options: O,
+): void {
+	pi.registerCommand(name, {
+		...options,
+		handler: (args: string, ctx: unknown) => {
+			announceLocalCommand(pi, { name, args });
+			return options.handler(args, ctx);
+		},
+	});
+}