gentle-pi 2.4.0 → 2.6.0

package/tests/agents-widget.test.ts

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { TASK_STATUS, type TaskRecord } from "../lib/agents-protocol.ts";
+import { formatElapsed, renderAgentsCard, widgetExpiryMs, widgetRows, widgetTasks } from "../lib/agents-widget.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// Gentle Agents widget: the card above the editor that shows what the
+// subagents are doing, drawn from task records only (never from threads).
+// Layout: glyph, agent, task summary (wrapped), then model · tokens · cost · time.
+
+const plainTheme = { fg: (_color: string, text: string) => text };
+
+function task(overrides: Partial<TaskRecord>): TaskRecord {
+	return { id: "t", agent: "sdd-explore", mode: "task", prompt: "map footer data sources", label: "map footer data sources", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.RUNNING, createdAt: 1000, startedAt: 1000, endedAt: null, model: "anthropic/claude-sonnet-5", thinking: undefined, sessionPath: null, error: null, result: null, lastStep: "grep", lastActivityAt: 1000, turns: 0, toolCalls: 0, tokens: 34_000, cost: 0.27, ...overrides };
+}
+
+test("formatElapsed renders seconds, minutes, and hours compactly", () => {
+	assert.equal(formatElapsed(4_000), "4s");
+	assert.equal(formatElapsed(65_000), "1m05s");
+	assert.equal(formatElapsed(3_720_000), "1h02m");
+	assert.equal(formatElapsed(-5), "0s");
+});
+
+test("widgetTasks keeps active tasks in start order and only recently finished ones", () => {
+	const tasks = [
+		task({ id: "old-done", status: TASK_STATUS.COMPLETED, endedAt: 10_000 }),
+		task({ id: "new-done", status: TASK_STATUS.FAILED, endedAt: 95_000 }),
+		task({ id: "queued", status: TASK_STATUS.QUEUED, createdAt: 3000, startedAt: null }),
+		task({ id: "running", createdAt: 2000, startedAt: 2000 }),
+	];
+	assert.deepEqual(widgetTasks(tasks, 100_000).map((entry) => entry.id), ["new-done", "running", "queued"]);
+	assert.deepEqual(widgetTasks([], 100_000), []);
+});
+
+test("widgetExpiryMs says how long until the next finished row leaves the card", () => {
+	const running = task({ id: "running", createdAt: 2000, startedAt: 2000 });
+	const done = task({ id: "done", status: TASK_STATUS.COMPLETED, endedAt: 95_000 });
+	const later = task({ id: "later", status: TASK_STATUS.COMPLETED, endedAt: 99_000 });
+	assert.equal(widgetExpiryMs([running, done, later], 100_000), 55_000, "the oldest shown row expires first");
+	assert.equal(widgetExpiryMs([done], 155_000), undefined, "a row past its minute is already gone");
+	assert.equal(widgetExpiryMs([running], 100_000), undefined, "active rows never expire");
+	assert.equal(widgetExpiryMs([], 100_000), undefined);
+});
+
+test("renderAgentsCard draws columns for agent, task, and model · tokens · cost · time, with the batch time in the rule", () => {
+	const tasks = [
+		task({ id: "a", status: TASK_STATUS.COMPLETED, startedAt: 1000, endedAt: 26_000 }),
+		task({ id: "b", agent: "sdd-apply", label: "write gentle-shell footer", startedAt: 44_000, tokens: 12_000, cost: 0.09 }),
+	];
+	const lines = renderAgentsCard(tasks, plainTheme, 84, 85_000, { collapsed: false });
+	for (const line of lines) assert.equal(visibleWidth(line), 84, `"${stripAnsi(line)}" is not 84 wide`);
+	const plain = lines.map(stripAnsi);
+	assert.match(plain[0], /^╭─ ❀ Agents · 1 active · 1 done ─+ 1m24s ╮$/);
+	assert.match(plain[1], /^│ ✓  sdd-explore  map footer data sources +claude-sonnet-5 · 34k · \$0\.27 · 25s │$/);
+	assert.match(plain[2], /^│ ◐  sdd-apply    write gentle-shell footer +claude-sonnet-5 · 12k · \$0\.09 · 41s │$/);
+	assert.match(plain[3], /^╰─+╯$/);
+	assert.deepEqual(renderAgentsCard([], plainTheme, 60, 0, { collapsed: false }), []);
+});
+
+test("renderAgentsCard renders singleton elapsed time only on its task row", () => {
+	const lines = renderAgentsCard([task({})], plainTheme, 84, 5_000, { collapsed: false }).map(stripAnsi);
+	assert.equal(lines.join("\n").match(/4s/g)?.length, 1);
+	assert.match(lines[1], /4s/);
+});
+
+test("renderAgentsCard keeps every task on one line, clipping long labels, and drops the task column when the card is narrow", () => {
+	const tasks = [task({ id: "a", label: "write the gentle shell footer and all of its tests before lunch" })];
+	const wide = renderAgentsCard(tasks, plainTheme, 84, 5_000, { collapsed: false }).map(stripAnsi);
+	assert.equal(wide.length, 3);
+	assert.match(wide[1], /^│ ◐  sdd-explore  write the gentle shell foot… +claude-sonnet-5 · 34k · \$0\.27 · 4s │$/);
+	const narrow = renderAgentsCard(tasks, plainTheme, 44, 5_000, { collapsed: false }).map(stripAnsi);
+	assert.equal(narrow.length, 3);
+	assert.match(narrow[1], /^│ ◐  sdd-explore +claude-sonnet-5 +│$/);
+});
+
+test("renderAgentsCard shows questions and failures in place of the task, and collapses to the first row", () => {
+	const tasks = [
+		task({ id: "a", status: TASK_STATUS.WAITING, lastStep: "asked: Delete?", tokens: 0, cost: 0 }),
+		task({ id: "b", status: TASK_STATUS.FAILED, endedAt: 2000, error: "pi exited with code 1", lastStep: "pi exited with code 1" }),
+		task({ id: "c", status: TASK_STATUS.QUEUED, createdAt: 1500, startedAt: null, tokens: 0, cost: 0 }),
+	];
+	const plain = renderAgentsCard(tasks, plainTheme, 80, 3000, { collapsed: false }).map(stripAnsi);
+	assert.match(plain[0], /^╭─ ❀ Agents · 1 waiting · 1 queued · 1 failed ─+ 2s ╮$/);
+	assert.match(plain[1], /^│ \?  sdd-explore  asked: Delete\? +claude-sonnet-5 · 2s │$/);
+	assert.match(plain[2], /^│ ✗  sdd-explore  pi exited with code 1 +claude-sonnet-5 · 34k · \$0\.27 · 1s │$/);
+	assert.match(plain[3], /^│ ○  sdd-explore  map footer data sources +queued │$/);
+	const collapsed = renderAgentsCard(tasks, plainTheme, 80, 3000, { collapsed: true, collapseKey: "ctrl+shift+a" }).map(stripAnsi);
+	assert.equal(collapsed.length, 3);
+	assert.match(collapsed[0], /ctrl\+shift\+a expand ╮$/);
+	assert.match(collapsed[1], /^│ \?  sdd-explore  asked: Delete\?/);
+});
+
+test("agent model and effort outrank usage at sidebar widths without inventing unknown values", () => {
+	for (const width of [32, 44, 60, 100]) {
+		const lines = renderAgentsCard([task({ agent: "worker", model: "openai/gpt-5", thinking: "high" })], plainTheme, width, 5000, { collapsed: false });
+		assert.equal(lines.length, 3);
+		assert.match(lines[1], /worker/);
+		assert.match(lines[1], /gpt-5 · high/);
+		for (const line of lines) assert.equal(visibleWidth(line), width);
+		if (width <= 44) assert.doesNotMatch(lines[1], /34k|\$0\.27|4s/);
+	}
+	for (const width of [0, 1, 2, 3, 4, 8, 16, 24]) {
+		const lines = renderAgentsCard([task({ agent: "界worker", thinking: "xhigh" })], plainTheme, width, 5000, { collapsed: false });
+		assert.ok(lines.length <= 4, "narrow metadata gets at most one dedicated row");
+		for (const line of lines) assert.equal(visibleWidth(line), width);
+	}
+	const sidebar = renderAgentsCard([task({ agent: "gentle-ai-worker", model: "openai/gpt-5.6", thinking: "high" })], plainTheme, 32, 5000, { collapsed: false });
+	assert.match(sidebar.join("\n"), /gentle-ai-worker/);
+	assert.match(sidebar.join("\n"), /gpt-5\.6 · high/);
+	for (const line of sidebar) assert.equal(visibleWidth(line), 32);
+	const unknown = renderAgentsCard([task({ model: "default", thinking: undefined })], plainTheme, 80, 5000, { collapsed: false }).join("\n");
+	assert.doesNotMatch(unknown, /default|undefined|high|off/);
+	const off = renderAgentsCard([task({ thinking: "off" })], plainTheme, 80, 5000, { collapsed: false }).join("\n");
+	assert.match(off, /claude-sonnet-5 · off/);
+});
+
+test("widgetRows caps the card at a quarter of the terminal, between three and eight rows", () => {
+	assert.equal(widgetRows(40), 8, "tall terminals still stop at eight rows");
+	assert.equal(widgetRows(24), 6);
+	assert.equal(widgetRows(10), 3, "short terminals keep three rows");
+	assert.equal(widgetRows(undefined), 8, "without a terminal the widest default applies");
+});
+
+test("renderAgentsCard caps the rows at maxRows, keeps active tasks ahead of finished ones, and says how many are hidden", () => {
+	const tasks = [
+		task({ id: "done", status: TASK_STATUS.COMPLETED, startedAt: 500, endedAt: 2000 }),
+		...Array.from({ length: 6 }, (_, index) => task({ id: `run${index}`, label: `job ${index}`, createdAt: 1000 + index, startedAt: 1000 + index })),
+	];
+	const plain = renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false, maxRows: 4, viewKey: "alt+a" }).map(stripAnsi);
+	assert.equal(plain.length, 6, "frame plus four rows");
+	assert.match(plain[0], /6 active · 1 done/, "the title still counts every shown task");
+	assert.match(plain[1], /◐  sdd-explore  job 0/);
+	assert.match(plain[3], /◐  sdd-explore  job 2/);
+	assert.match(plain[4], /^│ … 4 more · alt\+a to view +│$/, "the finished row gives way to running ones");
+	assert.equal(renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false }).length, 9, "without a cap every row shows");
+	assert.equal(renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false, maxRows: 7 }).length, 9, "at the cap no row is hidden");
+	assert.match(renderAgentsCard(tasks, plainTheme, 80, 5000, { collapsed: false, maxRows: 4 }).map(stripAnsi)[4], /^│ … 4 more +│$/, "no view key, no hint");
+	const waiting = [...tasks, task({ id: "ask", status: TASK_STATUS.WAITING, lastStep: "asked: Delete?", createdAt: 4000, startedAt: 4000 })];
+	assert.match(renderAgentsCard(waiting, plainTheme, 80, 5000, { collapsed: false, maxRows: 2 }).map(stripAnsi)[1], /^│ \?  sdd-explore  asked: Delete\?/, "a question is never hidden");
+});

package/tests/artifact-language.test.ts

@@ -149,6 +149,27 @@ test("SDD proposal questions focus on business and PRD gaps", async () => {
 	);
 });
 
+test("all shipped SDD agents and chains require parent preflight transport", async () => {
+	const agents = [
+		"sdd-init", "sdd-onboard", "sdd-explore", "sdd-research", "sdd-proposal", "sdd-spec", "sdd-design",
+		"sdd-tasks", "sdd-status", "sdd-apply", "sdd-verify", "sdd-sync", "sdd-archive", "sdd-remediate",
+	];
+	const chains = ["sdd-full", "sdd-plan", "sdd-verify"];
+	assert.equal(agents.length, 14);
+	assert.equal(chains.length, 3);
+	for (const agent of agents) {
+		const source = await readFile(join(ROOT, "assets", "agents", `${agent}.md`), "utf8");
+		assert.match(source, /## Parent Preflight Transport/);
+		assert.match(source, /never confirms or persists SDD choices/);
+		assert.doesNotMatch(source, /(?:infer|synthesize) (?:a )?(?:preflight )?(?:confirmation|defaults?) yourself/i);
+	}
+	for (const chain of chains) {
+		const source = await readFile(join(ROOT, "assets", "chains", `${chain}.chain.md`), "utf8");
+		assert.match(source, /## Parent preflight transport guard/);
+		assert.match(source, /Missing or malformed transport blocks the chain before its first phase/);
+	}
+});
+
 test("SDD chain assets distinguish interactive gates from auto execution", async () => {
 	const planChain = await readFile(join(ROOT, "assets/chains/sdd-plan.chain.md"), "utf8");
 	const fullChain = await readFile(join(ROOT, "assets/chains/sdd-full.chain.md"), "utf8");
@@ -212,8 +233,10 @@ test("SDD assets route completed implementation directly through verify, sync, a
 
 	assert.match(tasks, /<!-- sdd-owner: implementation -->/);
 	assert.match(apply, /next_recommended: "sdd-verify"/);
-	assert.match(status, /verify.*ready/i);
-	assert.match(contract, /apply.*verify.*sync.*archive/is);
+	assert.match(status, /gentle-ai\.sdd-status.*v2/i);
+	assert.match(status, /read-only/i);
+	assert.match(contract, /native.*(?:apply|verify).*archive/is);
+	assert.match(contract, /Manual `sdd-sync` remains its intentional local resolver/);
 	assert.match(chain, /apply.*verification/is);
 	assert.doesNotMatch(assets, /<!-- sdd-owner: parent -->/);
 	assert.doesNotMatch(assets, /parent-lifecycle/);

package/tests/ask-user-choice.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { getKeybindings, KeybindingsManager, setKeybindings, stripTerminalSequences, TUI_KEYBINDINGS } from "@earendil-works/pi-tui";
 import askUserChoice from "../extensions/ask-user-choice.ts";
 
 interface ChoiceResult {
@@ -16,6 +17,7 @@ interface ChoiceParameters {
 	additionalProperties?: boolean;
 	properties?: {
 		question?: unknown;
+		allowCustomResponse?: unknown;
 		options?: {
 			minItems?: number;
 			maxItems?: number;
@@ -25,7 +27,10 @@ interface ChoiceParameters {
 }
 
 interface ChoiceTool {
+	renderShell?: string;
 	name: string;
+	description?: string;
+	promptGuidelines?: string[];
 	parameters: ChoiceParameters;
 	execute: (...args: unknown[]) => Promise<ChoiceResult>;
 }
@@ -35,6 +40,35 @@ interface ChoiceLifecycleEvent {
 	data: { active: boolean };
 }
 
+interface NativeChoiceComponent {
+	render(width: number): string[];
+	handleInput(data: string): void;
+	handleMouse?: (event: Record<string, unknown>) => NativeChoiceMouseResult | undefined;
+}
+
+interface NativeChoiceMouseResult {
+	handled?: boolean;
+	focus?: boolean;
+	render?: boolean;
+}
+
+interface ChoiceTui {
+	requestRender(): void;
+}
+
+interface ChoiceTheme {
+	fg(color: string, text: string): string;
+	bg(color: string, text: string): string;
+	bold(text: string): string;
+}
+
+type ChoiceCustomFactory = (
+	tui: ChoiceTui,
+	theme: ChoiceTheme,
+	keybindings: unknown,
+	done: (value: unknown) => void,
+) => NativeChoiceComponent;
+
 type BeforeAgentStart = (event: unknown, ctx: { mode: string }) => void | Promise<void>;
 
 function registerChoiceTool(
@@ -103,11 +137,11 @@ function tuiContext(inputs: readonly string[], rendered: { value: string }) {
 	return {
 		mode: "tui",
 		ui: {
-			custom: async (factory: (tui: { requestRender(): void }, theme: { fg(_color: string, text: string): string; bold(text: string): string }, keybindings: unknown, done: (value: unknown) => void) => { render(width: number): string[]; handleInput(data: string): void }) => {
+			custom: async (factory: ChoiceCustomFactory) => {
 				let result: unknown;
 				const component = factory(
 					{ requestRender() {} },
-					{ fg: (_color, text) => text, bold: (text) => text },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
 					{},
 					(value) => {
 						result = value;
@@ -121,6 +155,10 @@ function tuiContext(inputs: readonly string[], rendered: { value: string }) {
 	};
 }
 
+test("ask_user_choice transcript opts out of Pi's painted tool shell", () => {
+	assert.equal(registerChoiceTool().tool.renderShell, "self");
+});
+
 test("ask_user_choice registers without runtime actions or overriding the open questionnaire", () => {
 	const registration = registerChoiceTool(["read", "ask_user_question"]);
 
@@ -129,20 +167,300 @@ test("ask_user_choice registers without runtime actions or overriding the open q
 	assert.deepEqual(registration.activeTools(), ["read", "ask_user_question"]);
 });
 
-test("ask_user_choice exposes a strict closed single-select schema", () => {
+test("ask_user_choice keeps closed mode by default and makes custom mode opt-in", () => {
 	const { tool } = registerChoiceTool();
 	const optionsSchema = tool.parameters.properties?.options;
 	const optionSchema = optionsSchema?.items;
 
 	assert.equal(tool.name, "ask_user_choice");
 	assert.equal(tool.parameters.additionalProperties, false);
-	assert.deepEqual(Object.keys(tool.parameters.properties ?? {}).sort(), ["options", "question"]);
+	assert.deepEqual(Object.keys(tool.parameters.properties ?? {}).sort(), ["allowCustomResponse", "options", "question"]);
+	assert.equal(tool.parameters.properties?.allowCustomResponse !== undefined, true);
+	assert.match(tool.description ?? "", /allowCustomResponse/);
+	assert.match((tool.promptGuidelines ?? []).join(" "), /Never enable allowCustomResponse.*provider-owned consent prompts.*maintenance authorizations.*exact opaque token/);
 	assert.equal(optionsSchema?.minItems, 2);
 	assert.equal(optionsSchema?.maxItems, 4);
 	assert.equal(optionSchema?.additionalProperties, false);
 	assert.deepEqual(Object.keys(optionSchema?.properties ?? {}).sort(), ["description", "label", "value"]);
 });
 
+test("ask_user_choice hover preserves the keyboard-selected opaque value", async () => {
+	const { tool } = registerChoiceTool();
+	let completionCalls = 0;
+	const result = await tool.execute("call", { question: "Proceed?", options }, new AbortController().signal, undefined, {
+		mode: "tui",
+		ui: { custom: async (factory: ChoiceCustomFactory) => {
+			let completed: unknown;
+			const component = factory({ requestRender() {} }, {
+				fg: (_color, text) => `\u001b[38;5;39m${text}\u001b[39m`,
+				bg: (_color, text) => `\u001b[48;5;236m${text}\u001b[49m`, bold: (text) => text,
+			}, {}, (value) => { completionCalls++; completed = value; });
+			const lines = component.render(80);
+			const first = lines.findIndex((line) => stripTerminalSequences(line).includes(options[0]!.label));
+			const second = lines.findIndex((line) => stripTerminalSequences(line).includes(options[1]!.label));
+			assert.ok(first >= 0 && second >= 0);
+			const hover = {
+				type: "move", button: "none", x: 0, y: second,
+				screenX: 0, screenY: second, width: 80, height: lines.length,
+				shift: false, alt: false, ctrl: false,
+			};
+			assert.equal(component.handleMouse?.(hover)?.render, true);
+			assert.equal(completed, undefined, "hover never submits");
+			const hovered = component.render(80);
+			assert.ok(hovered[second]?.includes("\u001b[48;5;236m"), "only the second option is hovered");
+			assert.ok(
+				hovered[first]?.includes("\u001b[38;5;39m") && !hovered[first]?.includes("\u001b[48;5;236m"),
+				"hover does not change keyboard selection",
+			);
+			component.handleInput("\r");
+			component.handleInput("\r");
+			return completed;
+		} },
+	});
+	assert.deepEqual(result.details.selection, { value: options[0]!.value, label: options[0]!.label, index: 1 });
+	assert.equal(completionCalls, 1);
+});
+
+test("ask_user_choice retains native rendered hit testing for mouse selection", async () => {
+	const longOptions = [
+		{
+			label: "Authorize the observed baseline hash after independent verification",
+			description: "Accept the observed baseline after a long description that verifies layout offsets.",
+			value: "authorize_observed_hash",
+		},
+		{
+			label: "Preserve the originally requested hash without changing the envelope",
+			description: "Keep the original opaque answer token after the user confirms the requested value.",
+			value: "preserve_requested_hash",
+		},
+	];
+	const { tool } = registerChoiceTool();
+	let completionCalls = 0;
+	const result = await tool.execute(
+		"call",
+		{
+			question: "A deliberately long question verifies that the rendered header does not shift native option hit bounds.",
+			options: longOptions,
+		},
+		new AbortController().signal,
+		undefined,
+		{
+			mode: "tui",
+			ui: {
+				custom: async (factory: ChoiceCustomFactory) => {
+					let completed: unknown;
+					const component = factory(
+						{ requestRender() {} },
+						{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+						{},
+						(value) => {
+							completionCalls++;
+							completed = value;
+						},
+					) as NativeChoiceComponent;
+					const narrow = component.render(24);
+					assert.ok(narrow.length > 0, "the real component renders before a narrow-to-wide resize");
+					const wide = component.render(100);
+					const secondRow = wide.findIndex((line) => line.includes(longOptions[1]!.label.slice(0, 24)));
+					assert.ok(secondRow >= 0, "the test locates the actual rendered option row");
+					const event = (type: string, button: string, y: number, wheelDelta?: number) => ({
+						type,
+						button,
+						x: 1,
+						y,
+						screenX: 1,
+						screenY: y,
+						width: 100,
+						height: wide.length,
+						shift: false,
+						alt: false,
+						ctrl: false,
+						wheelDelta,
+					});
+					assert.equal(typeof component.handleMouse, "function", "native mouse dispatch must survive the custom UI adapter");
+					const wheel = component.handleMouse?.(event("wheel", "none", secondRow, 1));
+					assert.equal(wheel?.handled, true);
+					assert.equal(wheel?.render, true);
+					assert.equal(completed, undefined, "wheel changes focus without answering");
+					assert.equal(component.handleMouse?.(event("release", "left", secondRow)), undefined);
+					assert.equal(component.handleMouse?.(event("click", "right", secondRow)), undefined);
+					assert.equal(component.handleMouse?.(event("click", "left", wide.length)), undefined);
+					assert.equal(component.handleMouse?.({ type: "click" }), undefined);
+					const press = component.handleMouse?.(event("press", "left", secondRow));
+					assert.equal(press?.handled, true);
+					assert.equal(press?.focus, true);
+					assert.equal(completed, undefined, "press focuses and selects but never answers");
+					component.handleMouse?.(event("click", "left", secondRow));
+					component.handleMouse?.(event("click", "left", secondRow));
+					component.handleInput("\r");
+					return completed;
+				},
+			},
+		},
+	);
+	assert.deepEqual(result.details.selection, {
+		value: "preserve_requested_hash",
+		label: longOptions[1]!.label,
+		index: 2,
+	});
+	assert.equal(completionCalls, 1, "late keyboard input cannot complete the choice twice");
+});
+
+test("ask_user_choice supports an opt-in custom response from keyboard navigation", async () => {
+	const { tool } = registerChoiceTool();
+	const rendered: string[] = [];
+	const response = "  exactly as typed  ";
+	const result = await tool.execute("call", { question: "Explain?", options, allowCustomResponse: true }, new AbortController().signal, undefined, {
+		mode: "tui",
+		ui: {
+			custom: async (factory: ChoiceCustomFactory) => {
+				let completed: unknown;
+				const component = factory(
+					{ requestRender() {} },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+					{},
+					(value) => { completed = value; },
+				);
+				rendered.push(component.render(80).join("\n"));
+				component.handleInput("\x1b[B");
+				component.handleInput("\x1b[B");
+				component.handleInput("\r");
+				rendered.push(component.render(80).join("\n"));
+				component.handleInput(response);
+				component.handleInput("\r");
+				return completed;
+			},
+		},
+	});
+	assert.match(rendered[0] ?? "", /Other…/);
+	assert.match(rendered[1] ?? "", /Custom response/);
+	assert.deepEqual(result.details, { question: "Explain?", options, customResponse: response });
+	assert.equal(result.content[0]?.text, `User responded: ${response}`);
+});
+
+test("ask_user_choice uses native input decoding and supplied custom editor keybindings", async () => {
+	const { tool } = registerChoiceTool();
+	const configured = new KeybindingsManager(TUI_KEYBINDINGS, {
+		"tui.select.down": "ctrl+n",
+		"tui.select.confirm": "ctrl+o",
+		"tui.select.cancel": "ctrl+x",
+		"tui.input.submit": "ctrl+s",
+		"tui.editor.deleteCharBackward": "ctrl+h",
+	});
+	const previous = getKeybindings();
+	setKeybindings(configured);
+	try {
+		const result = await tool.execute("call", { question: "Explain?", options, allowCustomResponse: true }, new AbortController().signal, undefined, {
+			mode: "tui",
+			ui: { custom: async (factory: ChoiceCustomFactory) => {
+				let completed: unknown;
+				const component = factory(
+					{ requestRender() {} },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+					configured, (value) => { completed = value; },
+				);
+				component.handleInput("\x0e");
+				component.handleInput("\x0e");
+				component.handleInput("\x0f");
+				component.handleInput("\x1b[97u");
+				component.handleInput("\x1b[98u");
+				component.handleInput("\x08");
+				component.handleInput("\x18");
+				assert.match(component.render(80).join("\n"), /Other…/);
+				component.handleInput("\x0f");
+				component.handleInput("\x13");
+				return completed;
+			} },
+		});
+		assert.deepEqual(result.details, { question: "Explain?", options, customResponse: "a" });
+	} finally {
+		setKeybindings(previous);
+	}
+});
+
+test("ask_user_choice activates an opt-in custom response from the Other row pointer target", async () => {
+	const { tool } = registerChoiceTool();
+	const result = await tool.execute("call", { question: "Explain?", options, allowCustomResponse: true }, new AbortController().signal, undefined, {
+		mode: "tui",
+		ui: {
+			custom: async (factory: ChoiceCustomFactory) => {
+				let completed: unknown;
+				const component = factory(
+					{ requestRender() {} },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+					{},
+					(value) => { completed = value; },
+				);
+				const lines = component.render(80);
+				const otherRow = lines.findIndex((line) => stripTerminalSequences(line).includes("Other…"));
+				assert.ok(otherRow >= 0);
+				const event = (type: string) => ({
+					type, button: "left", x: 0, y: otherRow, screenX: 0, screenY: otherRow,
+					width: 80, height: lines.length, shift: false, alt: false, ctrl: false,
+				});
+				assert.equal(component.handleMouse?.(event("press"))?.focus, true);
+				component.handleMouse?.(event("click"));
+				component.handleInput("pointer response");
+				component.handleInput("\r");
+				return completed;
+			},
+		},
+	});
+	assert.deepEqual(result.details, { question: "Explain?", options, customResponse: "pointer response" });
+});
+
+test("ask_user_choice rejects empty custom responses and escapes back to list cancellation", async () => {
+	const { tool } = registerChoiceTool();
+	const result = await tool.execute("call", { question: "Explain?", options, allowCustomResponse: true }, new AbortController().signal, undefined, {
+		mode: "tui",
+		ui: {
+			custom: async (factory: ChoiceCustomFactory) => {
+				let completed: unknown;
+				const choice = factory(
+					{ requestRender() {} },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+					{},
+					(value) => { completed = value; },
+				);
+				choice.handleInput("\x1b[B");
+				choice.handleInput("\x1b[B");
+				choice.handleInput("\r");
+				assert.match(choice.render(80).join("\n"), /Custom response/);
+				choice.handleInput("   ");
+				choice.handleInput("\r");
+				assert.equal(completed, undefined, "whitespace-only submission stays in the editor");
+				assert.match(choice.render(80).join("\n"), /Custom response/);
+				choice.handleInput("\x1b");
+				assert.match(choice.render(80).join("\n"), /Other…/);
+				choice.handleInput("\x1b");
+				return completed;
+			},
+		},
+	});
+	assert.deepEqual(result.details, { question: "Explain?", options, cancelled: true });
+});
+
+test("ask_user_choice renders Other only when custom response is explicitly enabled", async () => {
+	const { tool } = registerChoiceTool();
+	for (const allowCustomResponse of [undefined, false, true]) {
+		let rendered = "";
+		await tool.execute("call", { question: "Proceed?", options, ...(allowCustomResponse === undefined ? {} : { allowCustomResponse }) }, new AbortController().signal, undefined, {
+			mode: "tui",
+			ui: { custom: async (factory: ChoiceCustomFactory) => {
+				const component = factory(
+					{ requestRender() {} },
+					{ fg: (_color, text) => text, bg: (_color, text) => text, bold: (text) => text },
+					{}, () => {},
+				);
+				rendered = component.render(80).join("\n");
+				component.handleInput("\x1b");
+				return undefined;
+			} },
+		});
+		assert.equal(rendered.includes("Other…"), allowCustomResponse === true);
+	}
+});
+
 test("ask_user_choice handles a closed Kilo hash decision with an opaque envelope value", async () => {
 	const { tool } = registerChoiceTool(["read"]);
 	const rendered = { value: "" };
@@ -185,7 +503,9 @@ test("ask_user_choice emits a private balanced lifecycle around selection and ca
 			},
 		},
 	);
-	assert.equal(selected.details.selection?.value, "preserve_requested_hash");
+	const selection = selected.details.selection;
+	assert.ok(selection !== null && typeof selection === "object" && "value" in selection);
+	assert.equal(selection.value, "preserve_requested_hash");
 	assert.deepEqual(sequence, ["active", "custom", "inactive"]);
 	assert.deepEqual(selectedRegistration.emittedEvents(), [
 		{ channel: "gentle-pi:ask-user-choice:blocked", data: { active: true } },