@agnishc/edb-ask-user 0.8.2 → 0.10.3

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+## [0.10.3] - 2026-05-15
+
 ## [0.8.2] - 2026-05-11
 
 ## [0.8.1] - 2026-05-11

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agnishc/edb-ask-user",
-	"version": "0.8.2",
+	"version": "0.10.3",
 	"description": "Pi extension: ask_user tool for structured questions — text, choice, and multi-step wizard",
 	"keywords": [
 		"pi-package",

package/src/component.ts

@@ -1,5 +1,42 @@
-import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { Editor, type EditorTheme, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Answer, AskQuestion, AskResult, RenderOption } from "./types";
+import { wrapText } from "./utils";
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_VISIBLE_OPTIONS = 10;
+const OVERLAY_PADDING_X = 2;
+
+// ── Overlay frame helpers ──────────────────────────────────────────────────────
+
+function padToWidth(text: string, width: number): string {
+	const truncated = truncateToWidth(text, width, "");
+	return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+function framePopup(lines: string[], width: number, theme: any, title = ""): string[] {
+	if (width < 8) return lines.map((l) => truncateToWidth(l, width, ""));
+
+	const border = (t: string) => theme.fg("borderAccent", t);
+	const innerWidth = Math.max(1, width - 2 - OVERLAY_PADDING_X * 2);
+
+	const topBorder = (): string => {
+		if (!title) return `${border("┏")}${border("━".repeat(width - 2))}${border("┓")}`;
+		const safe = truncateToWidth(title, Math.max(1, width - 6), "…");
+		const titleStr = ` ${safe} `;
+		const fillW = Math.max(0, width - 2 - visibleWidth(titleStr));
+		return `${border("┏")}${theme.fg("accent", titleStr)}${border("━".repeat(fillW))}${border("┓")}`;
+	};
+
+	const framed: string[] = [topBorder()];
+	for (const line of lines) {
+		framed.push(
+			`${border("┃")}${" ".repeat(OVERLAY_PADDING_X)}${padToWidth(line, innerWidth)}${" ".repeat(OVERLAY_PADDING_X)}${border("┃")}`,
+		);
+	}
+	framed.push(`${border("┗")}${border("━".repeat(width - 2))}${border("┛")}`);
+	return framed.map((l) => truncateToWidth(l, width, ""));
+}
 
 // ── Component factory ──────────────────────────────────────────────────────────
 
@@ -12,18 +49,32 @@ export function createAskUserComponent(
 	theme: any,
 	done: (result: AskResult) => void,
 	questions: AskQuestion[],
+	opts?: { header?: string; useOverlay?: boolean },
 ) {
-	const isMulti = questions.length > 1;
-	const totalTabs = questions.length + 1; // questions + Submit tab
+	const header = opts?.header;
+	const useOverlay = opts?.useOverlay ?? false;
+
+	// A Submit tab is needed when there are multiple questions or any multiple-select question.
+	const needsSubmitTab = questions.length > 1 || questions.some((q) => q.multiple);
+	const totalTabs = questions.length + (needsSubmitTab ? 1 : 0);
 
 	// ── Shared state ──────────────────────────────────────────────────────────
 	let currentTab = 0;
-	let optionIndex = 0;
+	let submitCursor = 0; // cursor row on the Submit tab
 	let inputMode = false;
 	let inputQuestionId: string | null = null;
 	let cachedLines: string[] | undefined;
 
+	/** Committed answers (single-select + text questions). */
 	const answers = new Map<string, Answer>();
+	/** Selected option values per choice-question tab (multi-select). */
+	const multiSelections: Set<string>[] = questions.map(() => new Set());
+	/** Free-text entered via the isOther editor, per tab. */
+	const customTexts: string[] = questions.map(() => "");
+	/** Cursor row (absolute option index) per choice-question tab. */
+	const selectedRows: number[] = questions.map(() => 0);
+	/** Scroll offset (absolute option index of first visible row) per tab. */
+	const scrollOffsets: number[] = questions.map(() => 0);
 
 	// ── Inline editor ─────────────────────────────────────────────────────────
 	const editorTheme: EditorTheme = {
@@ -53,40 +104,87 @@ export function createAskUserComponent(
 		return questions[currentTab];
 	}
 
-	function currentOptions(): RenderOption[] {
-		const q = currentQuestion();
-		if (!q || q.type !== "choice") return [];
-		const rawOpts = q.options ?? [];
-		const opts: RenderOption[] = rawOpts.map((o) => ({
-			...o,
-			isOther: o.isOther === true ? true : undefined,
-		}));
-		// If no option is already marked as free-text (isOther), auto-append "Type something."
+	/** Builds the full options list for a question, auto-appending an isOther option if needed. */
+	function optionsFor(q: AskQuestion): RenderOption[] {
+		const raw = q.options ?? [];
+		const opts: RenderOption[] = raw.map((o) => ({ ...o }));
 		if (!opts.some((o) => o.isOther)) {
-			opts.push({ value: "__other__", label: "Type something.", isOther: true });
+			opts.push({ value: "__other__", label: q.customLabel ?? "Type something.", isOther: true });
 		}
 		return opts;
 	}
 
+	function currentOptions(): RenderOption[] {
+		const q = currentQuestion();
+		return q?.type === "choice" ? optionsFor(q) : [];
+	}
+
+	function maxVisibleFor(q: AskQuestion): number {
+		return Math.max(1, q.maxVisibleOptions ?? DEFAULT_MAX_VISIBLE_OPTIONS);
+	}
+
+	function isQuestionAnswered(q: AskQuestion, i: number): boolean {
+		if (q.type === "choice" && q.multiple) {
+			return multiSelections[i].size > 0 || customTexts[i].trim().length > 0;
+		}
+		return answers.has(q.id);
+	}
+
 	function allAnswered(): boolean {
-		return questions.every((q) => answers.has(q.id));
+		return questions.every((q, i) => isQuestionAnswered(q, i));
 	}
 
-	function advanceAfterAnswer() {
-		if (!isMulti) {
-			submitAll(false);
-			return;
+	/** Clamp selectedRows and scrollOffsets for a choice tab. */
+	function clampScroll(tabIndex: number): void {
+		const q = questions[tabIndex];
+		if (!q || q.type !== "choice") return;
+		const total = optionsFor(q).length;
+		const visible = maxVisibleFor(q);
+		selectedRows[tabIndex] = Math.max(0, Math.min(selectedRows[tabIndex] ?? 0, total - 1));
+		if (selectedRows[tabIndex] < scrollOffsets[tabIndex]) {
+			scrollOffsets[tabIndex] = selectedRows[tabIndex];
 		}
-		for (let i = currentTab + 1; i < questions.length; i++) {
-			if (!answers.has(questions[i]!.id)) {
-				switchToTab(i);
-				return;
-			}
+		if (selectedRows[tabIndex] >= scrollOffsets[tabIndex] + visible) {
+			scrollOffsets[tabIndex] = selectedRows[tabIndex] - visible + 1;
 		}
-		switchToTab(questions.length);
+		scrollOffsets[tabIndex] = Math.max(0, Math.min(scrollOffsets[tabIndex], Math.max(0, total - visible)));
 	}
 
-	function saveAnswer(questionId: string, value: string, label: string, wasCustom: boolean, optIndex?: number) {
+	/** Rebuild the Answer entry for a multiple-select question from its selections + custom text. */
+	function updateMultiAnswer(tabIndex: number): void {
+		const q = questions[tabIndex];
+		if (!q) return;
+		const opts = optionsFor(q);
+		const selected = Array.from(multiSelections[tabIndex]);
+		const custom = customTexts[tabIndex].trim();
+		const allValues = custom ? [...selected, custom] : selected;
+
+		if (allValues.length === 0) {
+			answers.delete(q.id);
+			return;
+		}
+
+		const labels = allValues.map((v) => opts.find((o) => o.value === v)?.label ?? v);
+		const indices = selected
+			.map((v) => {
+				const idx = opts.findIndex((o) => o.value === v && !o.isOther);
+				return idx >= 0 ? idx + 1 : undefined;
+			})
+			.filter((x): x is number => x !== undefined);
+
+		answers.set(q.id, {
+			id: q.id,
+			value: allValues[0]!,
+			values: allValues,
+			label: labels[0]!,
+			labels,
+			type: "choice",
+			wasCustom: Boolean(custom),
+			optionIndices: indices.length ? indices : undefined,
+		});
+	}
+
+	function saveAnswer(questionId: string, value: string, label: string, wasCustom: boolean, optIndex?: number): void {
 		const q = questions.find((x) => x.id === questionId);
 		answers.set(questionId, {
 			id: questionId,
@@ -98,11 +196,26 @@ export function createAskUserComponent(
 		});
 	}
 
-	function switchToTab(tabIndex: number) {
+	/** After answering a single-select or text question, advance to the next unanswered tab. */
+	function advanceAfterAnswer(): void {
+		if (!needsSubmitTab) {
+			submitAll(false);
+			return;
+		}
+		for (let i = currentTab + 1; i < questions.length; i++) {
+			if (!isQuestionAnswered(questions[i]!, i)) {
+				switchToTab(i);
+				return;
+			}
+		}
+		switchToTab(questions.length); // go to Submit tab
+	}
+
+	function switchToTab(tabIndex: number): void {
 		currentTab = tabIndex;
-		optionIndex = 0;
+		submitCursor = 0;
 		const q = questions[tabIndex];
-		if (q && q.type === "text") {
+		if (q?.type === "text") {
 			inputMode = true;
 			inputQuestionId = q.id;
 			const existing = answers.get(q.id);
@@ -112,17 +225,42 @@ export function createAskUserComponent(
 			inputQuestionId = null;
 			editor.setText("");
 		}
+		clampScroll(tabIndex);
 		refresh();
 	}
 
+	// ── Editor callbacks ──────────────────────────────────────────────────────
+
 	editor.onSubmit = (value) => {
 		if (!inputQuestionId) return;
+		const q = questions.find((x) => x.id === inputQuestionId);
+		if (!q) return;
 		const trimmed = value.trim() || "(no response)";
-		saveAnswer(inputQuestionId, trimmed, trimmed, true);
-		inputMode = false;
-		inputQuestionId = null;
-		editor.setText("");
-		advanceAfterAnswer();
+		const tabIndex = questions.indexOf(q);
+
+		if (q.type === "choice") {
+			if (q.multiple) {
+				customTexts[tabIndex] = trimmed;
+				updateMultiAnswer(tabIndex);
+				inputMode = false;
+				inputQuestionId = null;
+				editor.setText("");
+				refresh();
+			} else {
+				saveAnswer(q.id, trimmed, trimmed, true);
+				inputMode = false;
+				inputQuestionId = null;
+				editor.setText("");
+				advanceAfterAnswer();
+			}
+		} else {
+			// text question
+			saveAnswer(q.id, trimmed, trimmed, true);
+			inputMode = false;
+			inputQuestionId = null;
+			editor.setText("");
+			advanceAfterAnswer();
+		}
 	};
 
 	// ── Input handler ─────────────────────────────────────────────────────────
@@ -130,11 +268,12 @@ export function createAskUserComponent(
 	function handleInput(data: string) {
 		// ── Editor is active ───────────────────────────────────────────────
 		if (inputMode) {
-			if (matchesKey(data, Key.escape)) {
+			if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
 				const q = currentQuestion();
 				if (q?.type === "text") {
 					submitAll(true);
 				} else {
+					// Cancel the inline editor; go back to choice list
 					inputMode = false;
 					inputQuestionId = null;
 					editor.setText("");
@@ -147,8 +286,14 @@ export function createAskUserComponent(
 			return;
 		}
 
-		// ── Tab bar navigation (multi-question only) ───────────────────────
-		if (isMulti) {
+		// ── Global cancel ──────────────────────────────────────────────────
+		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			submitAll(true);
+			return;
+		}
+
+		// ── Tab bar navigation ─────────────────────────────────────────────
+		if (needsSubmitTab) {
 			if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
 				switchToTab((currentTab + 1) % totalTabs);
 				return;
@@ -160,65 +305,90 @@ export function createAskUserComponent(
 		}
 
 		// ── Submit tab ─────────────────────────────────────────────────────
-		if (isMulti && currentTab === questions.length) {
-			const submitItems = questions.length + 1;
+		if (needsSubmitTab && currentTab === questions.length) {
+			const itemCount = questions.length + 1; // question rows + Submit row
 			if (matchesKey(data, Key.up)) {
-				optionIndex = Math.max(0, optionIndex - 1);
+				submitCursor = Math.max(0, submitCursor - 1);
 				refresh();
 				return;
 			}
 			if (matchesKey(data, Key.down)) {
-				optionIndex = Math.min(submitItems - 1, optionIndex + 1);
+				submitCursor = Math.min(itemCount - 1, submitCursor + 1);
 				refresh();
 				return;
 			}
 			if (matchesKey(data, Key.enter)) {
-				if (optionIndex < questions.length) {
-					switchToTab(optionIndex);
+				if (submitCursor < questions.length) {
+					switchToTab(submitCursor);
 				} else if (allAnswered()) {
 					submitAll(false);
 				}
 				return;
 			}
-			if (matchesKey(data, Key.escape)) {
-				submitAll(true);
-			}
 			return;
 		}
 
 		const q = currentQuestion();
+		if (!q) return;
+		const tabIndex = currentTab;
 
-		// ── Choice question: option navigation ─────────────────────────────
-		if (q?.type === "choice") {
+		// ── Choice question ────────────────────────────────────────────────
+		if (q.type === "choice") {
 			const opts = currentOptions();
+			const maxVisible = maxVisibleFor(q);
+
 			if (matchesKey(data, Key.up)) {
-				optionIndex = Math.max(0, optionIndex - 1);
+				selectedRows[tabIndex] = Math.max(0, (selectedRows[tabIndex] ?? 0) - 1);
+				clampScroll(tabIndex);
 				refresh();
 				return;
 			}
 			if (matchesKey(data, Key.down)) {
-				optionIndex = Math.min(opts.length - 1, optionIndex + 1);
+				selectedRows[tabIndex] = Math.min(opts.length - 1, (selectedRows[tabIndex] ?? 0) + 1);
+				clampScroll(tabIndex);
 				refresh();
 				return;
 			}
-			if (matchesKey(data, Key.enter)) {
-				const opt = opts[optionIndex];
+			// Page up / down
+			if (matchesKey(data, Key.pageUp) || data === "-") {
+				selectedRows[tabIndex] = Math.max(0, (selectedRows[tabIndex] ?? 0) - maxVisible);
+				clampScroll(tabIndex);
+				refresh();
+				return;
+			}
+			if (matchesKey(data, Key.pageDown) || data === "=") {
+				selectedRows[tabIndex] = Math.min(opts.length - 1, (selectedRows[tabIndex] ?? 0) + maxVisible);
+				clampScroll(tabIndex);
+				refresh();
+				return;
+			}
+
+			const isSpaceToggle = data === " " && q.multiple;
+			if (matchesKey(data, Key.enter) || isSpaceToggle) {
+				const opt = opts[selectedRows[tabIndex] ?? 0];
 				if (!opt) return;
+
 				if (opt.isOther) {
 					inputMode = true;
 					inputQuestionId = q.id;
-					const existing = answers.get(q.id);
-					editor.setText(existing?.wasCustom ? existing.label : "");
+					const custom = customTexts[tabIndex];
+					editor.setText(custom || "");
+					refresh();
+				} else if (q.multiple) {
+					// Toggle multi-select
+					if (multiSelections[tabIndex].has(opt.value)) {
+						multiSelections[tabIndex].delete(opt.value);
+					} else {
+						multiSelections[tabIndex].add(opt.value);
+					}
+					updateMultiAnswer(tabIndex);
 					refresh();
 				} else {
-					saveAnswer(q.id, opt.value, opt.label, false, optionIndex + 1);
+					// Single-select: save and advance
+					const optIdx = selectedRows[tabIndex] ?? 0;
+					saveAnswer(q.id, opt.value, opt.label, false, optIdx + 1);
 					advanceAfterAnswer();
 				}
-				return;
-			}
-			if (matchesKey(data, Key.escape)) {
-				submitAll(true);
-				return;
 			}
 		}
 	}
@@ -228,19 +398,25 @@ export function createAskUserComponent(
 	function render(width: number): string[] {
 		if (cachedLines) return cachedLines;
 
-		const lines: string[] = [];
-		const add = (s: string) => lines.push(truncateToWidth(s, width));
-		const hr = () => add(theme.fg("accent", "─".repeat(width)));
-		hr();
+		// When using overlay, content is rendered at innerWidth and then framed.
+		const innerWidth = useOverlay ? Math.max(1, width - 2 - OVERLAY_PADDING_X * 2) : width;
+		const inner: string[] = [];
+		const add = (s: string) => inner.push(truncateToWidth(s, innerWidth));
 
 		const canSubmit = allAnswered();
 
+		// Header (inline mode only — overlay title is shown in the frame border)
+		if (!useOverlay && header) {
+			add(theme.bold(theme.fg("accent", ` ${header}`)));
+			inner.push("");
+		}
+
 		// ── Tab bar ─────────────────────────────────────────────────────────
-		if (isMulti) {
+		if (needsSubmitTab) {
 			const parts: string[] = ["  "];
 			for (let i = 0; i < questions.length; i++) {
 				const isActive = i === currentTab;
-				const isAnswered = answers.has(questions[i]!.id);
+				const isAnswered = isQuestionAnswered(questions[i]!, i);
 				const bullet = isAnswered ? "■" : "□";
 				const color: "success" | "muted" = isAnswered ? "success" : "muted";
 				const lbl = ` ${bullet} ${questions[i]!.label} `;
@@ -254,34 +430,36 @@ export function createAskUserComponent(
 					: theme.fg(canSubmit ? "success" : "dim", submitLabel),
 			);
 			add(parts.join(""));
-			lines.push("");
+			inner.push("");
 		}
 
-		// ── Content ─────────────────────────────────────────────────────────
+		// ── Content ──────────────────────────────────────────────────────────
 		const q = currentQuestion();
-		const opts = currentOptions();
 
-		if (isMulti && currentTab === questions.length) {
-			// Submit tab
+		if (needsSubmitTab && currentTab === questions.length) {
+			// ── Submit / Review tab ──────────────────────────────────────────
 			add(theme.fg("accent", theme.bold(" Review your answers")));
-			lines.push("");
+			inner.push("");
 			for (let i = 0; i < questions.length; i++) {
 				const question = questions[i]!;
 				const ans = answers.get(question.id);
-				const sel = optionIndex === i;
+				const sel = submitCursor === i;
 				const prefix = sel ? theme.fg("accent", "> ") : "  ";
 				add(prefix + (sel ? theme.fg("accent", question.prompt) : theme.fg("text", question.prompt)));
 				if (ans) {
-					const pre = ans.wasCustom ? theme.fg("muted", "(wrote) ") : theme.fg("dim", `${ans.optionIndex}. `);
-					add(`    ${theme.fg("success", "✓ ")}${pre}${theme.fg(sel ? "accent" : "muted", ans.label)}`);
+					const answerText = ans.labels && ans.labels.length > 1 ? ans.labels.join(", ") : ans.label;
+					const pre = ans.wasCustom
+						? theme.fg("muted", "(wrote) ")
+						: theme.fg("dim", ans.optionIndex ? `${ans.optionIndex}. ` : "");
+					add(`    ${theme.fg("success", "✓ ")}${pre}${theme.fg(sel ? "accent" : "muted", answerText)}`);
 				} else {
 					add(
 						`    ${theme.fg("warning", "✗ unanswered")}${sel ? theme.fg("dim", " — press Enter to answer") : ""}`,
 					);
 				}
-				lines.push("");
+				inner.push("");
 			}
-			const submitSel = optionIndex === questions.length;
+			const submitSel = submitCursor === questions.length;
 			const submitPrefix = submitSel ? theme.fg("accent", "> ") : "  ";
 			if (canSubmit) {
 				add(
@@ -290,90 +468,161 @@ export function createAskUserComponent(
 				);
 			} else {
 				const missing = questions
-					.filter((x) => !answers.has(x.id))
+					.filter((_q, i) => !isQuestionAnswered(questions[i]!, i))
 					.map((x) => x.label)
 					.join(", ");
 				add(`  ${theme.fg("dim", "✓ Submit All")} ${theme.fg("warning", `(unanswered: ${missing})`)}`);
 			}
-			lines.push("");
-			add(theme.fg("dim", " ↑↓ navigate • Enter to edit answer or submit • Tab/←→ switch tab • Esc cancel"));
+			inner.push("");
+			add(theme.fg("dim", " ↑↓ navigate • Enter to edit answer or submit • Tab/←→ switch tab • Esc/Ctrl+C cancel"));
 		} else if (q?.type === "text") {
-			add(theme.fg("text", ` ${q.prompt}`));
+			// ── Text question ────────────────────────────────────────────────
+			for (const line of wrapText(q.prompt, innerWidth - 1, 3)) {
+				add(theme.fg("text", ` ${line}`));
+			}
 			if (q.placeholder) add(theme.fg("dim", `   ${q.placeholder}`));
-			lines.push("");
-			for (const line of editor.render(width - 2)) add(` ${line}`);
-			lines.push("");
-			add(theme.fg("dim", " Enter to submit • Esc to cancel"));
+			inner.push("");
+			for (const line of editor.render(innerWidth - 2)) add(` ${line}`);
+			inner.push("");
+			add(theme.fg("dim", " Enter to submit • Esc/Ctrl+C to cancel"));
 		} else if (q?.type === "choice") {
-			add(theme.fg("text", ` ${q.prompt}`));
-			lines.push("");
+			// ── Choice question ──────────────────────────────────────────────
+			for (const line of wrapText(q.prompt, innerWidth - 1, 3)) {
+				add(theme.fg("text", ` ${line}`));
+			}
+			if (q.multiple) {
+				add(theme.fg("dim", " Space/Enter toggles • Tab to advance when done"));
+			}
+			inner.push("");
+
+			const tabIndex = currentTab;
+			const opts = optionsFor(q);
+			const maxVisible = maxVisibleFor(q);
+			const start = scrollOffsets[tabIndex] ?? 0;
+			const end = Math.min(opts.length, start + maxVisible);
+			const scrollable = opts.length > maxVisible;
+			const curRow = selectedRows[tabIndex] ?? 0;
+
 			if (inputMode) {
-				// Inline "other" editor inside option list
-				for (let i = 0; i < opts.length; i++) {
+				// Render options list with the inline editor on the isOther row
+				for (let i = start; i < end; i++) {
 					const opt = opts[i]!;
-					const selected = i === optionIndex;
-					const prefix = selected ? theme.fg("accent", "> ") : "  ";
+					const sel = i === curRow;
+					const prefix = sel ? theme.fg("accent", "> ") : "  ";
 					if (opt.isOther) {
-						add(prefix + theme.fg("accent", `${i + 1}. ${opt.label} ✎`));
+						const filled = customTexts[tabIndex].trim();
+						const rowLabel = filled ? `${opt.label}: ${filled}` : opt.label;
+						if (q.multiple) {
+							const chk = filled ? theme.fg("success", "[x] ") : theme.fg("muted", "[ ] ");
+							add(`${prefix}${chk}${theme.fg("accent", `${i + 1}. ${rowLabel} ✎`)}`);
+						} else {
+							add(`${prefix}${theme.fg("accent", `${i + 1}. ${rowLabel} ✎`)}`);
+						}
+						const hint = q.customPlaceholder ?? "Type your answer, then press Enter.";
+						add(theme.fg("muted", `     ${hint}`));
+						for (const line of editor.render(innerWidth - 4)) add(`   ${line}`);
 					} else {
-						add(
-							prefix +
-								(selected
-									? theme.fg("accent", `${i + 1}. ${opt.label}`)
-									: theme.fg("text", `${i + 1}. ${opt.label}`)),
-						);
+						if (q.multiple) {
+							const chk = multiSelections[tabIndex].has(opt.value)
+								? theme.fg("success", "[x] ")
+								: theme.fg("muted", "[ ] ");
+							add(
+								`${prefix}${chk}${sel ? theme.fg("accent", `${i + 1}. ${opt.label}`) : theme.fg("text", `${i + 1}. ${opt.label}`)}`,
+							);
+						} else {
+							add(
+								`${prefix}${sel ? theme.fg("accent", `${i + 1}. ${opt.label}`) : theme.fg("text", `${i + 1}. ${opt.label}`)}`,
+							);
+						}
 						if (opt.description) add(`     ${theme.fg("muted", opt.description)}`);
 					}
 				}
-				lines.push("");
-				add(theme.fg("muted", " Your answer:"));
-				for (const line of editor.render(width - 2)) add(` ${line}`);
-				lines.push("");
+				inner.push("");
 				add(theme.fg("dim", " Enter to submit • Esc to go back"));
 			} else {
-				for (let i = 0; i < opts.length; i++) {
+				// Normal option list
+				for (let i = start; i < end; i++) {
 					const opt = opts[i]!;
-					const selected = i === optionIndex;
-					const isAnswered =
-						!opt.isOther && answers.get(q.id)?.value === opt.value && !answers.get(q.id)?.wasCustom;
-					const prefix = selected ? theme.fg("accent", "> ") : "  ";
-					const checkmark = isAnswered ? theme.fg("success", " ✓") : "";
-					add(
-						prefix +
-							(selected
-								? theme.fg("accent", `${i + 1}. ${opt.label}`)
-								: theme.fg("text", `${i + 1}. ${opt.label}`)) +
-							checkmark,
-					);
-					if (opt.description) add(`     ${theme.fg("muted", opt.description)}`);
+					const sel = i === curRow;
+					const prefix = sel ? theme.fg("accent", "> ") : "  ";
+
+					if (opt.isOther) {
+						const filled = customTexts[tabIndex].trim();
+						const rowLabel = filled ? `${opt.label}: ${filled}` : opt.label;
+						if (q.multiple) {
+							const chk = filled ? theme.fg("success", "[x] ") : theme.fg("muted", "[ ] ");
+							add(
+								`${prefix}${chk}${sel ? theme.fg("accent", `${i + 1}. ${rowLabel}`) : theme.fg(filled ? "success" : "text", `${i + 1}. ${rowLabel}`)}`,
+							);
+						} else {
+							const chk = answers.get(q.id)?.wasCustom ? theme.fg("success", " ✓") : "";
+							add(
+								`${prefix}${sel ? theme.fg("accent", `${i + 1}. ${opt.label}`) : theme.fg("text", `${i + 1}. ${opt.label}`)}${chk}`,
+							);
+						}
+					} else {
+						const isChecked = q.multiple
+							? multiSelections[tabIndex].has(opt.value)
+							: answers.get(q.id)?.value === opt.value && !answers.get(q.id)?.wasCustom;
+
+						if (q.multiple) {
+							const chk = isChecked ? theme.fg("success", "[x] ") : theme.fg("muted", "[ ] ");
+							add(
+								`${prefix}${chk}${sel ? theme.fg("accent", `${i + 1}. ${opt.label}`) : theme.fg(isChecked ? "success" : "text", `${i + 1}. ${opt.label}`)}`,
+							);
+						} else {
+							const chk = isChecked ? theme.fg("success", " ✓") : "";
+							add(
+								`${prefix}${sel ? theme.fg("accent", `${i + 1}. ${opt.label}`) : theme.fg("text", `${i + 1}. ${opt.label}`)}${chk}`,
+							);
+						}
+						if (opt.description && !q.multiple) add(`     ${theme.fg("muted", opt.description)}`);
+					}
 				}
-				const existing = answers.get(q.id);
-				if (existing?.wasCustom) {
-					lines.push("");
-					add(
-						theme.fg("dim", "   Current: ") +
-							theme.fg("success", "✓ ") +
-							theme.fg("muted", "(wrote) ") +
-							theme.fg("accent", existing.label),
-					);
+
+				// Scroll indicator
+				if (scrollable) {
+					add(theme.fg("dim", `   (${start + 1}–${end} of ${opts.length}) ↑↓ scroll, -/= page`));
 				}
-				lines.push("");
+
+				// For single-select: show current custom answer below the list
+				if (!q.multiple) {
+					const existing = answers.get(q.id);
+					if (existing?.wasCustom) {
+						inner.push("");
+						add(
+							theme.fg("dim", "   Current: ") +
+								theme.fg("success", "✓ ") +
+								theme.fg("muted", "(wrote) ") +
+								theme.fg("accent", existing.label),
+						);
+					}
+				}
+
+				inner.push("");
+				const hintSuffix = needsSubmitTab ? " • Tab/←→ switch tab" : "";
 				add(
 					theme.fg(
 						"dim",
-						isMulti
-							? " ↑↓ navigate • Enter select • Tab/←→ switch tab • Esc cancel"
-							: " ↑↓ navigate • Enter select • Esc cancel",
+						q.multiple
+							? `↑↓ navigate • Space/Enter toggle${hintSuffix} • Esc/Ctrl+C cancel`
+							: `↑↓ navigate • Enter select${hintSuffix} • Esc/Ctrl+C cancel`,
 					),
 				);
 			}
 		}
 
-		lines.push("");
-		hr();
+		inner.push("");
+
+		// ── Wrap in frame or add horizontal rules ─────────────────────────
+		if (useOverlay) {
+			cachedLines = framePopup(inner, width, theme, header ?? "");
+		} else {
+			const hr = theme.fg("accent", "─".repeat(width));
+			cachedLines = [hr, ...inner, hr];
+		}
 
-		cachedLines = lines;
-		return lines;
+		return cachedLines;
 	}
 
 	// ── Bootstrap: activate first tab ─────────────────────────────────────────

package/src/index.ts

@@ -5,18 +5,25 @@
  * questions directly in the terminal UI — without an extra model round-trip.
  *
  * Supports three question modes (freely mixed in one call):
- *   - text   : free-form text input via inline editor
- *   - choice : pick from a numbered option list (+ always-available free-text)
+ *   - text    : free-form text input via inline editor
+ *   - choice  : pick from a numbered option list (single or multiple-select)
  *
- * Single question  → focused UI, no tab bar, immediate return
- * Multiple questions → tab-based wizard with a Submit tab
+ * Single question   → focused UI, no tab bar, immediate return on answer
+ * Multiple questions / any multiple-select → tab-based wizard with a Submit tab
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	type ExtensionAPI,
+	formatSize,
+	truncateHead,
+} from "@earendil-works/pi-coding-agent";
 import { createAskUserComponent } from "./component";
 import { renderCall, renderResult } from "./render";
 import { AskUserParams } from "./schemas";
 import type { AskQuestion, AskResult } from "./types";
+import { acquireModalLock, isModalActive, sleep, writeTempJson } from "./utils";
 
 // ── Extension ──────────────────────────────────────────────────────────────────
 
@@ -26,9 +33,10 @@ export default function askUserExtension(pi: ExtensionAPI): void {
 		label: "Ask User",
 		description:
 			"Ask the user one or more structured questions directly in the terminal UI. " +
-			"Supports free-text input, multiple-choice option lists, and multi-step " +
-			"questionnaires. Use this instead of embedding questions in your response text " +
-			"to avoid an extra model round-trip and give the user a clear, interactive prompt.",
+			"Supports free-text input, multiple-choice option lists (single or multi-select), " +
+			"and multi-step questionnaires. Use this instead of embedding questions in your " +
+			"response text to avoid an extra model round-trip and give the user a clear, " +
+			"interactive prompt.",
 		promptSnippet: "Ask the user a question or questionnaire and get structured answers",
 		promptGuidelines: [
 			"Use ask_user whenever you need information, a preference, or confirmation from the user before proceeding.",
@@ -36,19 +44,26 @@ export default function askUserExtension(pi: ExtensionAPI): void {
 			"For a single free-form question set type to 'text'. " +
 				"For a multiple-choice question set type to 'choice' and provide options. " +
 				"Pass several questions together for a multi-step flow.",
+			"Set multiple: true on a choice question to allow the user to select several options at once (checkbox style).",
 			"A free-text option is always available for choice questions. " +
 				"By default, a 'Type something.' option is auto-appended. " +
 				"If you want to provide your own free-text option (e.g. 'Other', 'Custom'), " +
-				"mark it with isOther: true — this replaces the default and avoids redundancy.",
+				"mark it with isOther: true — this replaces the default and avoids redundancy. " +
+				"Use customLabel / customPlaceholder to rename or hint that auto-appended option.",
+			"Use the header field to give the overall prompt a title (e.g. 'Deployment settings').",
+			"Set overlay: true for prominent confirmations or when terminal context should stay visible.",
 		],
 		parameters: AskUserParams,
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			// ── Guard: interactive mode only ──────────────────────────────────
 			if (!ctx.hasUI) {
 				return {
 					content: [
-						{ type: "text", text: "Error: ask_user requires an interactive terminal (UI not available)." },
+						{
+							type: "text",
+							text: "Error: ask_user requires an interactive terminal (UI not available).",
+						},
 					],
 					details: { questions: [], answers: [], cancelled: true } satisfies AskResult,
 				};
@@ -61,26 +76,71 @@ export default function askUserExtension(pi: ExtensionAPI): void {
 				};
 			}
 
-			// Validate: choice questions must have at least one option
+			// Validate choice questions have options
 			for (const q of params.questions) {
 				if (q.type === "choice" && (!q.options || q.options.length === 0)) {
 					return {
-						content: [{ type: "text", text: `Error: Question "${q.id}" is type 'choice' but has no options.` }],
+						content: [
+							{
+								type: "text",
+								text: `Error: Question "${q.id}" is type 'choice' but has no options.`,
+							},
+						],
 						details: { questions: [], answers: [], cancelled: true } satisfies AskResult,
 					};
 				}
 			}
 
+			// ── Queue behind any active modal ─────────────────────────────────
+			while (isModalActive()) {
+				if (signal?.aborted) {
+					return {
+						content: [{ type: "text", text: "Error: Tool call aborted while waiting for active modal." }],
+						details: { questions: [], answers: [], cancelled: true } satisfies AskResult,
+					};
+				}
+				await sleep(100);
+			}
+
 			// Normalise questions (fill in derived defaults)
 			const questions: AskQuestion[] = params.questions.map((q, i) => ({
 				...q,
 				label: q.label || `Q${i + 1}`,
 			}));
 
-			// ── Build & show the custom TUI ───────────────────────────────────
-			const result = await ctx.ui.custom<AskResult>((tui, theme, _kb, done) =>
-				createAskUserComponent(tui, theme, done, questions),
-			);
+			const useOverlay = params.overlay ?? false;
+			const overlayOpts = useOverlay
+				? {
+						overlay: true,
+						overlayOptions: {
+							anchor: "center" as const,
+							maxHeight: "80%" as `${number}%`,
+							width: 96,
+						},
+					}
+				: undefined;
+
+			// ── Acquire modal lock + save hardware cursor ─────────────────────
+			const releaseModalLock = acquireModalLock();
+			let restoreHardwareCursor: (() => void) | undefined;
+
+			let result: AskResult;
+			try {
+				result = await ctx.ui.custom<AskResult>((tui, theme, _kb, done) => {
+					const prev = (tui as any).getShowHardwareCursor?.();
+					if (prev !== undefined) {
+						(tui as any).setShowHardwareCursor?.(true);
+						restoreHardwareCursor = () => (tui as any).setShowHardwareCursor?.(prev);
+					}
+					return createAskUserComponent(tui, theme, done, questions, {
+						header: params.header,
+						useOverlay,
+					});
+				}, overlayOpts);
+			} finally {
+				restoreHardwareCursor?.();
+				releaseModalLock();
+			}
 
 			// ── Build response for LLM ────────────────────────────────────────
 			if (result.cancelled) {
@@ -93,12 +153,45 @@ export default function askUserExtension(pi: ExtensionAPI): void {
 			const lines = result.answers.map((a) => {
 				const q = questions.find((x) => x.id === a.id);
 				const label = q?.label ?? a.id;
+				if (a.labels && a.labels.length > 1) {
+					const parts = a.labels.map((lbl, i) => {
+						const idx = a.optionIndices?.[i];
+						return idx ? `${idx}. ${lbl}` : lbl;
+					});
+					return `${label} (${a.id}): user selected: ${parts.join(", ")}`;
+				}
 				if (a.wasCustom) return `${label} (${a.id}): user wrote: ${a.label}`;
 				return `${label} (${a.id}): user selected: ${a.optionIndex}. ${a.label}`;
 			});
 
+			const text = lines.join("\n");
+
+			// ── Truncate large responses ──────────────────────────────────────
+			const full = JSON.stringify(result, null, 2);
+			const truncation = truncateHead(full, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+
+			if (!truncation.truncated) {
+				return {
+					content: [{ type: "text", text }],
+					details: result satisfies AskResult,
+				};
+			}
+
+			const artifact = await writeTempJson(full);
+			const omittedLines = Math.max(0, truncation.totalLines - truncation.outputLines);
+			const omittedBytes = Math.max(0, truncation.totalBytes - truncation.outputBytes);
+			const artifactNote = artifact.path
+				? ` Full output saved to: ${artifact.path}`
+				: artifact.error
+					? ` Full output preservation failed: ${artifact.error}`
+					: "";
+			const truncationNotice =
+				`[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines ` +
+				`(${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). ` +
+				`${omittedLines} lines (${formatSize(omittedBytes)}) omitted.${artifactNote}]`;
+
 			return {
-				content: [{ type: "text", text: lines.join("\n") }],
+				content: [{ type: "text", text: `${text}\n\n${truncationNotice}` }],
 				details: result satisfies AskResult,
 			};
 		},

package/src/render.ts

@@ -7,9 +7,10 @@ export function renderCall(args: any, theme: any): any {
 	const qs = (args.questions as AskQuestion[]) ?? [];
 	const count = qs.length;
 	let text = theme.fg("toolTitle", theme.bold("ask_user "));
+	if (args.header) text += theme.fg("accent", `${args.header} `) + theme.fg("dim", "— ");
 	if (count === 1) {
 		const q = qs[0];
-		const typeTag = theme.fg("muted", `[${q?.type ?? "?"}] `);
+		const typeTag = theme.fg("muted", `[${q?.type ?? "?"}${q?.multiple ? "/multi" : ""}] `);
 		text += typeTag + theme.fg("muted", q?.prompt ?? "");
 	} else {
 		text += theme.fg("muted", `${count} questions`);
@@ -19,7 +20,7 @@ export function renderCall(args: any, theme: any): any {
 	return new Text(text, 0, 0);
 }
 
-export function renderResult(result: any, _options: any, theme: any): any {
+export function renderResult(result: any, options: any, theme: any): any {
 	const details = result.details as AskResult | undefined;
 	if (!details) {
 		const first = result.content[0];
@@ -29,20 +30,61 @@ export function renderResult(result: any, _options: any, theme: any): any {
 		return new Text(theme.fg("warning", "Cancelled"), 0, 0);
 	}
 
-	const lines = details.answers.map((a) => {
-		const q = details.questions.find((x) => x.id === a.id);
-		const label = q?.label ?? a.id;
-		if (a.wasCustom) {
-			return (
-				theme.fg("success", "✓ ") +
-				theme.fg("accent", label) +
-				theme.fg("dim", ": ") +
-				theme.fg("muted", "(wrote) ") +
-				a.label
-			);
+	if (!options?.expanded) {
+		// ── Compact mode ──────────────────────────────────────────────────
+		const lines = details.answers.map((a) => {
+			const q = details.questions.find((x) => x.id === a.id);
+			const label = q?.label ?? a.id;
+			if (a.labels && a.labels.length > 1) {
+				return (
+					theme.fg("success", "✓ ") +
+					theme.fg("accent", label) +
+					theme.fg("dim", ": ") +
+					theme.fg("text", a.labels.join(", "))
+				);
+			}
+			if (a.wasCustom) {
+				return (
+					theme.fg("success", "✓ ") +
+					theme.fg("accent", label) +
+					theme.fg("dim", ": ") +
+					theme.fg("muted", "(wrote) ") +
+					a.label
+				);
+			}
+			const num = a.optionIndex ? `${a.optionIndex}. ` : "";
+			return theme.fg("success", "✓ ") + theme.fg("accent", label) + theme.fg("dim", ": ") + num + a.label;
+		});
+		const expandHint = theme.fg("dim", " · ctrl+o to expand");
+		return new Text(lines.join("\n") + expandHint, 0, 0);
+	}
+
+	// ── Expanded mode ──────────────────────────────────────────────────────
+	const lines: string[] = [];
+	for (let i = 0; i < details.questions.length; i++) {
+		const q = details.questions[i]!;
+		const ans = details.answers.find((a) => a.id === q.id);
+		const isLast = i === details.questions.length - 1;
+		const branch = theme.fg("muted", isLast ? "  └─ " : "  ├─ ");
+		const stem = theme.fg("muted", isLast ? "     " : "  │  ");
+
+		lines.push(`${branch}${theme.fg("accent", theme.bold(q.label ?? q.id))}`);
+		lines.push(`${stem}${theme.fg("muted", "Q: ")}${theme.fg("text", q.prompt)}`);
+
+		if (!ans) {
+			lines.push(`${stem}  ${theme.fg("warning", "✗ unanswered")}`);
+		} else if (ans.labels && ans.labels.length > 0) {
+			for (const lbl of ans.labels) {
+				const pre = ans.wasCustom ? theme.fg("muted", "(wrote) ") : "";
+				lines.push(`${stem}  ${theme.fg("success", "✓")} ${pre}${theme.fg("text", lbl)}`);
+			}
+		} else {
+			const pre = ans.wasCustom ? theme.fg("muted", "(wrote) ") : "";
+			lines.push(`${stem}  ${theme.fg("success", "✓")} ${pre}${theme.fg("text", ans.label)}`);
 		}
-		const num = a.optionIndex ? `${a.optionIndex}. ` : "";
-		return theme.fg("success", "✓ ") + theme.fg("accent", label) + theme.fg("dim", ": ") + num + a.label;
-	});
+
+		if (!isLast) lines.push(theme.fg("muted", "  │"));
+	}
+
 	return new Text(lines.join("\n"), 0, 0);
 }

package/src/schemas.ts

@@ -21,7 +21,7 @@ export const OptionSchema = Type.Object({
 				"Mark this option as a free-text option. When selected, opens an inline editor " +
 				"instead of returning the option value. Use this when you want to provide your own " +
 				"label for the free-text option (e.g. 'Other', 'Custom'). " +
-				"If no option is marked isOther, a default 'Type something.' option is auto-appended. " +
+				"If no option is marked isOther, a default free-text option is auto-appended. " +
 				"Only one option should be marked isOther per question.",
 		}),
 	),
@@ -57,13 +57,50 @@ export const QuestionSchema = Type.Object({
 				"(e.g. 'Enter your API key…'). Purely informational.",
 		}),
 	),
+	multiple: Type.Optional(
+		Type.Boolean({
+			description:
+				"Allow the user to select multiple options (checkbox style). " +
+				"Only applies to choice questions. Default: false.",
+		}),
+	),
+	customLabel: Type.Optional(
+		Type.String({
+			description:
+				"Label for the free-text option row when no option is marked isOther. " + "Defaults to 'Type something.'",
+		}),
+	),
+	customPlaceholder: Type.Optional(
+		Type.String({
+			description: "Placeholder shown inside the inline editor for the free-text option in choice questions.",
+		}),
+	),
+	maxVisibleOptions: Type.Optional(
+		Type.Number({
+			description: "Maximum number of option rows visible before scrolling kicks in. Default: 10.",
+		}),
+	),
 });
 
 export const AskUserParams = Type.Object({
+	header: Type.Optional(
+		Type.String({
+			description:
+				"Optional title shown at the top of the prompt (e.g. 'Deployment settings'). " +
+				"Summarises the overall interaction.",
+		}),
+	),
 	questions: Type.Array(QuestionSchema, {
 		description:
 			"One or more questions to ask the user. " +
 			"Single-item arrays show a focused UI. " +
 			"Multi-item arrays show a tabbed wizard with a Submit step.",
 	}),
+	overlay: Type.Optional(
+		Type.Boolean({
+			description:
+				"Render the prompt as a framed popup overlay centred in the terminal instead of inline. " +
+				"Use for prominent confirmations or when screen context should remain visible. Default: false.",
+		}),
+	),
 });

package/src/types.ts

@@ -16,15 +16,32 @@ export interface AskQuestion {
 	options?: QuestionOption[];
 	placeholder?: string;
 	label?: string;
+	/** Allow the user to select multiple options (checkbox style). Only applies to choice questions. Default: false. */
+	multiple?: boolean;
+	/** Label for the auto-appended free-text option when no option is marked isOther. Defaults to "Type something." */
+	customLabel?: string;
+	/** Placeholder shown inside the inline editor for the free-text option in choice questions. */
+	customPlaceholder?: string;
+	/** Maximum number of option rows visible before scrolling kicks in. Default: 10. */
+	maxVisibleOptions?: number;
 }
 
 export interface Answer {
 	id: string;
+	/** Primary selected value (first value for multiple-select). */
 	value: string;
+	/** All selected values — populated for multiple: true questions. */
+	values?: string[];
+	/** Primary display label. */
 	label: string;
+	/** All selected labels — populated for multiple: true questions. */
+	labels?: string[];
 	type: "text" | "choice";
 	wasCustom: boolean;
+	/** 1-based option index (single-select). */
 	optionIndex?: number;
+	/** 1-based option indices (multiple-select). */
+	optionIndices?: number[];
 }
 
 export interface AskResult {

package/src/utils.ts

@@ -0,0 +1,100 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+// ── Text wrapping ──────────────────────────────────────────────────────────────
+
+/**
+ * Reflows plain text into lines of at most `width` visible characters.
+ * The last rendered line gets an ellipsis if the full text didn't fit.
+ */
+export function wrapText(text: string, width: number, maxLines = 4): string[] {
+	const words = text.trim().split(/\s+/).filter(Boolean);
+	if (!words.length) return [""];
+
+	const lines: string[] = [];
+	let current = "";
+
+	for (const word of words) {
+		const wordW = visibleWidth(word);
+		const currentW = visibleWidth(current);
+		if (!current) {
+			current = wordW > width ? word.slice(0, width) : word;
+		} else if (currentW + 1 + wordW <= width) {
+			current = `${current} ${word}`;
+		} else {
+			lines.push(current);
+			if (lines.length >= maxLines) {
+				current = "";
+				break;
+			}
+			current = wordW > width ? word.slice(0, width) : word;
+		}
+	}
+
+	if (current && lines.length < maxLines) lines.push(current);
+
+	// Append ellipsis on last line if the text was clipped
+	const fullText = words.join(" ");
+	const rendered = lines.join(" ");
+	if (rendered.length < fullText.length && lines.length > 0) {
+		const last = lines[lines.length - 1]!;
+		lines[lines.length - 1] = visibleWidth(last) < width ? `${last}…` : `${last.slice(0, Math.max(0, width - 1))}…`;
+	}
+
+	return lines.length > 0 ? lines : [""];
+}
+
+// ── Modal lock ─────────────────────────────────────────────────────────────────
+
+const MODAL_LOCK_SYMBOL = Symbol.for("edb.ask-user.modal-lock");
+
+interface ModalLock {
+	depth: number;
+}
+
+function getModalLock(): ModalLock {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	let lock = host[MODAL_LOCK_SYMBOL] as ModalLock | undefined;
+	if (!lock) {
+		lock = { depth: 0 };
+		host[MODAL_LOCK_SYMBOL] = lock;
+	}
+	return lock;
+}
+
+/** Returns true while another ask_user prompt is already open. */
+export function isModalActive(): boolean {
+	return getModalLock().depth > 0;
+}
+
+/** Marks a modal as open. Returns a release callback. */
+export function acquireModalLock(): () => void {
+	const lock = getModalLock();
+	lock.depth += 1;
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		lock.depth = Math.max(0, lock.depth - 1);
+	};
+}
+
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Temp file output ───────────────────────────────────────────────────────────
+
+/** Writes content to a unique temp file. Returns the path or an error string. */
+export async function writeTempJson(content: string): Promise<{ path?: string; error?: string }> {
+	try {
+		const dir = await mkdtemp(join(tmpdir(), "pi-ask-user-"));
+		const filePath = join(dir, "result.json");
+		await writeFile(filePath, content, { encoding: "utf-8", mode: 0o600 });
+		return { path: filePath };
+	} catch (e) {
+		return { error: e instanceof Error ? e.message : String(e) };
+	}
+}