@d3ara1n/pi-ask-user 2.0.0 → 2.1.1

package/README.md

@@ -4,24 +4,20 @@ A collapsible **ask-user** tool for [pi](https://github.com/earendil-works/pi).
 
 ## Why
 
-Other ask-user tools render a panel that covers the transcript, and even when
-they "collapse" they keep keyboard focus locked on the panel — so you **can't
+Most ask-user tools render a panel that covers the transcript, so you **can't
 scroll the conversation** to read the analysis that should inform your choice.
 You end up choosing blind.
 
-This tool fixes that:
+This tool fixes that by **not** using a screen overlay. The panel renders into
+pi's bottom `editorContainer` slot (the same path `ctx.ui.select()` /
+`ctx.ui.input()` take), so the transcript stays visible **above** the panel and
+remains scrollable via the terminal's native scrollback — mouse wheel,
+`Shift+PgUp`, `Cmd+↑`. This works because pi's TUI never enters alt-screen and
+never tracks the mouse, so every rendered chat line lives in the terminal
+buffer and can be scrolled back at any time, no focus gymnastics needed.
 
-- **Collapse actually releases focus.** Press `Ctrl+\` and the panel shrinks to
-  a single status row while `OverlayHandle.unfocus()` hands focus back to the
-  transcript. Your normal scroll mechanisms work again — mouse wheel,
-  `Shift+PgUp`, `Ctrl+Left`/`Ctrl+Right` tree nav, `/tree`.
-- **Re-expand works from anywhere.** A global shortcut (`pi.registerShortcut`)
-  captures `Ctrl+\` from the editor, so pressing it again re-expands and
-  re-focuses the panel — no matter where focus currently is.
-
-> **Note:** Because pi removes the editor from the UI tree while an overlay is
-> active, full transcript scrolling while collapsed depends on pi's overlay
-> behavior. The collapse affordance is kept as best-effort.
+- **Collapse** (`Ctrl+\`) shrinks the panel to a single status row, leaving
+  even more of the transcript on screen while you decide.
 
 ## Tool: `ask_user`
 
@@ -194,11 +190,40 @@ treat it as high-priority context.
 
 ### Result
 
-The tool returns a summary plus structured `answers`, and optionally a
-`message` (the user's review-screen note, only when non-empty). If the user
-cancelled mid-way, the summary notes how many questions were answered before
-cancellation. When present, the note is appended as a separate `Note from user:`
-block so it's visually distinct from the per-question answers.
+The tool result returned to the model is **JSON**, shaped symmetrically with
+the questions schema so the model can correlate each answer back to its own
+question by the `tab` key:
+
+```json
+{
+  "cancelled": false,
+  "answers": [
+    { "tab": "layout", "answer": "Sidebar" },
+    { "tab": "extras", "answers": ["dark-mode"], "custom": "also add export-to-pdf" },
+    { "tab": "db", "skipped": true }
+  ],
+  "message": "leaning towards the minimal option"
+}
+```
+
+Only the relevant fields appear per answer (no noise):
+
+| Situation | Fields |
+|-----------|--------|
+| single-select, option picked | `answer` |
+| single-select, custom typed | `custom` |
+| multi-select, options picked | `answers: [...]` |
+| multi-select, options + custom | `answers` + `custom` |
+| multi-select, custom only | `custom` |
+| multi-select, empty commit (skippable, submitted with nothing) | `answers: []` |
+| any question, Tab-skipped | `skipped: true` |
+
+`custom` is always a sibling of `answer`/`answers`, never mixed in — it signals
+the user typed something outside the offered options. The top-level `message`
+(the user's review-screen note) appears only when non-empty. `cancelled: true`
+means the user pressed `Esc`; `answers` still lists whatever was answered
+before cancellation. This JSON shape replaces the old `"tab: answer"` text
+format, which could break when a custom answer contained a colon or newline.
 
 ## Keys
 
@@ -212,7 +237,11 @@ block so it's visually distinct from the per-question answers.
 | `Esc` | Cancel (or exit custom-input editor without saving) |
 | `Ctrl+\` | Collapse / expand the panel |
 
-## Install
+## Dependencies
+
+None.
+
+## Installation
 
 Add to `~/.pi/agent/settings.json`:
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@d3ara1n/pi-ask-user",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
-  "description": "Ask-user tool for pi — collapsible question overlay that releases focus so you can scroll the transcript while deciding",
+  "description": "Ask-user tool for pi — renders in the bottom editor slot (not a screen overlay), so the transcript stays visible and scrollable above the panel while you decide",
   "main": "src/index.ts",
   "keywords": [
     "pi-package",
@@ -23,7 +23,8 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/d3ara1n/pi-extensions/main/packages/pi-ask-user/preview.png"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -2,10 +2,10 @@
  * pi-ask-user — An ask-user tool for pi.
  *
  * Design notes:
- *   - Collapsible panel (Ctrl+\). Collapsing calls `handle.unfocus()` to release
- *     focus back to the editor. NOTE: because pi removes the editor from the UI
- *     tree while an overlay is active, full transcript scrolling while collapsed
- *     depends on pi behaviour; this is kept as a best-effort affordance.
+ *   - Collapsible panel (Ctrl+\) shrinks the panel to one row so more of the
+ *     transcript stays on screen. Chat scrolling does NOT depend on keyboard
+ *     focus at all — it is the terminal scrollback (see Layout note below), so
+ *     it works whether the panel is expanded, collapsed, or focused.
  *   - Per-question state (cursor position, scroll offset, type-something draft,
  *     multi-select picks) survives tab navigation — switching tabs never loses
  *     what you typed.
@@ -17,10 +17,18 @@
  *     field, the question renders in two equal columns (options | preview);
  *     otherwise it renders single-column full-width.
  *
- * Layout: bottom-anchored full-width overlay. Collapses to a single status row.
+ * Layout: renders into pi's bottom `editorContainer` slot (overlay:false, NOT a
+ *   screen overlay). The chat transcript stays visible ABOVE the panel and is
+ *   scrollable via the terminal's native scrollback (mouse wheel / Shift-PgUp /
+ *   Cmd-↑). This works because pi's TUI never enters alt-screen and never tracks
+ *   the mouse, so every rendered chat line lives in the terminal buffer and can
+ *   be scrolled back at any time — the exact mechanism ctx.ui.select()/input()
+ *   rely on. (overlay:true would route through ui.showOverlay(), compositing the
+ *   panel over the whole screen and visually hiding the transcript — making it
+ *   unscrollable, which was the original bug.) Collapses to one status row.
  */
 
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import {
 	type Component,
 	Editor,
@@ -44,6 +52,8 @@ const ICON_CHECK_EMPTY = "□"; // U+25A1
 const ICON_CHECK_FILLED = "▣"; // U+25A3
 const ICON_OTHER = "✎"; // pencil for "Type something."
 const ICON_CURSOR = "▸"; // current cursor position, independent of selection
+const ICON_NOTE = ICON_OTHER; // same ✎ pencil as custom answers — the note is also free-form user input
+const ICON_ANSWER = "›"; // lead glyph on option-pick answers in the result card
 
 // ────────────────────────────────────────────────────────────────────────────
 // Types
@@ -69,19 +79,24 @@ interface Question {
 	allowSkip?: boolean;
 }
 
-interface Answer {
-	tab: string;
-	/** Single-select: the chosen label. Multi-select: empty string. */
-	answerLabel: string;
-	/** Multi-select: all chosen labels. Single-select: absent. */
-	answerLabels?: string[];
-	wasCustom: boolean;
-	index?: number;
-	/** True for multi-select answers. */
-	multiSelect?: boolean;
-	/** True if the user skipped this question (only set when allowSkip is true). */
-	skipped?: boolean;
-}
+/** A committed answer. Discriminated by `kind` so every state carries exactly
+ *  the fields it needs — the compiler guarantees completeness, and the three
+ *  display/serialization consumers all derive from `describeAnswer()` (single
+ *  source of truth) so they can never drift apart.
+ *
+ *  - `single`: the user picked one of the offered options.
+ *  - `custom`: single-select, the user typed a custom answer ("Type something.").
+ *  - `multi`:  multi-select — `options` are the picked option labels; an
+ *    optional `custom` carries any typed text alongside them. Pure-custom
+ *    (no options checked) is `options: []` + `custom`; an empty commit
+ *    (skippable, submitted with nothing) is `options: []` with no `custom`.
+ *  - `skipped`: the user navigated past without answering (Tab/arrows).
+ */
+type Answer =
+	| { tab: string; kind: "single"; option: string }
+	| { tab: string; kind: "custom"; text: string }
+	| { tab: string; kind: "multi"; options: string[]; custom?: string }
+	| { tab: string; kind: "skipped" };
 
 interface AskUserResult {
 	questions: Question[];
@@ -223,6 +238,49 @@ function padRight(s: string, width: number): string {
 	return v >= width ? s : s + " ".repeat(width - v);
 }
 
+/** Truncate to a visible width, appending “…” only when the text actually
+ *  overflows. (truncateToWidth's third arg is a fill, not a suffix, so we
+ *  reserve one column and append the ellipsis ourselves when needed.) */
+function truncForDisplay(text: string, maxW: number): string {
+	if (maxW <= 0) return "";
+	if (maxW === 1) return "…";
+	const vw = visibleWidth(text);
+	if (vw <= maxW) return text;
+	return truncateToWidth(text, maxW - 1, "") + "…";
+}
+
+/** Structured interpretation of an Answer for display/serialization.
+ *  Single source of truth — all three consumers (review screen's
+ *  formatAnswerText, result card's formatAnswer, execute's JSON payload)
+ *  derive from this, so they can never drift apart. */
+interface AnswerView {
+	/** Human-readable text WITHOUT ANSI — e.g. "Sidebar" / "甲, 乙" /
+	 *  "✎ 自定义文本" / "(none)" / "(skipped)". Consumers wrap it in color. */
+	text: string;
+	/** Theme color name for the whole text. */
+	color: ThemeColor;
+}
+
+/** Interpret an Answer into display form. `customGlyph` (default "✎") prefixes
+ *  any custom text. Returns `(no answer)` / dim for an absent answer. */
+function describeAnswer(ans: Answer | undefined, customGlyph = ICON_OTHER): AnswerView {
+	if (!ans) return { text: "(no answer)", color: "dim" };
+	switch (ans.kind) {
+		case "skipped":
+			return { text: "(skipped)", color: "warning" };
+		case "multi": {
+			if (ans.options.length === 0 && !ans.custom) return { text: "(none)", color: "dim" };
+			const parts = [...ans.options];
+			if (ans.custom) parts.push(`${customGlyph} ${ans.custom}`);
+			return { text: parts.join(", "), color: "text" };
+		}
+		case "custom":
+			return { text: `${customGlyph} ${ans.text}`, color: "text" };
+		case "single":
+			return { text: ans.option, color: "text" };
+	}
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // The overlay component
 // ────────────────────────────────────────────────────────────────────────────
@@ -233,7 +291,6 @@ interface TuiLike {
 
 interface PanelCallbacks {
 	onResult: (result: AskUserResult) => void;
-	onCollapseChange: (collapsed: boolean) => void;
 }
 
 class AskUserPanel implements Component, Focusable {
@@ -251,19 +308,14 @@ class AskUserPanel implements Component, Focusable {
 	private tabs: TabState[];
 	/** Visible option rows (recomputed each render). */
 	private optionViewportH = 8;
-	/** When true, the panel shows a review summary of all answers; Enter submits. */
-	private reviewMode = false;
-	/** Cursor row in the review summary. */
+	/** Cursor row in the review summary (shown on the review tab). */
 	private reviewCursor = 0;
 	/** Vertical scroll offset for the review viewport. */
 	private reviewScrollOffset = 0;
 	/** Visible review rows (recomputed each render). */
 	private reviewViewportH = 8;
-	/** True after jumping from review mode to edit a question; makes answering
-	 *  return to review instead of advancing to the next question. */
-	private editingFromReview = false;
 	/** True while the user is editing the free-form "note to assistant" on the
-	 *  review screen. While true, all input goes to messageEditor. */
+	 *  review tab. While true, all input goes to messageEditor. */
 	private messageEditing = false;
 	/** Committed note text (trimmed). Empty string = no note. Lives only on the
 	 *  review screen; the LLM cannot set it. */
@@ -339,21 +391,22 @@ class AskUserPanel implements Component, Focusable {
 		}
 		this.answers.set(q.tab, {
 			tab: q.tab,
-			answerLabel: trimmed,
-			wasCustom: true,
+			kind: "custom",
+			text: trimmed,
 		});
-		st.selectedSingle = -2; // sentinel: "answered via type-something"
+		st.selectedSingle = -1; // clear any prior option pick — answer is now custom
 		st.inputMode = false;
 		if (tabIndex === this.currentTab) {
 			this.advanceAfterAnswer();
 		}
 	}
 
-	/** Save the review-screen note: trim, store, return to review. Empty = no note. */
+	/** Save the review-tab note: trim, store, return to the review tab.
+	 *  currentTab already points at the review tab (note editing is only
+	 *  entered from there), so we just clear the editing flag. Empty = no note. */
 	private handleMessageSubmit(value: string): void {
 		this.messageText = value.trim();
 		this.messageEditing = false;
-		this.reviewMode = true;
 		this.invalidate();
 	}
 
@@ -370,21 +423,35 @@ class AskUserPanel implements Component, Focusable {
 			.map((i) => opts[i])
 			.filter((o): o is RenderOption => !!o && !o.isOther);
 		const labels = picked.map((o) => o.label);
-		const hasCustom = !!st.customText;
-		if (hasCustom && st.customText) labels.push(st.customText);
-		if (labels.length === 0) return false;
-		this.answers.set(q.tab, {
+		const customText = st.customText;
+		// Empty commit = no option picks AND no custom text. (A skippable
+		// multi-select still records an explicit empty answer via the Enter
+		// path — see handleInput — so this function returning false just means
+		// "nothing to record here".)
+		if (labels.length === 0 && !customText) return false;
+		const ans: Answer = {
 			tab: q.tab,
-			answerLabel: "",
-			answerLabels: labels,
-			wasCustom: hasCustom,
-			multiSelect: true,
-		});
+			kind: "multi",
+			options: labels,
+		};
+		if (customText) ans.custom = customText;
+		this.answers.set(q.tab, ans);
 		return true;
 	}
 
 	// ── accessors ──
 
+	/** Total number of tabs: one per question, plus the trailing review tab. */
+	private get totalTabs(): number {
+		return this.questions.length + 1;
+	}
+
+	/** The review tab sits at index === questions.length (the last tab).
+	 *  While true, the panel renders the review summary instead of a question. */
+	private get isReviewTab(): boolean {
+		return this.currentTab === this.questions.length;
+	}
+
 	private currentQuestion(): Question | undefined {
 		return this.questions[this.currentTab];
 	}
@@ -399,42 +466,47 @@ class AskUserPanel implements Component, Focusable {
 	}
 
 	private advanceAfterAnswer(): void {
-		// If we came from review mode (editing a question), return to review
-		// instead of advancing to the next question.
-		if (this.editingFromReview) {
-			this.editingFromReview = false;
-			this.reviewMode = true;
-			this.reviewScrollOffset = 0;
-			this.invalidate();
-			return;
-		}
-		if (this.currentTab < this.questions.length - 1) {
-			this.switchTab(wrapTab(this.currentTab + 1, this.questions.length));
-			return;
-		}
-		// Last question answered: enter review mode instead of submitting.
-		this.reviewMode = true;
-		this.reviewCursor = 0;
-		this.reviewScrollOffset = 0;
-		this.invalidate();
+		// Advance to the next tab. The review tab is the last tab, so answering
+		// the final question lands the user on the review tab (where Enter
+		// submits). Navigation is now uniform: review is just the next tab,
+		// reached by the same Tab/→ keys as any question — no special "enter
+		// review" step. Safe because this is only called from question tabs
+		// (currentTab < questions.length), so currentTab + 1 <= reviewTabIndex.
+		this.switchTab(this.currentTab + 1);
 	}
 
 	/**
-	 * Called when the user tries to leave the current question without answering.
-	 * - If the question is already answered: return true (leave freely).
-	 * - If unanswered + allowSkip is true: record a skipped answer, return true.
-	 * - If unanswered + allowSkip is false: return false (block navigation).
+	 * Called before navigating AWAY from a question tab (Tab/→/←/Shift+Tab).
+	 * Resolves the current question's state so it can be left cleanly:
+	 *
+	 *  - Already committed (answers.has): leave freely.
+	 *  - Multi-select with UNCOMMITTED checks (or a typed custom text): a check
+	 *    IS an answer — commit it first, then leave. Navigating away with
+	 *    pending checks must submit them (not skip, not block), regardless of
+	 *    allowSkip, because the user has already expressed a choice. (Single-
+	 *    select commits on Space, so it never has pending uncommitted state.)
+	 *  - Nothing selected at all:
+	 *      allowSkip true  → record a skipped answer, allow leaving.
+	 *      allowSkip false → block (a required question must be answered).
+	 *
+	 * Returns true when navigation may proceed.
 	 */
-	private markSkippedIfNeeded(): boolean {
+	private prepareQuestionForLeave(): boolean {
 		const q = this.currentQuestion();
 		if (!q) return true;
 		if (this.answers.has(q.tab)) return true;
-		if (!canSkip(q)) return false; // required question: block
+		const st = this.currentTabState();
+		// Multi-select: uncommitted checks count as an answer — commit them,
+		// then leave. commitMultiAnswer only returns false when there's nothing
+		// to commit (no checks, no custom), which the guard already rules out.
+		if (isMulti(q) && (st.multiChecked.size > 0 || !!st.customText)) {
+			this.commitMultiAnswer(q, st);
+			return true;
+		}
+		if (!canSkip(q)) return false; // required question, nothing chosen: block
 		this.answers.set(q.tab, {
 			tab: q.tab,
-			answerLabel: "",
-			wasCustom: false,
-			skipped: true,
+			kind: "skipped",
 		});
 		return true;
 	}
@@ -453,14 +525,9 @@ class AskUserPanel implements Component, Focusable {
 	private setCollapsed(next: boolean): void {
 		if (this.collapsed === next) return;
 		this.collapsed = next;
-		this.cb.onCollapseChange(next);
 		this.invalidate();
 	}
 
-	expandFromShortcut(): void {
-		this.setCollapsed(false);
-	}
-
 		private clampScrollToCursor(): void {
 		const opts = this.currentOptions();
 		if (opts.length === 0) return;
@@ -474,12 +541,12 @@ class AskUserPanel implements Component, Focusable {
 	// ── input ──
 
 	handleInput(data: string): void {
-		// Note editor active: all keys go to the editor; Esc returns to review.
-		// (Ctrl+\ collapse is intentionally ignored here — note editing is brief.)
+		// 1. Note editor (messageEditing): owns all input while active. Esc
+		//    returns to the review tab (currentTab already points there — note
+		//    editing is only entered from the review tab).
 		if (this.messageEditing) {
 			if (matchesKey(data, Key.escape)) {
 				this.messageEditing = false;
-				this.reviewMode = true;
 				this.invalidate();
 				return;
 			}
@@ -488,82 +555,62 @@ class AskUserPanel implements Component, Focusable {
 			return;
 		}
 
+		// 2. Collapse toggle (global, any tab).
 		if (matchesKey(data, TOGGLE_KEY)) {
 			this.setCollapsed(!this.collapsed);
 			return;
 		}
 
+		// 3. Collapsed: only Esc (cancel) is meaningful.
 		if (this.collapsed) {
 			if (matchesKey(data, Key.escape)) this.submit(true);
 			return;
 		}
 
-		// ── Review mode: list all answers, Enter submits, Tab/↑↓ jump to a question ──
-		if (this.reviewMode) {
-			return this.handleReviewInput(data);
-		}
-
-		const st = this.currentTabState();
-
-		// "Type something." input mode: ALL editing keys (Tab, arrows, etc.) go to
-		// the editor. Only Esc (exit) is handled here. Tab is NOT hijacked for
-		// question switching — that would break indentation / cursor movement.
-		// To switch questions, press Esc first to return to the option list.
-		if (st.inputMode) {
+		// 4. Question tab + "Type something." input mode: the editor owns ALL
+		//    editing keys (Tab, arrows, etc.). Tab is NOT hijacked for tab
+		//    switching here, because that would break indentation / cursor
+		//    movement. Esc exits back to the option list. The review tab has no
+		//    input mode (it never edits options), so it skips this branch — the
+		//    `!this.isReviewTab` short-circuit also avoids indexing tabs[] OOB.
+		if (!this.isReviewTab && this.currentTabState().inputMode) {
 			if (matchesKey(data, Key.escape)) {
+				const st = this.currentTabState();
 				st.inputMode = false;
 				// Keep the editor content (per-tab editor preserves it as draft).
 				this.invalidate();
 				return;
 			}
-			st.editor.handleInput(data);
+			this.currentTabState().editor.handleInput(data);
 			this.invalidate();
 			return;
 		}
 
+		// 5. Esc = cancel submission (any tab, when not editing).
 		if (matchesKey(data, Key.escape)) {
 			this.submit(true);
 			return;
 		}
 
+		// 6. Shared tab navigation — Tab/→ forward, Shift+Tab/← backward.
+		//    Runs on BOTH question tabs and the review tab, which is what makes
+		//    the review reachable by the same keys as any question. The skip
+		//    check only applies when LEAVING a question tab (never the review).
+		if (this.handleTabNavigation(data)) return;
+
+		// 7. Review tab: ↑↓ move · Space edit · Enter submit. (Esc + tab
+		//    navigation were already handled above.)
+		if (this.isReviewTab) {
+			return this.handleReviewInput(data);
+		}
+
+		// 8. Question tab: ↑↓ move cursor · Space toggle/commit · Enter confirm.
+		const st = this.currentTabState();
 		const q = this.currentQuestion();
 		if (!q) return;
 		const opts = this.currentOptions();
 		const multi = isMulti(q);
 
-		// Tab navigation — Tab/Shift+Tab CYCLE through questions; arrow keys
-		// ←/→ navigate the same tabs but STOP at the boundary (no wrap).
-		// Cycling arrows was disorienting with many tabs: pressing → on the
-		// last question jumped back to the first, making it easy to lose your
-		// place and submit by accident. Arrows stopping at the edge fixes that
-		// while Tab keeps its familiar cycle for fast traversal.
-		if (this.questions.length > 1) {
-			// Forward (Tab cycles, → stops at the last question)
-			if (matchesKey(data, Key.tab)) {
-				if (!this.markSkippedIfNeeded()) return;
-				this.switchTab(wrapTab(this.currentTab + 1, this.questions.length));
-				return;
-			}
-			if (matchesKey(data, Key.right)) {
-				if (!this.markSkippedIfNeeded()) return;
-				const next = this.currentTab + 1;
-				if (next >= this.questions.length) return; // boundary: stop
-				this.switchTab(next);
-				return;
-			}
-			// Backward (Shift+Tab cycles, ← stops at the first question)
-			if (matchesKey(data, Key.shift("tab"))) {
-				this.switchTab(wrapTab(this.currentTab - 1, this.questions.length));
-				return;
-			}
-			if (matchesKey(data, Key.left)) {
-				const prev = this.currentTab - 1;
-				if (prev < 0) return; // boundary: stop
-				this.switchTab(prev);
-				return;
-			}
-		}
-
 		// Up / Down — moves ONLY the cursor (▸), does not change selection
 		if (matchesKey(data, Key.up)) {
 			if (st.cursor > 0) {
@@ -594,64 +641,84 @@ class AskUserPanel implements Component, Focusable {
 			return;
 		}
 
-		// Multi-select: space toggles the option under the cursor
-		if (multi && matchesKey(data, Key.space)) {
+		// Space — the "interact" key: select (single), toggle (multi), or EDIT
+		// (the "Type something." row). It never advances — that's Enter's job.
+		// This mirrors the review tab (where Space opens an entry for editing),
+		// so "the key that modifies things" is the same on every screen.
+		if (matchesKey(data, Key.space)) {
 			const opt = opts[st.cursor];
-			if (opt && !opt.isOther) {
-				if (st.multiChecked.has(st.cursor)) st.multiChecked.delete(st.cursor);
-				else st.multiChecked.add(st.cursor);
+			if (!opt) return;
+			if (opt.isOther) {
+				// Enter edit mode for a custom answer. Prefill with any committed
+				// custom text so the user edits rather than retypes. Per-tab
+				// editor keeps the text for Esc-discard semantics automatically.
+				//   - Single-select: custom text lives in the `custom` answer.
+				//   - Multi-select:  it lives in st.customText (kept alongside checks).
+				st.inputMode = true;
+				const existing = this.answers.get(q.tab);
+				const prefill = multi ? st.customText : existing?.kind === "custom" ? existing.text : null;
+				if (prefill) st.editor.setText(prefill);
 				this.invalidate();
+				return;
 			}
-			return;
-		}
-
-		// Single-select: space commits the selection WITHOUT advancing (stay on question)
-		if (!multi && matchesKey(data, Key.space)) {
-			const opt = opts[st.cursor];
-			if (opt && !opt.isOther) {
-				st.selectedSingle = st.cursor;
-				this.answers.set(q.tab, {
-					tab: q.tab,
-					answerLabel: opt.label,
-					wasCustom: false,
-					index: st.cursor,
-				});
+			if (multi) {
+				if (st.multiChecked.has(st.cursor)) st.multiChecked.delete(st.cursor);
+				else st.multiChecked.add(st.cursor);
 				this.invalidate();
+				return;
 			}
+			// single-select: mark the selection WITHOUT advancing (stay on question)
+			st.selectedSingle = st.cursor;
+			this.answers.set(q.tab, {
+				tab: q.tab,
+				kind: "single",
+				option: opt.label,
+			});
+			this.invalidate();
 			return;
 		}
 
-		// Confirm
+		// Enter — confirm + advance to the next tab. It does NOT enter edit mode
+		// (Space owns that now), keeping the two keys orthogonal: Space modifies,
+		// Enter commits. Single-select commits the cursor position and advances;
+		// multi-select commits the currently checked options as-is and advances
+		// (Space owns checking, so Enter no longer auto-checks the cursor option).
 		if (matchesKey(data, Key.enter)) {
 			const opt = opts[st.cursor];
 			if (!opt) return;
-			if (opt.isOther) {
-				st.inputMode = true;
-				// Prefill the editor with the committed custom text (if any) so the
-				// user can edit rather than retype. Per-tab editor keeps the text
-				// for Esc-discard semantics automatically.
-				//   - Single-select: custom text lives in answers[].answerLabel.
-				//   - Multi-select:  it lives in st.customText (kept alongside checks).
-				const existing = this.answers.get(q.tab);
-				const prefill = multi ? st.customText : existing?.wasCustom ? existing.answerLabel : null;
-				if (prefill) st.editor.setText(prefill);
-				this.invalidate();
+			if (opt.isOther && !multi) {
+				// Single-select isOther: Enter never edits (Space owns that). Only
+				// advance if a custom answer was already committed; otherwise stay.
+				if (this.answers.get(q.tab)?.kind === "custom") {
+					this.advanceAfterAnswer();
+				}
 				return;
 			}
 			if (multi) {
-				if (!st.multiChecked.has(st.cursor)) st.multiChecked.add(st.cursor);
-				// Re-commit merges checks + any previously entered custom text, so
-				// going back to add/remove a check never drops the custom value.
-				if (this.commitMultiAnswer(q, st)) this.advanceAfterAnswer();
+				// Commit the current checks (+ any custom text) and advance. For a
+				// skippable multi-select, committing an EMPTY selection is still a
+				// commit — Enter means "submit (even if empty) and move on", not
+				// "skip" (Tab/arrows do skipping). So we record an explicit empty
+				// answer and advance; a required question (!canSkip) with an empty
+				// selection stays put, since it must have at least one pick.
+				if (this.commitMultiAnswer(q, st)) {
+					this.advanceAfterAnswer();
+				} else if (canSkip(q)) {
+					this.answers.set(q.tab, {
+						tab: q.tab,
+						kind: "multi",
+						options: [],
+					});
+					this.advanceAfterAnswer();
+				}
 				return;
 			}
-			// single-select: commit cursor position as the selection
+			// single-select: commit cursor position as the selection, then advance
 			st.selectedSingle = st.cursor;
 			this.answers.set(q.tab, {
 				tab: q.tab,
-				answerLabel: opt.label,
-				wasCustom: false,
-				index: st.cursor,
+				kind: "single",
+				option: opt.label,
 			});
 			this.advanceAfterAnswer();
 			return;
@@ -666,47 +733,56 @@ class AskUserPanel implements Component, Focusable {
 		this.invalidate();
 	}
 
-	/** Handle input while in review mode.
+	/** Shared tab navigation, invoked from handleInput for BOTH question tabs
+	 *  and the review tab. Returns true when the key was consumed.
+	 *
+	 *  - Tab / →   : forward. Tab WRAPS through every tab (questions → review →
+	 *                first question); → STOPS at the review tab (boundary).
+	 *  - Shift+Tab / ← : backward. Shift+Tab wraps; ← stops at the first
+	 *                question.
+	 *
+	 *  Leaving a question tab may need to commit pending multi-select checks
+	 *  or record a skip (when it's unanswered and required) — that's handled
+	 *  by prepareQuestionForLeave. Leaving the review tab never needs that
+	 *  check (it isn't a question), so →/Tab work freely from review. */
+	private handleTabNavigation(data: string): boolean {
+		if (this.totalTabs <= 1) return false;
+		// Forward
+		if (matchesKey(data, Key.tab)) {
+			if (!this.isReviewTab && !this.prepareQuestionForLeave()) return true; // required: blocked
+			this.switchTab(wrapTab(this.currentTab + 1, this.totalTabs));
+			return true;
+		}
+		if (matchesKey(data, Key.right)) {
+			if (!this.isReviewTab && !this.prepareQuestionForLeave()) return true; // required: blocked
+			if (this.currentTab + 1 >= this.totalTabs) return true; // stop at review
+			this.switchTab(this.currentTab + 1);
+			return true;
+		}
+		// Backward
+		if (matchesKey(data, Key.shift("tab"))) {
+			this.switchTab(wrapTab(this.currentTab - 1, this.totalTabs));
+			return true;
+		}
+		if (matchesKey(data, Key.left)) {
+			if (this.currentTab - 1 < 0) return true; // stop at first question
+			this.switchTab(this.currentTab - 1);
+			return true;
+		}
+		return false;
+	}
+
+	/** Handle input specific to the review tab. Esc and tab navigation
+	 *  (Tab/←/→) are already handled upstream in handleInput, so here we only
+	 *  deal with: ↑↓/PgUp/PgDn (move the review cursor), Space (open the entry
+	 *  under the cursor for editing), and Enter (submit the whole review).
+	 *
 	 *  The review list has N question entries plus one trailing "note to
 	 *  assistant" entry (index N), so the cursor ranges over [0, N]. */
 	private handleReviewInput(data: string): void {
 		const n = this.questions.length;
 		const total = n + 1; // include the note entry
-		if (matchesKey(data, Key.escape)) {
-			this.submit(true);
-			return;
-		}
-		if (matchesKey(data, Key.enter)) {
-			// Enter ALWAYS submits the whole review, no matter where the cursor
-			// sits. This deliberately differs from the question screens (where
-			// Enter edits/advances): in review, Enter = "I'm done, send it". The
-			// cursor-position-sensitive action here is Tab (edit selected entry).
-			this.submit(false);
-			return;
-		}
-		if (matchesKey(data, Key.tab)) {
-			if (this.reviewCursor === n) {
-				// Note entry: open the note editor. Prefill with the committed note
-				// (if any) so the user can tweak rather than retype.
-				this.reviewMode = false;
-				this.messageEditing = true;
-				if (this.messageText) this.messageEditor.setText(this.messageText);
-				this.invalidate();
-				return;
-			}
-			// Jump to the question under the review cursor for editing.
-			// We set currentTab + invalidate directly rather than calling
-			// switchTab(): switchTab early-returns when next === currentTab, which
-			// happens whenever the review cursor sits on the already-active
-			// question (always true for a single-question call). That early return
-			// skipped invalidate(), so the panel kept showing the stale review
-			// render and Tab looked dead until ↑/↓ forced a redraw.
-			this.reviewMode = false;
-			this.editingFromReview = true;
-			this.currentTab = this.reviewCursor;
-			this.invalidate();
-			return;
-		}
+		// ↑/↓/PgUp/PgDn — move the review cursor over [0, total-1]
 		if (matchesKey(data, Key.up)) {
 			if (this.reviewCursor > 0) { this.reviewCursor--; this.invalidate(); }
 			return;
@@ -725,6 +801,29 @@ class AskUserPanel implements Component, Focusable {
 			this.invalidate();
 			return;
 		}
+		// Space — "select" the entry under the cursor: jump into editing it.
+		// (Mirrors the option screens, where Space = select/toggle.)
+		if (matchesKey(data, Key.space)) {
+			if (this.reviewCursor === n) {
+				// Note entry: open the note editor. Prefill with the committed note
+				// (if any) so the user can tweak rather than retype.
+				this.messageEditing = true;
+				if (this.messageText) this.messageEditor.setText(this.messageText);
+				this.invalidate();
+				return;
+			}
+			// Question entry: switch to that question's tab for editing.
+			// switchTab early-returns when next === currentTab, which is fine — that
+			// only happens on a single-question call where we're already on the
+			// question; nothing to redraw.
+			this.switchTab(this.reviewCursor);
+			return;
+		}
+		// Enter — submit the whole review, no matter where the cursor sits.
+		if (matchesKey(data, Key.enter)) {
+			this.submit(false);
+			return;
+		}
 	}
 
 	// ── render ──
@@ -745,19 +844,48 @@ class AskUserPanel implements Component, Focusable {
 
 	private renderCollapsed(width: number): string[] {
 		const th = this.theme;
-		const tabsPart = this.questions
-			.map((q, i) => {
-				const label = q.tab;
-				const done = this.answers.has(q.tab);
-				return th.fg(done ? "success" : "dim", `${label}${done ? "✓" : "○"}`);
-			})
-			.join(th.fg("dim", " "));
+		const qParts = this.questions.map((q, i) => {
+			const done = this.answers.has(q.tab);
+			const active = i === this.currentTab && !this.isReviewTab;
+			const mark = active ? "▸" : done ? "✓" : "○";
+			const color = active ? "accent" : done ? "success" : "dim";
+			return th.fg(color, `${q.tab}${mark}`);
+		});
+		const reviewPart = this.isReviewTab
+			? th.fg("accent", "Review▸")
+			: th.fg("dim", "Review○");
+		const tabsPart = [...qParts, reviewPart].join(th.fg("dim", " "));
 		const inner = `${tabsPart}  ${th.fg("dim", ` ${TOGGLE_HINT} expand `)}${th.fg("dim", " Esc cancel ")}`;
 		const line =
 			th.fg("border", "│") + inner + " ".repeat(Math.max(0, width - 2 - visibleWidth(inner))) + th.fg("border", "│");
 		return [truncateToWidth(line, width)];
 	}
 
+	/** Build the tab-bar content line (without border wrapping). Shared by the
+	 *  question screen and the review screen so the bar is always visible —
+	 *  the review tab is a real tab, so it must highlight when active just like
+	 *  any question. Callers wrap the returned string in their own row() so the
+	 *  border color matches the surrounding screen. */
+	private renderTabBarContent(th: Theme): string {
+		const tabCells = this.questions.map((q, i) => {
+			const active = i === this.currentTab;
+			const ans = this.answers.get(q.tab);
+			let mark = " ";
+			let baseColor: import("@earendil-works/pi-coding-agent").ThemeColor = active ? "accent" : "muted";
+			if (ans?.kind === "skipped") { mark = "—"; baseColor = "warning"; }
+			else if (ans) { mark = "✓"; baseColor = "success"; }
+			else if (active) mark = "▸";
+			const color = active ? "accent" : baseColor;
+			return th.fg(color, `${mark} ${q.tab}`);
+		});
+		const reviewActive = this.isReviewTab;
+		const reviewMark = reviewActive ? "▸" : " ";
+		const reviewColor: import("@earendil-works/pi-coding-agent").ThemeColor = reviewActive ? "accent" : "muted";
+		const reviewCell = th.fg(reviewColor, `${reviewMark} [ Review ]`);
+		const sep = th.fg("dim", "  │");
+		return ` ${tabCells.join(th.fg("dim", "  "))}${sep}${reviewCell}`;
+	}
+
 	private renderExpanded(width: number): string[] {
 		const th = this.theme;
 		const innerW = Math.max(20, width - 2);
@@ -767,29 +895,18 @@ class AskUserPanel implements Component, Focusable {
 		if (this.messageEditing) {
 			return this.renderMessageEditor(width, innerW, th);
 		}
-		if (this.reviewMode) {
+		if (this.isReviewTab) {
 			return this.renderReview(width, innerW, th);
 		}
 
 		lines.push(th.fg("border", `╭${"─".repeat(innerW)}╮`));
 
 		// ── Tab bar ──
-		if (this.questions.length > 1) {
-			const tabCells = this.questions.map((q, i) => {
-				const label = q.tab;
-				const active = i === this.currentTab;
-				const ans = this.answers.get(q.tab);
-				let mark = " ";
-				let baseColor: import("@earendil-works/pi-coding-agent").ThemeColor = active ? "accent" : "muted";
-				if (ans?.skipped) { mark = "—"; baseColor = "warning"; }
-				else if (ans) { mark = "✓"; baseColor = "success"; }
-				else if (active) mark = "▸";
-				const color = active ? "accent" : baseColor;
-				return th.fg(color, `${mark} ${label}`);
-			});
-			lines.push(row(` ${tabCells.join(th.fg("dim", "  "))}`));
-			lines.push(row(""));
-		}
+		// Always shown: there is always at least one question tab plus the
+		// trailing review tab. renderTabBarContent is shared with the review
+		// screen so the active tab stays visible across every screen.
+		lines.push(row(this.renderTabBarContent(th)));
+		lines.push(row(""));
 
 		// ── Question header ──
 		const q = this.currentQuestion();
@@ -830,7 +947,7 @@ class AskUserPanel implements Component, Focusable {
 			this.questions.length > 1 ? th.fg("dim", ` ${doneCount}/${this.questions.length} answered · `) : th.fg("dim", " ");
 		const hint = multi
 			? `${TOGGLE_HINT} collapse · ↑↓ move · Space toggle · Enter confirm · Esc cancel`
-			: `${TOGGLE_HINT} collapse · ↑↓ move · Enter confirm · Esc cancel`;
+			: `${TOGGLE_HINT} collapse · ↑↓ move · Space select · Enter confirm · Esc cancel`;
 		lines.push(row(`${left}${th.fg("dim", hint)}`));
 		lines.push(th.fg("border", `╰${"─".repeat(innerW)}╯`));
 		return lines;
@@ -853,18 +970,12 @@ class AskUserPanel implements Component, Focusable {
 		return filled ? th.fg("success", ICON_RADIO_FILLED) : th.fg("dim", ICON_RADIO_EMPTY);
 	}
 
-	/** Format an answer for the review summary: comma-joined, truncated with “…” if too long. */
+	/** Format an answer for the review summary. Delegates to describeAnswer
+	 *  (single source of truth), then wraps in the theme color + truncates. */
 	private formatAnswerText(ans: Answer | undefined, maxW: number, th: Theme): string {
-		if (!ans) return th.fg("dim", "(no answer)");
-		if (ans.skipped) return th.fg("warning", "(skipped)");
-		let text: string;
-		if (ans.multiSelect) text = (ans.answerLabels ?? []).join(", ");
-		else text = ans.answerLabel;
-		const vw = visibleWidth(text);
-		if (vw <= maxW) return th.fg("text", text);
-		// truncate: keep prefix, append “…”
-		const cut = truncateToWidth(text, maxW - 1, "");
-		return th.fg("text", cut) + th.fg("dim", "…");
+		const view = describeAnswer(ans);
+		const text = truncForDisplay(view.text, maxW);
+		return th.fg(view.color, text);
 	}
 
 	/** Clamp the review scroll offset so the cursor stays visible. The review
@@ -890,6 +1001,8 @@ class AskUserPanel implements Component, Focusable {
 		const bc: import("@earendil-works/pi-coding-agent").ThemeColor = "success";
 		const row = (content: string) => th.fg(bc, "│") + padRight(content, innerW) + th.fg(bc, "│");
 		lines.push(th.fg(bc, `╭${"─".repeat(innerW)}╮`));
+		lines.push(row(this.renderTabBarContent(th)));
+		lines.push(row(""));
 		lines.push(row(` ${th.fg("accent", th.bold("Review your answers"))}`));
 		lines.push(th.fg(bc, `├${"─".repeat(innerW)}┤`));
 		const n = this.questions.length;
@@ -927,7 +1040,7 @@ class AskUserPanel implements Component, Focusable {
 					const body = vw <= maxW ? msg : `${truncateToWidth(msg, maxW - 1, "")}…`;
 					lines.push(row(`${bodyIndent}${th.fg("text", body)}`));
 				} else {
-					lines.push(row(`${bodyIndent}${th.fg("dim", "(optional — Tab to add a note)")}`));
+					lines.push(row(`${bodyIndent}${th.fg("dim", "(optional — Space to add a note)")}`));
 				}
 				continue;
 			}
@@ -946,12 +1059,12 @@ class AskUserPanel implements Component, Focusable {
 			lines.push(row(th.fg("dim", `${bodyIndent}↑↓/PgUp/PgDn scroll · ${start + 1}-${end}/${total}`)));
 		}
 		lines.push(th.fg(bc, `├${"─".repeat(innerW)}┤`));
-		lines.push(row(th.fg("dim", " ↑↓ navigate · Tab edit · Enter confirm · Esc cancel")));
+		lines.push(row(th.fg("dim", " ↑↓ move · Space edit · Enter confirm · Esc cancel")));
 		lines.push(th.fg(bc, `╰${"─".repeat(innerW)}╯`));
 		return lines;
 	}
 
-	/** Note editor screen: reached from the review's note entry via Tab. Uses
+	/** Note editor screen: reached from the review's note entry via Space. Uses
 	 *  the same success-bordered look as the review screen to signal it's part
 	 *  of the review flow, not a fresh question. */
 	private renderMessageEditor(width: number, innerW: number, th: Theme): string[] {
@@ -984,7 +1097,7 @@ class AskUserPanel implements Component, Focusable {
 			const isCursor = i === st.cursor;
 			const prefix = isCursor ? `${th.fg("accent", ICON_CURSOR)} ` : "  ";
 			const ans = this.answers.get(q.tab);
-			const committedCustom = multi ? st.customText : ans?.wasCustom ? ans.answerLabel : null;
+			const committedCustom = multi ? st.customText : ans?.kind === "custom" ? ans.text : null;
 			const customAnswered = !!committedCustom;
 			const glyph = this.optionGlyph(opt, i, st, multi, th, isCursor, customAnswered);
 			// For "Type something.", show the committed text instead of the placeholder.
@@ -1028,7 +1141,7 @@ class AskUserPanel implements Component, Focusable {
 		// ── build left column lines (options) ──
 		const leftLines: string[] = [];
 		const dualAns = this.answers.get(q.tab);
-		const dualCommittedCustom = multi ? st.customText : dualAns?.wasCustom ? dualAns.answerLabel : null;
+		const dualCommittedCustom = multi ? st.customText : dualAns?.kind === "custom" ? dualAns.text : null;
 		const customAnswered = !!dualCommittedCustom;
 		for (let i = start; i < end; i++) {
 			const opt = opts[i]!;
@@ -1095,24 +1208,155 @@ class AskUserPanel implements Component, Focusable {
 }
 
 // ────────────────────────────────────────────────────────────────────────────
-// Extension entry
+// Result view — static card shown in the message stream after ask_user.
+// Lets the user verify at a glance what they chose. Two states driven by
+// options.expanded: collapsed = one-line summary, expanded = bordered card.
+// Reuses AskUserPanel's visual language (same border glyphs, theme colors,
+// ✓/⊘/○ status icons, ✎ for custom) so it reads as a continuation of the
+// interaction, not a foreign element.
 // ────────────────────────────────────────────────────────────────────────────
 
-export default function askUserExtension(pi: ExtensionAPI) {
-	let activeExpand: (() => void) | null = null;
+class AskUserResultView implements Component {
+	private questions: ReadonlyArray<Pick<Question, "header" | "tab">>;
+	private result: AskUserResult;
+	private theme: Theme;
+	private expanded = false;
+	private cachedWidth?: number;
+	private cachedLines?: string[];
 
-	pi.registerShortcut(TOGGLE_KEY, {
-		description: "Expand the ask-user panel (when collapsed)",
-		handler: () => {
-			activeExpand?.();
-		},
-	});
+	constructor(questions: ReadonlyArray<Pick<Question, "header" | "tab">>, result: AskUserResult, theme: Theme) {
+		this.questions = questions;
+		this.result = result;
+		this.theme = theme;
+	}
 
-	pi.registerTool({
+	setExpanded(expanded: boolean): void {
+		if (this.expanded !== expanded) {
+			this.expanded = expanded;
+			this.cachedWidth = undefined;
+		}
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		this.cachedWidth = width;
+		this.cachedLines = this.expanded ? this.renderCard(width) : this.renderCollapsed(width);
+		return this.cachedLines;
+	}
+
+	/** Overall status → icon, color, and a short status phrase (plain text,
+	 *  no ANSI — callers wrap it in color). */
+	private getStatus(): { icon: string; color: ThemeColor; phrase: string } {
+		const total = this.questions.length;
+		if (this.result.cancelled) {
+			return {
+				icon: "⊘",
+				color: "warning",
+				phrase: `Cancelled · ${this.result.answers.length}/${total} answered`,
+			};
+		}
+		const anySkipped = this.result.answers.some((a) => a.kind === "skipped");
+		return anySkipped
+			? { icon: "○", color: "accent", phrase: "Answers (some skipped)" }
+			: { icon: "✓", color: "success", phrase: "Answers submitted" };
+	}
+
+	/** Format one answer for the card display. Delegates to describeAnswer. */
+	private formatAnswer(ans: Answer | undefined): { text: string; color: ThemeColor } {
+		return describeAnswer(ans);
+	}
+
+	private renderCollapsed(width: number): string[] {
+		const th = this.theme;
+		const { icon, color, phrase } = this.getStatus();
+		const head = `${th.fg(color, icon)} ${th.fg(color, phrase)}`;
+		const sep = th.fg("dim", ": ");
+		const pairs = this.questions.map((q) => {
+			const ans = this.result.answers.find((a) => a.tab === q.tab);
+			return `${q.header}=${this.formatAnswer(ans).text}`;
+		});
+		const body = pairs.join(th.fg("dim", " · "));
+		return [th.fg("dim", truncForDisplay(`${head}${sep}${body}`, width))];
+	}
+
+	private renderCard(width: number): string[] {
+		const th = this.theme;
+		const { icon, color, phrase } = this.getStatus();
+		const lines: string[] = [];
+		// Status line — icon + phrase in the status color. No border, no redundant
+		// "Ask User" title (the tool-execution cell already renders the tool name
+		// as its header above this component).
+		lines.push(`${th.fg(color, icon)} ${th.fg(color, th.bold(phrase))}`);
+		lines.push(""); // blank line separates status from the Q&A list
+
+		// Each question: header on its own row, then one or more answer rows.
+		// Rows are prefixed by a glyph indicating the answer TYPE, not a uniform
+		// marker: option picks get an arrow (›), custom text gets a pencil (✎).
+		// A multi-select with BOTH options and custom renders as TWO rows. Long
+		// content wraps (wrapTextWithAnsi) so nothing is ever truncated/lost.
+		const indent = "    "; // 4-space lead for answer rows
+		const arrow = th.fg("dim", ICON_ANSWER);
+		const pencil = th.fg("dim", ICON_OTHER);
+		const answerRow = (glyph: string, text: string, textColor: ThemeColor) => {
+			const lead = `${indent}${glyph} `;
+			const w = Math.max(8, width - visibleWidth(lead));
+			const wrapped = wrapTextWithAnsi(th.fg(textColor, text), w);
+			const contIndent = " ".repeat(visibleWidth(lead));
+			const out = [`${lead}${wrapped[0]}`];
+			for (let i = 1; i < wrapped.length; i++) out.push(`${contIndent}${wrapped[i]}`);
+			return out;
+		};
+		for (const q of this.questions) {
+			const ans = this.result.answers.find((a) => a.tab === q.tab);
+			lines.push(th.fg("muted", q.header));
+			if (!ans) {
+				lines.push(`${indent}${th.fg("dim", "(no answer)")}`);
+			} else if (ans.kind === "skipped") {
+				lines.push(`${indent}${th.fg("warning", "(skipped)")}`);
+			} else if (ans.kind === "single") {
+				lines.push(...answerRow(arrow, ans.option, "text"));
+			} else if (ans.kind === "custom") {
+				lines.push(...answerRow(pencil, ans.text, "text"));
+			} else if (ans.kind === "multi") {
+				if (ans.options.length === 0 && !ans.custom) {
+					lines.push(`${indent}${th.fg("dim", "(none)")}`);
+				} else {
+					// Options row (arrow) + optional custom row (pencil) — two rows.
+					if (ans.options.length > 0) lines.push(...answerRow(arrow, ans.options.join(", "), "text"));
+					if (ans.custom) lines.push(...answerRow(pencil, ans.custom, "text"));
+				}
+			}
+		}
+
+		// Note — separated by a blank line, no border, no indent. A speech-bubble
+		// glyph marks it as a free-form message, distinct from the Q&A answers.
+		if (this.result.message) {
+			lines.push("");
+			const prefix = th.fg("accent", ICON_NOTE);
+			const noteW = Math.max(8, width - visibleWidth(prefix) - 1);
+			const wrapped = wrapTextWithAnsi(this.result.message, noteW);
+			lines.push(`${prefix} ${wrapped[0]}`);
+			for (let i = 1; i < wrapped.length; i++) lines.push(wrapped[i]);
+		}
+		return lines;
+	}
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Extension entry
+// ────────────────────────────────────────────────────────────────────────────
+
+export default function askUserExtension(pi: ExtensionAPI) {
+	pi.registerTool<typeof AskUserParams, AskUserResult>({
 		name: "ask_user",
 		label: "Ask User",
 		description:
-			"Ask the user one or more questions with options. Supports single-select (◎→◉) and multi-select (□→▣, space toggles). Every question always includes a 'Type something.' row so the user can type a custom answer whenever none of the provided options fit — this is built in and cannot be disabled, so never assume the user is restricted to your listed options. The custom-input draft is preserved across tab switches, and a focused side panel shows extended detail (ASCII layouts, code, reasoning) when an option carries a `preview` field. Each option needs a short `label` + a `description` (shown beneath it); add a `preview` field only when a description can't fully convey the option. The panel is collapsible (Ctrl+\\). Use for clarifying requirements, getting preferences, or confirming decisions. Avoid using this to pick one item from a long list you just enumerated (e.g. \"which of these 8 fixes should I start with?\"): options are capped at a handful for a reason, and if the choice isn't a real either/or, present the list in a normal message and let the user reply freely, or just proceed with the highest-priority item — reserve ask_user for genuine decisions with a few distinct, mutually-exclusive paths. All displayed user-facing text should use the conversation's language. The result may carry an optional `message` — a free-form note the user can attach on the review screen (about overall direction, pacing, or anything beyond the specific questions). It is user-provided and out-of-band: you cannot set it via the parameters, and it may be absent; when present, treat it as high-priority context that can override or reframe the answers above it.",
+			"Ask the user one or more questions with options. Supports single-select (◎→◉) and multi-select (□→▣, space toggles). Every question always includes a 'Type something.' row so the user can type a custom answer whenever none of the provided options fit — this is built in and cannot be disabled, so never assume the user is restricted to your listed options. The custom-input draft is preserved across tab switches, and a focused side panel shows extended detail (ASCII layouts, code, reasoning) when an option carries a `preview` field. Each option needs a short `label` + a `description` (shown beneath it); add a `preview` field only when a description can't fully convey the option. The panel is collapsible (Ctrl+\\). Use for clarifying requirements, getting preferences, or confirming decisions. Avoid using this to pick one item from a long list you just enumerated (e.g. \"which of these 8 fixes should I start with?\"): options are capped at a handful for a reason, and if the choice isn't a real either/or, present the list in a normal message and let the user reply freely, or just proceed with the highest-priority item — reserve ask_user for genuine decisions with a few distinct, mutually-exclusive paths. All displayed user-facing text should use the conversation's language. The result is returned as JSON: `{ \"cancelled\": bool, \"answers\": [{ \"tab\": <the question's tab>, ... }], \"message\"?: string }`. Each answer echoes the question's `tab` so you can correlate by key. Per answer only the relevant fields appear: single-select option pick → `answer`; single-select custom text → `custom`; multi-select option picks → `answers: [...]`; multi-select with custom → `answers` + `custom`; multi-select empty commit (skippable, submitted with nothing) → `answers: []`; Tab-skipped → `skipped: true`. `custom` is a sibling of `answer`/`answers`, never mixed in — it signals the user typed something outside the offered options. The optional top-level `message` is a free-form note the user can attach on the review screen (about overall direction, pacing, or anything beyond the specific questions); it is user-provided and out-of-band: you cannot set it via the parameters, and it may be absent; when present, treat it as high-priority context that can override or reframe the answers above it.",
 		parameters: AskUserParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -1128,61 +1372,84 @@ export default function askUserExtension(pi: ExtensionAPI) {
 				options: q.options.map((o) => ({ ...o })),
 			}));
 
-			let overlayHandle: { focus: () => void; unfocus: () => void } | null = null;
-			let panel: AskUserPanel | null = null;
-
 			const result = await ctx.ui.custom<AskUserResult>((tui, theme, _kb, done) => {
-				panel = new AskUserPanel(questions, tui, theme, {
+				return new AskUserPanel(questions, tui, theme, {
 					onResult: (r) => done(r),
-					onCollapseChange: (collapsed) => {
-						if (collapsed) {
-							overlayHandle?.unfocus();
-							activeExpand = () => {
-								if (!panel) return;
-								panel.expandFromShortcut();
-								overlayHandle?.focus();
-							};
-						} else {
-							activeExpand = null;
-							overlayHandle?.focus();
-						}
-					},
 				});
-				return panel;
 			}, {
-				overlay: true,
-				overlayOptions: {
-					anchor: "bottom-center",
-					width: "100%",
-					margin: { bottom: 0 },
-				},
-				onHandle: (handle) => {
-					overlayHandle = handle;
-					handle.focus();
-				},
+				// overlay:false renders the panel into pi's bottom editorContainer slot
+				// (the same path ctx.ui.select()/input() take) instead of compositing a
+				// screen overlay over everything. The chat transcript stays visible above
+				// the panel and is scrollable via the terminal's native scrollback. See
+				// "Layout" note at the top of this file for why overlay:true breaks
+				// transcript scrolling.
+				overlay: false,
 			});
 
-			activeExpand = null;
-
-			const summary = result.cancelled
-				? `User cancelled the question(s). ${result.answers.length} question(s) were answered before cancellation.`
-				: result.answers
-						.map((a) => {
-							if (a.skipped) return `${a.tab}: (skipped)`;
-							if (a.multiSelect) return `${a.tab}: ${a.answerLabels?.join(", ") ?? ""}`;
-							return `${a.tab}: ${a.wasCustom ? "(custom) " : ""}${a.answerLabel}`;
-						})
-						.join("\n");
-			// Attach the user's free-form note only when present. When empty, say
-			// nothing — "user left no note" is noise the LLM doesn't need.
-			const withNote = result.message
-				? `${summary}\n\nNote from user:\n${result.message}`
-				: summary;
+			// ── Build the JSON payload returned to the LLM ──
+			//
+			// Structure is intentionally SYMMETRIC with the questions schema the LLM
+			// authored (AskUserParams): each question carries a `tab` as its identity
+			// key, and each answer echoes that same `tab`, so the LLM can correlate
+			// answers back to its own questions by key with zero parsing effort. This
+			// replaces the old `tab: answer` text format, which broke when a custom
+			// answer contained a colon or newline (it could overwrite or collide with
+			// adjacent lines).
+			//
+			// Field shape (only relevant fields are emitted — no noise):
+			//   single-select, option picked : { tab, answer }
+			//   single-select, custom typed  : { tab, custom }   // custom NOT in answer
+			//   multi-select, options picked : { tab, answers: [...] }
+			//   multi-select, options+custom : { tab, answers: [...], custom }
+			//   multi-select, custom only    : { tab, custom }
+			//   multi-select, empty commit   : { tab, answers: [] }   // NOT skipped
+			//   any question, Tab-skipped    : { tab, skipped: true }
+			//
+			// `custom` gets its own key (rather than being mixed into answer/answers)
+			// so the LLM can tell the user stepped outside the offered options — a
+			// useful signal, not an anti-spoofing measure. The empty-message note is
+			// omitted entirely ("user left no note" is noise the LLM doesn't need).
+			const jsonAnswers = result.answers.map((a): Record<string, unknown> => {
+				const out: Record<string, unknown> = { tab: a.tab };
+				switch (a.kind) {
+					case "skipped":
+						out.skipped = true;
+						break;
+					case "single":
+						out.answer = a.option;
+						break;
+					case "custom":
+						out.custom = a.text;
+						break;
+					case "multi":
+						out.answers = a.options;
+						if (a.custom) out.custom = a.custom;
+						break;
+				}
+				return out;
+			});
+			const payload: Record<string, unknown> = {
+				cancelled: result.cancelled,
+				answers: jsonAnswers,
+			};
+			if (result.message) payload.message = result.message;
 
 			return {
-				content: [{ type: "text", text: withNote }],
+				content: [{ type: "text", text: JSON.stringify(payload) }],
 				details: result,
 			};
 		},
+		renderResult(result, options, theme, context) {
+			// context.args.questions is the schema-static type; AskUserResultView
+			// only needs header+tab, so the structural subtype is compatible.
+			const questions = context.args?.questions ?? [];
+			const details = result.details ?? { questions: [], answers: [], cancelled: true };
+			const comp =
+				context.lastComponent instanceof AskUserResultView
+					? context.lastComponent
+					: new AskUserResultView(questions, details, theme);
+			comp.setExpanded(options.expanded);
+			return comp;
+		},
 	});
 }