one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/key-input.ts

@@ -0,0 +1,455 @@
+/**
+ * Terminal key decoding for One Code's panels, dialogs and input listeners.
+ *
+ * A key reaches an extension as raw bytes, and one key has several encodings.
+ * pi-tui asks the terminal for the kitty keyboard protocol (flags 7:
+ * disambiguate, event types, alternate keys), and when the terminal does not
+ * answer it turns on xterm's modifyOtherKeys. So Esc is `\x1b` in a legacy
+ * terminal and `\x1b[27u` in kitty, Ghostty, WezTerm or VS Code; ctrl+c is
+ * `\x03`, `\x1b[99;5u`, or `\x1b[27;5;99~` under tmux with `extended-keys on`;
+ * and with event types on, every press is followed by a release such as
+ * `\x1b[1;1:3B`. A decoder that compares legacy bytes misses all of those.
+ *
+ * `parseKey` is pi-tui's own parser (`dist/keys.js`, MIT; unchanged from
+ * 0.87.1 to 1.1.0, then 1.2.0's logical shifted-symbol reading), ported
+ * verbatim so every panel names a key exactly as pi-tui and pi's
+ * keybindings do. It stays here because `lib/` modules
+ * import nothing from pi, and the bare `@earendil-works/pi-tui` specifier
+ * resolves to a different pi-tui in tests than at runtime.
+ * `key-input.test.ts` compares this port with the installed pi-tui over
+ * every encoding, so a pi bump that changes the parser fails the suite.
+ *
+ * Decoders switch on `keyId(data)` (pi-tui's key ids: `escape`, `ctrl+c`,
+ * `shift+tab`, `up`, `pageDown`, `x`) and read typed text with `keyText`.
+ * An input listener, which pi-tui calls before it filters releases, checks
+ * `isKeyRelease` first.
+ */
+
+const MODIFIERS = { shift: 1, alt: 2, ctrl: 4, super: 8 } as const;
+/** Caps lock and num lock, which the kitty protocol reports as modifier bits. */
+const LOCK_MASK = 64 + 128;
+
+const CODEPOINTS = { escape: 27, tab: 9, enter: 13, space: 32, backspace: 127, kpEnter: 57414 } as const;
+const ARROW_CODEPOINTS = { up: -1, down: -2, right: -3, left: -4 } as const;
+const FUNCTIONAL_CODEPOINTS = { delete: -10, insert: -11, pageUp: -12, pageDown: -13, home: -14, end: -15 } as const;
+
+/** Kitty keypad codes and the keys they stand for. */
+const KITTY_FUNCTIONAL_KEY_EQUIVALENTS = new Map<number, number>([
+	[57399, 48],
+	[57400, 49],
+	[57401, 50],
+	[57402, 51],
+	[57403, 52],
+	[57404, 53],
+	[57405, 54],
+	[57406, 55],
+	[57407, 56],
+	[57408, 57],
+	[57409, 46],
+	[57410, 47],
+	[57411, 42],
+	[57412, 45],
+	[57413, 43],
+	[57415, 61],
+	[57416, 44],
+	[57417, ARROW_CODEPOINTS.left],
+	[57418, ARROW_CODEPOINTS.right],
+	[57419, ARROW_CODEPOINTS.up],
+	[57420, ARROW_CODEPOINTS.down],
+	[57421, FUNCTIONAL_CODEPOINTS.pageUp],
+	[57422, FUNCTIONAL_CODEPOINTS.pageDown],
+	[57423, FUNCTIONAL_CODEPOINTS.home],
+	[57424, FUNCTIONAL_CODEPOINTS.end],
+	[57425, FUNCTIONAL_CODEPOINTS.insert],
+	[57426, FUNCTIONAL_CODEPOINTS.delete],
+]);
+
+const SYMBOL_KEYS = new Set([
+	"`", "-", "=", "[", "]", "\\", ";", "'", ",", ".", "/", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "_",
+	"+", "|", "~", "{", "}", ":", "<", ">", "?",
+]);
+
+const LEGACY_SEQUENCE_KEY_IDS: Record<string, string> = {
+	"\x1bOA": "up",
+	"\x1bOB": "down",
+	"\x1bOC": "right",
+	"\x1bOD": "left",
+	"\x1bOH": "home",
+	"\x1bOF": "end",
+	"\x1b[E": "clear",
+	"\x1bOE": "clear",
+	"\x1bOe": "ctrl+clear",
+	"\x1b[e": "shift+clear",
+	"\x1b[2~": "insert",
+	"\x1b[2$": "shift+insert",
+	"\x1b[2^": "ctrl+insert",
+	"\x1b[3$": "shift+delete",
+	"\x1b[3^": "ctrl+delete",
+	"\x1b[[5~": "pageUp",
+	"\x1b[[6~": "pageDown",
+	"\x1b[a": "shift+up",
+	"\x1b[b": "shift+down",
+	"\x1b[c": "shift+right",
+	"\x1b[d": "shift+left",
+	"\x1bOa": "ctrl+up",
+	"\x1bOb": "ctrl+down",
+	"\x1bOc": "ctrl+right",
+	"\x1bOd": "ctrl+left",
+	"\x1b[5$": "shift+pageUp",
+	"\x1b[6$": "shift+pageDown",
+	"\x1b[7$": "shift+home",
+	"\x1b[8$": "shift+end",
+	"\x1b[5^": "ctrl+pageUp",
+	"\x1b[6^": "ctrl+pageDown",
+	"\x1b[7^": "ctrl+home",
+	"\x1b[8^": "ctrl+end",
+	"\x1bOP": "f1",
+	"\x1bOQ": "f2",
+	"\x1bOR": "f3",
+	"\x1bOS": "f4",
+	"\x1b[11~": "f1",
+	"\x1b[12~": "f2",
+	"\x1b[13~": "f3",
+	"\x1b[14~": "f4",
+	"\x1b[[A": "f1",
+	"\x1b[[B": "f2",
+	"\x1b[[C": "f3",
+	"\x1b[[D": "f4",
+	"\x1b[[E": "f5",
+	"\x1b[15~": "f5",
+	"\x1b[17~": "f6",
+	"\x1b[18~": "f7",
+	"\x1b[19~": "f8",
+	"\x1b[20~": "f9",
+	"\x1b[21~": "f10",
+	"\x1b[23~": "f11",
+	"\x1b[24~": "f12",
+	"\x1bb": "alt+left",
+	"\x1bf": "alt+right",
+	"\x1bp": "alt+up",
+	"\x1bn": "alt+down",
+};
+
+export type KeyEventType = "press" | "repeat" | "release";
+
+interface ParsedSequence {
+	codepoint: number;
+	shiftedKey?: number;
+	baseLayoutKey?: number;
+	modifier: number;
+	eventType: KeyEventType;
+}
+
+function parseEventType(field: string | undefined): KeyEventType {
+	if (!field) return "press";
+	const eventType = Number.parseInt(field, 10);
+	if (eventType === 2) return "repeat";
+	if (eventType === 3) return "release";
+	return "press";
+}
+
+const KITTY_CSI_U = /^\x1b\[(\d+)(?::(\d*))?(?::(\d+))?(?:;(\d+))?(?::(\d+))?u$/;
+
+function parseKittySequence(data: string): ParsedSequence | undefined {
+	const csiU = data.match(KITTY_CSI_U);
+	if (csiU) {
+		return {
+			codepoint: Number.parseInt(csiU[1], 10),
+			shiftedKey: csiU[2] && csiU[2].length > 0 ? Number.parseInt(csiU[2], 10) : undefined,
+			baseLayoutKey: csiU[3] ? Number.parseInt(csiU[3], 10) : undefined,
+			modifier: (csiU[4] ? Number.parseInt(csiU[4], 10) : 1) - 1,
+			eventType: parseEventType(csiU[5]),
+		};
+	}
+	const arrow = data.match(/^\x1b\[1;(\d+)(?::(\d+))?([ABCD])$/);
+	if (arrow) {
+		const codes: Record<string, number> = { A: -1, B: -2, C: -3, D: -4 };
+		return { codepoint: codes[arrow[3]], modifier: Number.parseInt(arrow[1], 10) - 1, eventType: parseEventType(arrow[2]) };
+	}
+	const func = data.match(/^\x1b\[(\d+)(?:;(\d+))?(?::(\d+))?~$/);
+	if (func) {
+		const funcCodes: Record<number, number> = {
+			2: FUNCTIONAL_CODEPOINTS.insert,
+			3: FUNCTIONAL_CODEPOINTS.delete,
+			5: FUNCTIONAL_CODEPOINTS.pageUp,
+			6: FUNCTIONAL_CODEPOINTS.pageDown,
+			7: FUNCTIONAL_CODEPOINTS.home,
+			8: FUNCTIONAL_CODEPOINTS.end,
+		};
+		const codepoint = funcCodes[Number.parseInt(func[1], 10)];
+		if (codepoint !== undefined) {
+			return { codepoint, modifier: (func[2] ? Number.parseInt(func[2], 10) : 1) - 1, eventType: parseEventType(func[3]) };
+		}
+	}
+	const homeEnd = data.match(/^\x1b\[1;(\d+)(?::(\d+))?([HF])$/);
+	if (homeEnd) {
+		return {
+			codepoint: homeEnd[3] === "H" ? FUNCTIONAL_CODEPOINTS.home : FUNCTIONAL_CODEPOINTS.end,
+			modifier: Number.parseInt(homeEnd[1], 10) - 1,
+			eventType: parseEventType(homeEnd[2]),
+		};
+	}
+	return undefined;
+}
+
+function parseModifyOtherKeysSequence(data: string): { codepoint: number; modifier: number } | undefined {
+	const match = data.match(/^\x1b\[27;(\d+);(\d+)~$/);
+	if (!match) return undefined;
+	return { codepoint: Number.parseInt(match[2], 10), modifier: Number.parseInt(match[1], 10) - 1 };
+}
+
+function normalizeKittyFunctionalCodepoint(codepoint: number): number {
+	return KITTY_FUNCTIONAL_KEY_EQUIVALENTS.get(codepoint) ?? codepoint;
+}
+
+function normalizeShiftedLetterIdentityCodepoint(codepoint: number, modifier: number): number {
+	const effective = modifier & ~LOCK_MASK;
+	if ((effective & MODIFIERS.shift) !== 0 && codepoint >= 65 && codepoint <= 90) return codepoint + 32;
+	return codepoint;
+}
+
+function formatKeyNameWithModifiers(keyName: string, modifier: number): string | undefined {
+	const effective = modifier & ~LOCK_MASK;
+	const supported = MODIFIERS.shift | MODIFIERS.ctrl | MODIFIERS.alt | MODIFIERS.super;
+	if ((effective & ~supported) !== 0) return undefined;
+	const mods: string[] = [];
+	if (effective & MODIFIERS.shift) mods.push("shift");
+	if (effective & MODIFIERS.ctrl) mods.push("ctrl");
+	if (effective & MODIFIERS.alt) mods.push("alt");
+	if (effective & MODIFIERS.super) mods.push("super");
+	return mods.length > 0 ? `${mods.join("+")}+${keyName}` : keyName;
+}
+
+const NAMED_CODEPOINTS = new Map<number, string>([
+	[CODEPOINTS.escape, "escape"],
+	[CODEPOINTS.tab, "tab"],
+	[CODEPOINTS.enter, "enter"],
+	[CODEPOINTS.kpEnter, "enter"],
+	[CODEPOINTS.space, "space"],
+	[CODEPOINTS.backspace, "backspace"],
+	[FUNCTIONAL_CODEPOINTS.delete, "delete"],
+	[FUNCTIONAL_CODEPOINTS.insert, "insert"],
+	[FUNCTIONAL_CODEPOINTS.home, "home"],
+	[FUNCTIONAL_CODEPOINTS.end, "end"],
+	[FUNCTIONAL_CODEPOINTS.pageUp, "pageUp"],
+	[FUNCTIONAL_CODEPOINTS.pageDown, "pageDown"],
+	[ARROW_CODEPOINTS.up, "up"],
+	[ARROW_CODEPOINTS.down, "down"],
+	[ARROW_CODEPOINTS.left, "left"],
+	[ARROW_CODEPOINTS.right, "right"],
+]);
+
+/** Symbols a modifyOtherKeys terminal reports as Shift plus the physical key (pi-tui 1.2.0). */
+const SHIFTED_SYMBOL_KEYS = new Set("~!@#$%^&*()_+|{}:<>?");
+
+/**
+ * pi-tui 1.2.0's logical reading of a shifted symbol: kitty reports "+" as
+ * Shift plus the physical "=" key (the produced symbol in the shifted-key
+ * field), and bindings name the produced symbol, so the implicit Shift is
+ * consumed while Ctrl, Alt and Super stay.
+ */
+function logicalShiftedSymbol(codepoint: number | undefined, modifier: number, allowed: ReadonlySet<string>): { codepoint: number; modifier: number } | undefined {
+	if (codepoint === undefined || (modifier & MODIFIERS.shift) === 0) return undefined;
+	const normalized = normalizeKittyFunctionalCodepoint(codepoint);
+	if (!allowed.has(String.fromCharCode(normalized))) return undefined;
+	return { codepoint: normalized, modifier: modifier & ~MODIFIERS.shift };
+}
+
+function formatParsedKey(codepoint: number, modifier: number, baseLayoutKey?: number): string | undefined {
+	const identity = normalizeShiftedLetterIdentityCodepoint(normalizeKittyFunctionalCodepoint(codepoint), modifier);
+	// The codepoint is authoritative for a Latin letter, digit or known symbol
+	// (remapped layouts); otherwise the base-layout key names it.
+	const isLatinLetter = identity >= 97 && identity <= 122;
+	const isDigit = identity >= 48 && identity <= 57;
+	const isKnownSymbol = SYMBOL_KEYS.has(String.fromCharCode(identity));
+	const effective = isLatinLetter || isDigit || isKnownSymbol ? identity : (baseLayoutKey ?? identity);
+	let keyName = NAMED_CODEPOINTS.get(effective);
+	if (!keyName) {
+		if ((effective >= 48 && effective <= 57) || (effective >= 97 && effective <= 122)) keyName = String.fromCharCode(effective);
+		else if (SYMBOL_KEYS.has(String.fromCharCode(effective))) keyName = String.fromCharCode(effective);
+	}
+	if (!keyName) return undefined;
+	return formatKeyNameWithModifiers(keyName, modifier);
+}
+
+export interface ParseKeyOptions {
+	/** pi-tui's kitty-protocol state: `\n` and `\x1b\r` then mean shift+enter. Default false. */
+	kittyActive?: boolean;
+	/** Windows Terminal outside SSH, where a raw `\x08` is ctrl+backspace. Default read from the environment. */
+	windowsTerminal?: boolean;
+}
+
+function isWindowsTerminalSession(env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(env.WT_SESSION) && !env.SSH_CONNECTION && !env.SSH_CLIENT && !env.SSH_TTY;
+}
+
+/** pi-tui's `parseKey` (1.2.0): the key id of one input chunk, or undefined. Releases parse like presses. */
+export function parseKey(data: string, options: ParseKeyOptions = {}): string | undefined {
+	const kitty = options.kittyActive ?? false;
+	const kittySeq = parseKittySequence(data);
+	if (kittySeq) {
+		const symbol = logicalShiftedSymbol(kittySeq.shiftedKey, kittySeq.modifier, SYMBOL_KEYS);
+		return formatParsedKey(symbol?.codepoint ?? kittySeq.codepoint, symbol?.modifier ?? kittySeq.modifier, kittySeq.baseLayoutKey);
+	}
+	const mok = parseModifyOtherKeysSequence(data);
+	if (mok) {
+		const symbol = logicalShiftedSymbol(mok.codepoint, mok.modifier, SHIFTED_SYMBOL_KEYS);
+		return formatParsedKey(symbol?.codepoint ?? mok.codepoint, symbol?.modifier ?? mok.modifier);
+	}
+	if (kitty && (data === "\x1b\r" || data === "\n")) return "shift+enter";
+	const legacy = LEGACY_SEQUENCE_KEY_IDS[data];
+	if (legacy) return legacy;
+	switch (data) {
+		case "\x1b":
+			return "escape";
+		case "\x1c":
+			return "ctrl+\\";
+		case "\x1d":
+			return "ctrl+]";
+		case "\x1f":
+			return "ctrl+-";
+		case "\x1b\x1b":
+			return "ctrl+alt+[";
+		case "\x1b\x1c":
+			return "ctrl+alt+\\";
+		case "\x1b\x1d":
+			return "ctrl+alt+]";
+		case "\x1b\x1f":
+			return "ctrl+alt+-";
+		case "\t":
+			return "tab";
+		case "\r":
+		case "\x1bOM":
+			return "enter";
+		case "\x00":
+			return "ctrl+space";
+		case " ":
+			return "space";
+		case "\x7f":
+			return "backspace";
+		case "\x08":
+			return (options.windowsTerminal ?? isWindowsTerminalSession()) ? "ctrl+backspace" : "backspace";
+		case "\x1b[Z":
+			return "shift+tab";
+		case "\x1b\x7f":
+		case "\x1b\b":
+			return "alt+backspace";
+	}
+	if (!kitty) {
+		if (data === "\n") return "enter";
+		if (data === "\x1b\r") return "alt+enter";
+		if (data === "\x1b ") return "alt+space";
+		if (data === "\x1bB") return "alt+left";
+		if (data === "\x1bF") return "alt+right";
+		if (data.length === 2 && data[0] === "\x1b") {
+			const code = data.charCodeAt(1);
+			if (code >= 1 && code <= 26) return `ctrl+alt+${String.fromCharCode(code + 96)}`;
+			const key = String.fromCharCode(code);
+			if ((code >= 97 && code <= 122) || (code >= 48 && code <= 57) || SYMBOL_KEYS.has(key)) return `alt+${key}`;
+		}
+	}
+	switch (data) {
+		case "\x1b[A":
+			return "up";
+		case "\x1b[B":
+			return "down";
+		case "\x1b[C":
+			return "right";
+		case "\x1b[D":
+			return "left";
+		case "\x1b[H":
+		case "\x1bOH":
+			return "home";
+		case "\x1b[F":
+		case "\x1bOF":
+			return "end";
+		case "\x1b[3~":
+			return "delete";
+		case "\x1b[5~":
+			return "pageUp";
+		case "\x1b[6~":
+			return "pageDown";
+	}
+	if (data.length === 1) {
+		const code = data.charCodeAt(0);
+		if (code >= 1 && code <= 26) return `ctrl+${String.fromCharCode(code + 96)}`;
+		if (code >= 32 && code <= 126) return data;
+	}
+	return undefined;
+}
+
+/**
+ * Legacy Home and End forms that pi-tui's `matchesKey` accepts but its
+ * `parseKey` does not name (rxvt and the Linux console send them).
+ */
+const EXTRA_KEY_IDS: Record<string, string> = { "\x1b[1~": "home", "\x1b[4~": "end" };
+
+/**
+ * The key id for a panel decoder: pi-tui's `parseKey`, plus the legacy Home
+ * and End forms. A release or repeat names the same key as its press; pi-tui
+ * drops releases before a focused component sees them.
+ */
+export function keyId(data: string, options?: ParseKeyOptions): string | undefined {
+	return parseKey(data, options) ?? EXTRA_KEY_IDS[data];
+}
+
+/** pi-tui's `isKeyRelease`: the kitty protocol's release event (flag 2). Pasted text never counts. */
+export function isKeyRelease(data: string): boolean {
+	if (data.includes("\x1b[200~")) return false;
+	return /:3[u~ABCDHF]/.test(data);
+}
+
+/** pi-tui's `isKeyRepeat`: the kitty protocol's auto-repeat event (flag 2). */
+export function isKeyRepeat(data: string): boolean {
+	if (data.includes("\x1b[200~")) return false;
+	return /:2[u~ABCDHF]/.test(data);
+}
+
+const KITTY_PRINTABLE_ALLOWED_MODIFIERS = MODIFIERS.shift | LOCK_MASK;
+
+/** pi-tui's `decodePrintableKey`: the character a kitty CSI u or modifyOtherKeys sequence types, if any. */
+export function decodePrintableKey(data: string): string | undefined {
+	const csiU = data.match(KITTY_CSI_U);
+	if (csiU) {
+		const codepoint = Number.parseInt(csiU[1] ?? "", 10);
+		if (!Number.isFinite(codepoint)) return undefined;
+		const shiftedKey = csiU[2] && csiU[2].length > 0 ? Number.parseInt(csiU[2], 10) : undefined;
+		const modValue = csiU[4] ? Number.parseInt(csiU[4], 10) : 1;
+		const modifier = Number.isFinite(modValue) ? modValue - 1 : 0;
+		if ((modifier & ~KITTY_PRINTABLE_ALLOWED_MODIFIERS) !== 0) return undefined;
+		if (modifier & (MODIFIERS.alt | MODIFIERS.ctrl)) return undefined;
+		let effective = codepoint;
+		if (modifier & MODIFIERS.shift && typeof shiftedKey === "number") effective = shiftedKey;
+		effective = normalizeKittyFunctionalCodepoint(effective);
+		if (!Number.isFinite(effective) || effective < 32) return undefined;
+		try {
+			return String.fromCodePoint(effective);
+		} catch {
+			return undefined;
+		}
+	}
+	const mok = parseModifyOtherKeysSequence(data);
+	if (!mok) return undefined;
+	if (((mok.modifier & ~LOCK_MASK) & ~MODIFIERS.shift) !== 0) return undefined;
+	if (!Number.isFinite(mok.codepoint) || mok.codepoint < 32) return undefined;
+	try {
+		return String.fromCodePoint(mok.codepoint);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The text a chunk types, for a search box, a draft or a letter shortcut:
+ * plain input (a key or a paste) with control characters removed, or the
+ * character an encoded printable key stands for. A control sequence types
+ * nothing, so its tail never leaks into a draft.
+ */
+export function keyText(data: string): string | undefined {
+	if (data.startsWith("\x1b")) {
+		if (isKeyRelease(data)) return undefined;
+		return decodePrintableKey(data);
+	}
+	const text = [...data].filter((ch) => ch >= " " && ch !== "\x7f").join("");
+	return text.length > 0 ? text : undefined;
+}

package/extensions/lib/keys.ts

@@ -11,7 +11,7 @@
  * 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.
+ * is alt+m on Windows and WSL — working-docs/decisions/windows.md.
  */
 
 /** pi's rule for its Windows key table: native Windows, or a WSL distro. */
@@ -24,6 +24,19 @@ export function modeCycleKey(platform: string = process.platform, env: NodeJS.Pr
 	return useWindowsKeybindings(platform, env) ? "alt+m" : "ctrl+q";
 }
 
+/**
+ * The key that shows or hides the pinned task list. Claude Code uses ctrl+t,
+ * which pi reserves for its thinking-block toggle (an extension shortcut on a
+ * reserved key is skipped), so One Code uses alt+t, free in pi's key tables
+ * on every platform. macOS terminals send option+t as the typed character †
+ * unless "Use Option as Meta" is on, so alt+t never arrives there; macOS gets
+ * ctrl+\ instead, a control byte every terminal passes through, free in pi's
+ * tables (ctrl+] and ctrl+- are taken, and no ctrl+letter is left).
+ */
+export function taskToggleKey(platform: string = process.platform): "alt+t" | "ctrl+\\" {
+	return platform === "darwin" ? "ctrl+\\" : "alt+t";
+}
+
 /**
  * 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,

package/extensions/lib/local-command.ts

@@ -7,7 +7,7 @@
  * of the next user message, after the reminder stack and before the user's own
  * text —
  *
- *   <local-command-caveat>Caveat: …</local-command-caveat>\n
+ *   <local-command-caveat>The command below was run directly in …</local-command-caveat>\n
  *   <command-name>/model</command-name>\n
  *               <command-message>model</command-message>\n
  *               <command-args></command-args>\n
@@ -16,19 +16,23 @@
  * (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.
+ * conversation. The caveat tells the model the command was the user's, not a
+ * request to it, kept as context.
  *
  * 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
+ * the handler runs (or, with `reportsResult`, after it, carrying the handler's
+ * returned text as the stdout, as CC's `onDone(result)` does), 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 { announceArgumentHint, type HintEmitter, withoutExactMatch } from "./argument-hints.ts";
 import { REMINDER_CHANNEL, type ReminderPayload } from "./reminders.ts";
 
 /** The slice of pi's ExtensionAPI the announcer needs (its event bus). */
@@ -43,8 +47,9 @@ export interface ReminderEmitter {
  */
 export const LOCAL_COMMAND_TAG_PREFIXES = ["<local-command-caveat>", "<command-name>", "<command-message>", "<local-command-stdout>"] as const;
 
+/** Claude Code 2.1.288's caveat, naming the harness the command ran in. */
 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";
+	"<local-command-caveat>The command below was run directly in One Code, not sent to you as a request, and its output goes straight to the user. It's recorded here as context for later messages.</local-command-caveat>\n";
 
 /** CC's `escapeXml` (utils/xml.ts): `& < >` only. */
 export function escapeXml(s: string): string {
@@ -91,22 +96,51 @@ export function announceLocalCommand(pi: ReminderEmitter, command: LocalCommand)
 
 type CommandOptions = { handler: (args: string, ctx: any) => Promise<void> | void } & Record<string, unknown>;
 
+/**
+ * What a local command passes: pi's options, plus `reportsResult` when its
+ * handler returns the stdout (a returned string is never silently dropped).
+ */
+type LocalCommandOptions<O extends CommandOptions> = Omit<O, "handler"> & { argumentHint?: string } & (
+		| { reportsResult: true; handler: (args: string, ctx: Parameters<O["handler"]>[1]) => Promise<string | void> | string | void }
+		| { reportsResult?: false; handler: (args: string, ctx: Parameters<O["handler"]>[1]) => Promise<void> | void }
+	);
+
 /**
  * `pi.registerCommand` for a One Code local command: the breadcrumb is
- * announced before the handler runs, so no command can forget it. `/clear`
+ * announced before the handler runs, so no command can forget it. With
+ * `reportsResult`, it is announced once the handler settles instead, its
+ * stdout the string the handler returned (CC's `onDone(result)`; "" for none
+ * or a throw). Only a command that never starts a turn of its own may opt in:
+ * a breadcrumb queued after `sendUserMessage` would miss that message. `/clear`
  * is the one exception — it announces from the NEW session's `session_start`
- * (see clear/index.ts) and registers plainly.
+ * (see clear/index.ts) and registers plainly. `argumentHint` is the prompt's
+ * dim placeholder for the command's argument (lib/argument-hints.ts). Its
+ * completions leave out an exact match, so a fully typed argument runs on the
+ * first Enter (`withoutExactMatch`).
  */
 export function registerLocalCommand<O extends CommandOptions>(
-	pi: ReminderEmitter & { registerCommand(name: string, options: O): void },
+	pi: ReminderEmitter & HintEmitter & { registerCommand(name: string, options: O): void },
 	name: string,
-	options: O,
+	options: LocalCommandOptions<O>,
 ): void {
+	const { argumentHint, reportsResult, ...rest } = options;
+	if (argumentHint) announceArgumentHint(pi, name, argumentHint);
+	const complete = (rest as { getArgumentCompletions?: Parameters<typeof withoutExactMatch>[0] }).getArgumentCompletions;
 	pi.registerCommand(name, {
-		...options,
-		handler: (args: string, ctx: unknown) => {
-			announceLocalCommand(pi, { name, args });
-			return options.handler(args, ctx);
+		...(rest as unknown as O),
+		...(complete ? { getArgumentCompletions: withoutExactMatch(complete) } : {}),
+		handler: async (args: string, ctx: Parameters<O["handler"]>[1]) => {
+			if (!reportsResult) {
+				announceLocalCommand(pi, { name, args });
+				await options.handler(args, ctx);
+				return;
+			}
+			let stdout = "";
+			try {
+				stdout = (await options.handler(args, ctx)) ?? "";
+			} finally {
+				announceLocalCommand(pi, { name, args, stdout });
+			}
 		},
 	});
 }

package/extensions/lib/mcp-overrides.ts

@@ -4,7 +4,7 @@
  * The /mcp panel's Disable/Enable action persists across sessions here rather
  * than by mutating the user's `~/.claude.json` or a plugin's `.mcp.json`: those
  * are Claude Code's / a plugin's config, which One Code only ever reads (the
- * "own state, borrowed config" rule — docs/decisions/memory-state.md). A
+ * "own state, borrowed config" rule — working-docs/decisions/memory-state.md). A
  * disabled server is still discovered and listed; the mcp extension just skips
  * connecting it, and the panel offers Enable to bring it back.
  *

package/extensions/lib/mcp-share.ts

@@ -23,3 +23,49 @@ export interface McpToolsPayload {
 	 */
 	settled?: boolean;
 }
+
+/** How long a child spawned while MCP is still connecting waits for the settled set. */
+export const MCP_SETTLE_CAP_MS = 10_000;
+
+/** The events slice `watchMcpTools` needs. */
+export interface McpToolsEvents {
+	on(channel: string, handler: (data: unknown) => void): unknown;
+}
+
+/**
+ * Track the parent's live MCP tool definitions for in-process children (the
+ * subagent runner and the workflow runner). Subscribe at extension load; the
+ * getter resolves to the current set. The parent's MCP connect runs in the
+ * background, so a child spawned in the first seconds of a session waits for
+ * the settled publish, capped so a hung server cannot stall spawns, instead of
+ * baking in a still-connecting (possibly empty) snapshot. Empty when no MCP
+ * servers are configured.
+ */
+export function watchMcpTools(events: McpToolsEvents, settleCapMs = MCP_SETTLE_CAP_MS): () => Promise<ToolDefinition[]> {
+	let tools: ToolDefinition[] = [];
+	let settled = false;
+	let resolveSettled: (() => void) | undefined;
+	const settledPromise = new Promise<void>((resolve) => {
+		resolveSettled = resolve;
+	});
+	events.on(MCP_TOOLS_CHANNEL, (data) => {
+		const payload = data as McpToolsPayload | undefined;
+		tools = payload?.tools ?? [];
+		if (payload?.settled) {
+			settled = true;
+			resolveSettled?.();
+		}
+	});
+	return async () => {
+		if (!settled) {
+			await Promise.race([
+				settledPromise,
+				new Promise<void>((resolve) => {
+					const timer = setTimeout(resolve, settleCapMs);
+					timer.unref?.();
+				}),
+			]);
+		}
+		return tools;
+	};
+}