@d3ara1n/pi-ask-user 0.1.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @d3ara1n/pi-ask-user
 
-A collapsible **ask-user** tool for [pi](https://github.com/earendil-works/pi-mono).
+A collapsible **ask-user** tool for [pi](https://github.com/earendil-works/pi).
 
 ## Why
 
@@ -30,10 +30,11 @@ This tool fixes that:
   "questions": [
     {
       "header": "Which layout?",
+      "tab": "layout",
       "prompt": "Pick the layout for the new settings page.",
       "options": [
-        { "value": "sidebar", "label": "Sidebar", "description": "Nav on the left…" },
-        { "value": "tabs", "label": "Tabs", "description": "Top tabs…" }
+        { "label": "Sidebar", "description": "Nav on the left…" },
+        { "label": "Tabs", "description": "Top tabs…" }
       ]
     }
   ]
@@ -47,11 +48,9 @@ This tool fixes that:
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `header` | string | yes | Short title shown in the panel header |
+| `tab` | string | yes | Short keyword identifying this question. Shown on the tab bar when there are multiple questions, and returned in the result as the answer's prefix. Write it in the user's language, not as a programmatic identifier. Must be unique across all questions in one call |
 | `options` | array | yes | 2–4 options |
-| `id` | string | no | Unique id. Defaults to `q1`, `q2`, … |
-| `label` | string | no | Tab label (multi-question). Defaults to `Q1`, … |
 | `prompt` | string | no | Longer body text under the header |
-| `allowOther` | boolean | no | Allow "Type something." custom input. Default `true` |
 | `multiSelect` | boolean | no | Check multiple options. Default `false` |
 | `allowSkip` | boolean | no | If `false`, the user MUST answer before proceeding. Default `true` |
 
@@ -60,9 +59,8 @@ This tool fixes that:
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `label` | string | yes | Display label |
-| `value` | string | no | Returned value. Defaults to `label` if omitted |
-| `description` | string | no | Explanation under the label (wraps). For ASCII diagrams/code use `preview` |
-| `preview` | string | no | Rich preview shown in a right-hand column when focused. Triggers two-column layout if any option has it |
+| `description` | string | no | Short explanation under the label (wraps). Add one when the label alone isn't self-explanatory |
+| `preview` | string | no | Use when `description` (a short one-liner) isn't enough and the user genuinely benefits from more detail in a side column — ASCII layout demo, code skeleton, Pro/Cons breakdown, or the reasoning behind the option and what choosing it entails. Rendered verbatim. Don't treat it as extra text capacity — every line competes for the user's attention. If a short `description` already conveys the option, leave empty. Most options need only `description` |
 
 ### Icons
 
@@ -84,8 +82,9 @@ Moving `↑`/`↓` only moves the cursor; selection is committed separately.
 
 ### Custom input ("Type something.")
 
-When `allowOther` is `true` (default), a "Type something." row appears. Press
-`Enter` on it to open a text editor:
+Every question always shows a "Type something." row (this cannot be turned off),
+so the user is never locked into the provided options. Press `Enter` on it to
+open a text editor:
 
 - After submitting, the row displays the committed text with a filled glyph
   (`◉ ✎ your text`).
@@ -94,33 +93,45 @@ When `allowOther` is `true` (default), a "Type something." row appears. Press
 - `Esc` discards the edit (the original answer is kept); `Enter` confirms the
   change (the answer is updated).
 
+**Multi-select + custom input.** In `multiSelect` mode the custom text is an
+*extra* entry kept alongside the checked options — it never overwrites them.
+You can check several options, then open "Type something.", type a value, and
+submit: both the checks and the custom text are preserved and returned
+together. The same holds in reverse — edit the question later from the review
+screen to add or remove checks and the committed custom text stays intact
+(and vice versa). Submitting an empty custom value clears only the custom
+entry; any remaining checks are kept.
+
 ### Required questions
 
 Set `allowSkip: false` to force an answer. The user cannot advance forward
-(`Tab`/`→`) until they answer. Backward navigation (`Shift+Tab`/`←`) is always
-allowed so they can review/edit earlier questions.
+(`Tab`/`→`) until they answer; the built-in "Type something." row always lets
+them supply a custom answer, so they're never trapped by options they dislike.
+Backward navigation (`Shift+Tab`/`←`) is always allowed so they can review/edit
+earlier questions.
 
 ### Rich previews
 
-If **any** option of a question carries a `preview` field, that question
-renders in **two columns**: option list on the left, the focused option's
-preview on the right. Moving the cursor updates the right pane. Ideal for
-comparing ASCII layouts / code samples:
+`description` is the default way to explain an option; reserve `preview` for
+the rare case where a description can't fully convey it. If **any** option of
+a question carries a `preview` field, that question renders in **two columns**:
+option list on the left, the focused option's preview on the right. Moving the
+cursor updates the right pane. Ideal for comparing ASCII layouts / code samples:
 
 ```jsonc
 {
-  "id": "layout",
   "header": "Which layout?",
+  "tab": "layout",
   "options": [
     {
       "label": "Sidebar",
-      "value": "sidebar",
-      "preview": "┌──┬────────┐\n│导│  正文  │\n│航│        │\n└──┴────────┘\n左侧固定导航"
+      "description": "Left-side navigation with the main content to its right.",
+      "preview": "┌──┬────────┐\n│NA│  body  │\n│V │        │\n└──┴────────┘\nleft sidebar nav"
     },
     {
       "label": "Top bar",
-      "value": "topbar",
-      "preview": "┌──────────────┐\n│    导航条    │\n├──────────────┤\n│     正文     │\n└──────────────┘\n顶部横向导航"
+      "description": "Top horizontal nav with the main content below.",
+      "preview": "┌──────────────┐\n│    nav bar   │\n├──────────────┤\n│     body     │\n└──────────────┘\ntop horizontal nav"
     }
   ]
 }
@@ -133,17 +144,61 @@ contains a newline renders verbatim as a fixed-width block.
 
 After the last question is answered, a **review screen** lists every question
 and its answer (multi-select answers are comma-joined and truncated with `…`
-when too long; skipped questions show `(skipped)`):
+when too long; skipped questions show `(skipped)`). Each question entry spans
+two rows (header + answer), followed by a trailing **note entry**:
+
+```
+▸ 1. Which layout?
+       Sidebar
+  2. Which database?
+       Postgres
+
+  ✎  Note to assistant
+       (optional — Tab to add a note)
+```
 
-- `↑`/`↓` — move the cursor between questions
-- `Tab` — jump to the focused question to edit it (returns to the review after)
-- `Enter` — confirm and submit all answers
+Each title carries a fixed-width marker (`1.`/`2.`… for questions, `✎ ` for
+the note) so every title aligns; the body is indented one level deeper to keep
+header vs content visually distinct. An empty line sets the note apart from
+the Q&A list above it.
+
+Each title carries a fixed-width marker (`1.`/`2.`… for questions, `✎ ` for
+the note) so every title aligns; the body is indented one level deeper to keep
+header vs content visually distinct.
+
+- `↑`/`↓` — move the cursor between entries (questions + the note)
+- `PgUp`/`PgDn` — scroll by page (when there are more entries than rows)
+- `Tab` — edit the focused entry: a question (returns to review after) or the
+  note (opens a free-form editor)
+- `Enter` — confirm and submit all answers. `Enter` is always "submit" on the
+  review screen, never "edit" — this deliberately differs from the question
+  screens (where `Enter` edits/advances) so you can never submit by
+  double-tapping `Enter` while trying to edit something. Use `Tab` to edit.
 - `Esc` — cancel
 
+### Note to assistant
+
+The review screen ends with a **note** entry — a free-form message the user
+can attach for the assistant, about anything *beyond* the specific questions
+(overall direction, pacing, priorities, a correction to the premise, …).
+
+- Move the cursor to the note row and press `Tab` to open the editor.
+- `Enter` saves the note (empty = no note); `Esc` returns to the review without
+  saving (the in-progress draft is kept).
+- The note is **out-of-band**: it is not part of `questions`/`options` and the
+  assistant cannot request or pre-fill it. It surfaces only in the tool result
+  as `message`, and only when non-empty.
+
+Because the note can reframe or override the answers, the assistant is told to
+treat it as high-priority context.
+
 ### Result
 
-The tool returns a summary plus structured `answers`. If the user cancelled
-mid-way, the message notes how many questions were answered before cancellation.
+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.
 
 ## Keys
 
@@ -152,8 +207,8 @@ mid-way, the message notes how many questions were answered before cancellation.
 | `↑` `↓` / `PgUp` `PgDn` | Move cursor / scroll options |
 | `Space` | Commit selection (single: select-only; multi: toggle) |
 | `Enter` | Confirm & advance (single) / commit checked (multi) / enter custom input |
-| `Tab` / `Shift+Tab` | Next / previous question (option list only — not hijacked inside the editor) |
-| `→` / `←` | Same as `Tab` / `Shift+Tab` |
+| `Tab` / `Shift+Tab` | Next / previous question, **cycling** (last → first). Option list only — not hijacked inside the editor |
+| `→` / `←` | Next / previous question, but **stop at the boundary** (no cycle) — safer than Tab when there are many questions |
 | `Esc` | Cancel (or exit custom-input editor without saving) |
 | `Ctrl+\` | Collapse / expand the panel |
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@d3ara1n/pi-ask-user",
-  "version": "0.1.0",
+  "version": "2.0.0",
+  "type": "module",
   "description": "Ask-user tool for pi — collapsible question overlay that releases focus so you can scroll the transcript while deciding",
   "main": "src/index.ts",
   "keywords": [

package/src/index.ts

@@ -50,7 +50,6 @@ const ICON_CURSOR = "▸"; // current cursor position, independent of selection
 // ────────────────────────────────────────────────────────────────────────────
 
 interface QuestionOption {
-	value: string;
 	label: string;
 	description?: string;
 	/** Rich preview shown in the right column when this option is focused. */
@@ -62,26 +61,20 @@ interface RenderOption extends QuestionOption {
 }
 
 interface Question {
-	id: string;
-	label?: string;
+	tab: string;
 	header: string;
 	prompt?: string;
 	options: QuestionOption[];
-	allowOther?: boolean;
 	multiSelect?: boolean;
 	allowSkip?: boolean;
 }
 
 interface Answer {
-	id: string;
-	/** Single-select: the chosen value. Multi-select: empty string. */
-	value: string;
-	/** Multi-select: the chosen values. Single-select: absent. */
-	values?: string[];
-	/** Single-select label. */
-	label: string;
-	/** Multi-select labels. */
-	labels?: string[];
+	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. */
@@ -94,6 +87,8 @@ interface AskUserResult {
 	questions: Question[];
 	answers: Answer[];
 	cancelled: boolean;
+	/** Free-form note the user can attach on the review screen. Absent when empty. */
+	message?: string;
 }
 
 /** Per-tab ephemeral UI state. Preserved across tab switches. */
@@ -108,6 +103,8 @@ interface TabState {
 	editor: Editor;
 	/** Indices of committed options (multi-select). */
 	multiChecked: Set<number>;
+	/** Committed custom text for multi-select mode (kept alongside multiChecked, never overwriting it). Null if none. */
+	customText: string | null;
 	/** Committed single-select index (or -1 if none yet, -2 = answered via type-something). */
 	selectedSingle: number;
 }
@@ -117,49 +114,32 @@ interface TabState {
 // ────────────────────────────────────────────────────────────────────────────
 
 const QuestionOptionSchema = Type.Object({
-	value: Type.Optional(
-		Type.String({
-			description: "Value returned when this option is chosen. Defaults to `label` if omitted.",
-		}),
-	),
 	label: Type.String({ description: "Short display label for the option (shown on the selection row)" }),
 	description: Type.Optional(
 		Type.String({
-			description:
-				"Optional short explanation shown under the label (wraps). For ASCII diagrams/code use `preview`.",
+			description: "Short explanation shown under the label (wraps). Add one when the label alone isn't self-explanatory.",
 		}),
 	),
 	preview: Type.Optional(
 		Type.String({
 			description:
-				"Optional rich preview (ASCII diagram, code sample, etc.) shown in a dedicated right-hand column when this option is focused. Triggers two-column layout for the whole question if any option has it.",
+			"Use this when `description` (a short one-liner) is not enough and the user genuinely benefits from seeing more detail in a side column — e.g. an ASCII layout demo, a code skeleton, a Pro/Cons breakdown, or the reasoning behind why this option is offered and what choosing it entails. Rendered verbatim in a side column (spaces/newlines preserved). Do NOT treat preview as extra text capacity. Every line competes for the user's attention against the option list; only add a preview when the content is worth reading, not just because there's room for more words. If a short `description` already conveys the option, leave preview empty. Most options need only `description`.",
 		}),
 	),
 });
 
 const QuestionSchema = Type.Object({
-	id: Type.Optional(
-		Type.String({
-			description: "Unique identifier for this question. Defaults to `q1`, `q2`, ... if omitted.",
-		}),
-	),
 	header: Type.String({
 		description: "Short question title shown in the panel header, e.g. 'Which layout?'",
 	}),
-	label: Type.Optional(
-		Type.String({
-			description: "Short tab label for multi-question mode (defaults to Q1, Q2, ...)",
-		}),
-	),
+	tab: Type.String({
+		description: "Short keyword that identifies this question. Shown on the tab bar when there are multiple questions, and returned in the result as the answer's prefix. Write it in the user's language (e.g. \"数据库\" or \"布局\" in a Chinese conversation, \"Database\" or \"Layout\" in English), not as a programmatic identifier like \"db_choice\". Must be unique across questions in one call." }),
 	prompt: Type.Optional(
 		Type.String({ description: "Optional longer body text shown under the header" }),
 	),
 	options: Type.Array(QuestionOptionSchema, {
-		description: "Available options. Pass 2-4; each may carry a description and/or preview.",
+		description: "Available options. Pass 2-4; each needs a short `label` + a `description`, and a `preview` only when a description can't fully convey the option.",
 	}),
-	allowOther: Type.Optional(
-		Type.Boolean({ description: "Allow a 'Type something.' custom-input option (default: true)" }),
-	),
 	multiSelect: Type.Optional(
 		Type.Boolean({
 			description:
@@ -199,12 +179,10 @@ function wrapTab(index: number, total: number): number {
 	return ((index % total) + total) % total;
 }
 
-/** Build the full option list for a question, appending "Type something." if allowed. */
+/** Build the full option list for a question, always appending the "Type something." custom-input row. */
 function buildOptions(q: Question): RenderOption[] {
 	const opts: RenderOption[] = [...q.options];
-	if (q.allowOther !== false) {
-		opts.push({ value: "__other__", label: "Type something.", isOther: true });
-	}
+	opts.push({ label: "Type something.", isOther: true });
 	return opts;
 }
 
@@ -226,7 +204,7 @@ function isDualColumn(q: Question | undefined): boolean {
 function newTabState(tui: TuiLike, theme: EditorTheme, tabIndex: number, onSubmit: (tabIndex: number, value: string) => void): TabState {
 	const editor = new Editor(tui as never, theme);
 	editor.onSubmit = (value) => onSubmit(tabIndex, value);
-	return { cursor: 0, scrollOffset: 0, inputMode: false, editor, multiChecked: new Set(), selectedSingle: -1 };
+	return { cursor: 0, scrollOffset: 0, inputMode: false, editor, multiChecked: new Set(), customText: null, selectedSingle: -1 };
 }
 
 function errorResult(message: string, questions: Question[] = []): {
@@ -277,9 +255,22 @@ class AskUserPanel implements Component, Focusable {
 	private reviewMode = false;
 	/** Cursor row in the review summary. */
 	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. */
+	private messageEditing = false;
+	/** Committed note text (trimmed). Empty string = no note. Lives only on the
+	 *  review screen; the LLM cannot set it. */
+	private messageText = "";
+	/** Dedicated editor for the note. Single-line semantics: Enter saves (like
+	 *  the per-question "Type something." editor). */
+	private messageEditor: Editor;
 
 	// ── render cache ──
 	private cachedWidth?: number;
@@ -306,6 +297,11 @@ class AskUserPanel implements Component, Focusable {
 		// draft-loss bug (previously a single shared editor was swapped in/out and
 		// the swap was lossy across the input-mode / tab-switch boundary).
 		this.tabs = questions.map((_, i) => newTabState(tui, editorTheme, i, (ti, v) => this.handleSubmit(ti, v)));
+		// Dedicated editor for the review-screen note. Enter saves (single-line),
+		// Esc returns to the review without saving — mirroring the per-question
+		// "Type something." editor's semantics.
+		this.messageEditor = new Editor(tui as never, editorTheme);
+		this.messageEditor.onSubmit = (value) => this.handleMessageSubmit(value);
 	}
 
 	/** Shared submit logic bound to each tab's editor. */
@@ -315,25 +311,78 @@ class AskUserPanel implements Component, Focusable {
 		if (!q || !st) return;
 		const trimmed = value.trim();
 		if (!trimmed) {
-			// empty → back to options, keep nothing
+			// empty → back to options. In multi-select mode, an empty submit also
+			// clears any previously committed custom text (blank = "remove my custom
+			// answer"), then re-commits the remaining checked options.
 			st.inputMode = false;
 			st.editor.setText("");
+			if (isMulti(q)) {
+				st.customText = null;
+				if (!this.commitMultiAnswer(q, st)) this.answers.delete(q.tab);
+			}
+			if (tabIndex === this.currentTab) this.invalidate();
+			return;
+		}
+		if (isMulti(q)) {
+			// Multi-select: the custom text is an extra entry kept ALONGSIDE the
+			// checked options — it must NOT overwrite them. (Previously this path
+			// did answers.set with only the custom text, dropping every check.)
+			// Committing custom text only records it — we return to the OPTION LIST
+			// (not advance) so the user can keep checking options and then press
+			// Enter on an option to confirm the whole question. Advancing here used
+			// to jump straight to review the moment the custom editor closed.
+			st.customText = trimmed;
+			this.commitMultiAnswer(q, st);
+			st.inputMode = false;
 			if (tabIndex === this.currentTab) this.invalidate();
 			return;
 		}
-		this.answers.set(q.id, {
-			id: q.id,
-			value: trimmed,
-			label: trimmed,
+		this.answers.set(q.tab, {
+			tab: q.tab,
+			answerLabel: trimmed,
 			wasCustom: true,
 		});
-		st.inputMode = false;
 		st.selectedSingle = -2; // sentinel: "answered via type-something"
+		st.inputMode = false;
 		if (tabIndex === this.currentTab) {
 			this.advanceAfterAnswer();
 		}
 	}
 
+	/** Save the review-screen note: trim, store, return to review. Empty = no note. */
+	private handleMessageSubmit(value: string): void {
+		this.messageText = value.trim();
+		this.messageEditing = false;
+		this.reviewMode = true;
+		this.invalidate();
+	}
+
+	/**
+	 * Multi-select commit: merge the checked options (st.multiChecked) together
+	 * with the committed custom text (st.customText) into one multi-select
+	 * answer. Returns false when there is nothing to commit (no checks and no
+	 * custom text), so the caller can delete the stale answer if desired.
+	 */
+	private commitMultiAnswer(q: Question, st: TabState): boolean {
+		const opts = buildOptions(q);
+		const picked = Array.from(st.multiChecked)
+			.sort((a, b) => a - b)
+			.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, {
+			tab: q.tab,
+			answerLabel: "",
+			answerLabels: labels,
+			wasCustom: hasCustom,
+			multiSelect: true,
+		});
+		return true;
+	}
+
 	// ── accessors ──
 
 	private currentQuestion(): Question | undefined {
@@ -355,6 +404,7 @@ class AskUserPanel implements Component, Focusable {
 		if (this.editingFromReview) {
 			this.editingFromReview = false;
 			this.reviewMode = true;
+			this.reviewScrollOffset = 0;
 			this.invalidate();
 			return;
 		}
@@ -365,6 +415,7 @@ class AskUserPanel implements Component, Focusable {
 		// Last question answered: enter review mode instead of submitting.
 		this.reviewMode = true;
 		this.reviewCursor = 0;
+		this.reviewScrollOffset = 0;
 		this.invalidate();
 	}
 
@@ -377,12 +428,11 @@ class AskUserPanel implements Component, Focusable {
 	private markSkippedIfNeeded(): boolean {
 		const q = this.currentQuestion();
 		if (!q) return true;
-		if (this.answers.has(q.id)) return true;
+		if (this.answers.has(q.tab)) return true;
 		if (!canSkip(q)) return false; // required question: block
-		this.answers.set(q.id, {
-			id: q.id,
-			value: "",
-			label: "",
+		this.answers.set(q.tab, {
+			tab: q.tab,
+			answerLabel: "",
 			wasCustom: false,
 			skipped: true,
 		});
@@ -394,6 +444,9 @@ class AskUserPanel implements Component, Focusable {
 			questions: this.questions,
 			answers: Array.from(this.answers.values()),
 			cancelled,
+			// Only attach the note when non-empty. A cancelled submit still carries
+			// the note if the user wrote one (it may explain why they cancelled).
+			message: this.messageText || undefined,
 		});
 	}
 
@@ -421,6 +474,20 @@ 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.)
+		if (this.messageEditing) {
+			if (matchesKey(data, Key.escape)) {
+				this.messageEditing = false;
+				this.reviewMode = true;
+				this.invalidate();
+				return;
+			}
+			this.messageEditor.handleInput(data);
+			this.invalidate();
+			return;
+		}
+
 		if (matchesKey(data, TOGGLE_KEY)) {
 			this.setCollapsed(!this.collapsed);
 			return;
@@ -464,22 +531,37 @@ class AskUserPanel implements Component, Focusable {
 		const opts = this.currentOptions();
 		const multi = isMulti(q);
 
-		// Tab navigation
+		// 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) {
-			if (matchesKey(data, Key.tab) || matchesKey(data, Key.right)) {
-				// Forward navigation: a required (allowSkip:false) question cannot be
-				// left unanswered, so block + record-skip is gated on markSkippedIfNeeded.
+			// 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.shift("tab")) || matchesKey(data, Key.left)) {
-				// Backward navigation is always allowed — reviewing/editing earlier
-				// questions doesn't let the user bypass a required question (forward
-				// nav re-checks when they come back forward).
+			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
@@ -528,10 +610,9 @@ class AskUserPanel implements Component, Focusable {
 			const opt = opts[st.cursor];
 			if (opt && !opt.isOther) {
 				st.selectedSingle = st.cursor;
-				this.answers.set(q.id, {
-					id: q.id,
-					value: opt.value,
-					label: opt.label,
+				this.answers.set(q.tab, {
+					tab: q.tab,
+					answerLabel: opt.label,
 					wasCustom: false,
 					index: st.cursor,
 				});
@@ -549,38 +630,26 @@ class AskUserPanel implements Component, Focusable {
 				// 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.
-				const existing = this.answers.get(q.id);
-				if (existing?.wasCustom && existing.value) {
-					st.editor.setText(existing.value);
-				}
+				//   - 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();
 				return;
 			}
 			if (multi) {
 				if (!st.multiChecked.has(st.cursor)) st.multiChecked.add(st.cursor);
-				const picked = Array.from(st.multiChecked)
-					.sort((a, b) => a - b)
-					.map((i) => opts[i])
-					.filter((o): o is RenderOption => !!o && !o.isOther);
-				if (picked.length === 0) return;
-				this.answers.set(q.id, {
-					id: q.id,
-					value: "",
-					values: picked.map((o) => o.value),
-					label: "",
-					labels: picked.map((o) => o.label),
-					wasCustom: false,
-					multiSelect: true,
-				});
-				this.advanceAfterAnswer();
+				// 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();
 				return;
 			}
 			// single-select: commit cursor position as the selection
 			st.selectedSingle = st.cursor;
-			this.answers.set(q.id, {
-				id: q.id,
-				value: opt.value,
-				label: opt.label,
+			this.answers.set(q.tab, {
+				tab: q.tab,
+				answerLabel: opt.label,
 				wasCustom: false,
 				index: st.cursor,
 			});
@@ -597,23 +666,45 @@ class AskUserPanel implements Component, Focusable {
 		this.invalidate();
 	}
 
-	/** Handle input while in review mode. */
+	/** Handle input while in review mode.
+	 *  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)) {
-			// Confirm: submit all answers.
+			// 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.switchTab(this.reviewCursor);
+			this.currentTab = this.reviewCursor;
+			this.invalidate();
 			return;
 		}
 		if (matchesKey(data, Key.up)) {
@@ -621,7 +712,17 @@ class AskUserPanel implements Component, Focusable {
 			return;
 		}
 		if (matchesKey(data, Key.down)) {
-			if (this.reviewCursor < n - 1) { this.reviewCursor++; this.invalidate(); }
+			if (this.reviewCursor < total - 1) { this.reviewCursor++; this.invalidate(); }
+			return;
+		}
+		if (matchesKey(data, Key.pageUp)) {
+			this.reviewCursor = Math.max(0, this.reviewCursor - Math.max(1, this.reviewViewportH));
+			this.invalidate();
+			return;
+		}
+		if (matchesKey(data, Key.pageDown)) {
+			this.reviewCursor = Math.min(total - 1, this.reviewCursor + Math.max(1, this.reviewViewportH));
+			this.invalidate();
 			return;
 		}
 	}
@@ -646,8 +747,8 @@ class AskUserPanel implements Component, Focusable {
 		const th = this.theme;
 		const tabsPart = this.questions
 			.map((q, i) => {
-				const label = q.label || `Q${i + 1}`;
-				const done = this.answers.has(q.id);
+				const label = q.tab;
+				const done = this.answers.has(q.tab);
 				return th.fg(done ? "success" : "dim", `${label}${done ? "✓" : "○"}`);
 			})
 			.join(th.fg("dim", " "));
@@ -663,8 +764,11 @@ class AskUserPanel implements Component, Focusable {
 		const lines: string[] = [];
 		const row = (content: string) => th.fg("border", "│") + padRight(content, innerW) + th.fg("border", "│");
 
+		if (this.messageEditing) {
+			return this.renderMessageEditor(width, innerW, th);
+		}
 		if (this.reviewMode) {
-			return this.renderReview(width, innerW, row, th);
+			return this.renderReview(width, innerW, th);
 		}
 
 		lines.push(th.fg("border", `╭${"─".repeat(innerW)}╮`));
@@ -672,9 +776,9 @@ class AskUserPanel implements Component, Focusable {
 		// ── Tab bar ──
 		if (this.questions.length > 1) {
 			const tabCells = this.questions.map((q, i) => {
-				const label = q.label || `Q${i + 1}`;
+				const label = q.tab;
 				const active = i === this.currentTab;
-				const ans = this.answers.get(q.id);
+				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"; }
@@ -703,8 +807,10 @@ class AskUserPanel implements Component, Focusable {
 		// ── Prompt body ──
 		if (q?.prompt) {
 			for (const w of wrapTextWithAnsi(th.fg("muted", q.prompt), innerW - 2)) lines.push(row(` ${w}`));
-			lines.push(row(""));
 		}
+		// 空行分隔 header/prompt 与 options。原来只在有 prompt 时才加，导致无
+		// prompt 的问题其标题与选项紧贴（"粘在一起"）。现在无条件加。
+		lines.push(row(""));
 
 		// ── Body: options / preview / input editor ──
 		const st = this.currentTabState();
@@ -752,8 +858,8 @@ class AskUserPanel implements Component, Focusable {
 		if (!ans) return th.fg("dim", "(no answer)");
 		if (ans.skipped) return th.fg("warning", "(skipped)");
 		let text: string;
-		if (ans.multiSelect) text = (ans.labels?.length ? ans.labels : ans.values ?? []).join(", ");
-		else text = ans.wasCustom ? ans.value : (ans.label || ans.value);
+		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 “…”
@@ -761,29 +867,104 @@ class AskUserPanel implements Component, Focusable {
 		return th.fg("text", cut) + th.fg("dim", "…");
 	}
 
-	/** Review summary: one row per question showing its answer. */
-	private renderReview(width: number, innerW: number, row: (s: string) => string, th: Theme): string[] {
+	/** Clamp the review scroll offset so the cursor stays visible. The review
+	 *  list has N questions + 1 note entry, so the cursor may equal N. */
+	private clampReviewScroll(): void {
+		const total = this.questions.length + 1;
+		if (total === 0) return;
+		const viewH = this.reviewViewportH;
+		if (this.reviewCursor < this.reviewScrollOffset) this.reviewScrollOffset = this.reviewCursor;
+		else if (this.reviewCursor >= this.reviewScrollOffset + viewH)
+			this.reviewScrollOffset = this.reviewCursor - viewH + 1;
+		if (this.reviewScrollOffset < 0) this.reviewScrollOffset = 0;
+	}
+
+	/** Review summary: one question per entry (header + answer), plus a trailing
+	 *  "note to assistant" entry. Viewport scrolling reuses the option-screen
+	 *  layout primitives. */
+	private renderReview(width: number, innerW: number, th: Theme): string[] {
 		const lines: string[] = [];
-		lines.push(th.fg("border", `╭${"─".repeat(innerW)}╮`));
+		// Review uses a distinct border color (success/green) so it's visually
+		// unmistakable as the review/confirm screen — not another question. The
+		// question screen keeps the default "border" color.
+		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(` ${th.fg("accent", th.bold("Review your answers"))}`));
-		lines.push(th.fg("border", `├${"─".repeat(innerW)}┤`));
+		lines.push(th.fg(bc, `├${"─".repeat(innerW)}┤`));
 		const n = this.questions.length;
-		for (let i = 0; i < n; i++) {
-			const q = this.questions[i]!;
+		const total = n + 1; // +1 for the note entry
+		// Body indent (6 cols): questions and the note carry a 2-visible-col marker
+		// (`1.` / `2.` … or `✎ ` for the note) right after the cursor, plus a
+		// separator space, so every title starts at the same column. The body is
+		// indented one past that so header vs content stay visually distinct —
+		// previously the body sat at 5 cols and the note's icon pushed its title
+		// out of alignment with the question titles.
+		const bodyIndent = "      "; // 6 spaces
+		const maxW = innerW - 2 - bodyIndent.length;
+		this.reviewViewportH = Math.max(3, Math.min(total, 10));
+		this.clampReviewScroll();
+		const start = this.reviewScrollOffset;
+		const end = Math.min(total, start + this.reviewViewportH);
+		for (let i = start; i < end; i++) {
 			const isCursor = i === this.reviewCursor;
-			const ans = this.answers.get(q.id);
 			const prefix = isCursor ? `${th.fg("accent", ICON_CURSOR)} ` : "  ";
-			const header = q.header;
-			const labelW = Math.min(20, innerW - 4);
-			const headerStr = truncateToWidth(header, labelW, "");
-			const headerColor = isCursor ? "accent" : "muted";
-			const ansW = innerW - labelW - 5; // prefix + ": " + answer + padding
-			const ansStr = this.formatAnswerText(ans, Math.max(10, ansW), th);
-			lines.push(row(` ${prefix}${th.fg(headerColor, headerStr)}${th.fg("dim", ": ")}${ansStr}`));
+			const headerColor: import("@earendil-works/pi-coding-agent").ThemeColor = isCursor ? "accent" : "muted";
+			// marker: a fixed 2-visible-col slot + 1 separator space, so every title
+			// (questions + note) aligns regardless of icon width. `1.` is 2 cols;
+			// the note's ✎ is 1 col, padded to `✎ ` (hence one extra space between
+			// ✎ and its title — the deliberate tradeoff of this layout).
+			// ── Note entry (index n): always last, two rows like a question. ──
+			if (i === n) {
+				// 空行分隔：note 是异类条目（附加留言，非问答），用空行和上方
+				// 问答列表隔开。保持简单，不用点线/装饰。
+				lines.push(row(""));
+				const marker = th.fg(headerColor, `${ICON_OTHER} `);
+				lines.push(row(` ${prefix}${marker} ${th.fg(headerColor, "Note to assistant")}`));
+				const msg = this.messageText;
+				if (msg) {
+					const vw = visibleWidth(msg);
+					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)")}`));
+				}
+				continue;
+			}
+			const q = this.questions[i]!;
+			const ans = this.answers.get(q.tab);
+			// Header row: cursor + marker + title.
+			const marker = th.fg(headerColor, `${i + 1}.`);
+			lines.push(row(` ${prefix}${marker} ${th.fg(headerColor, q.header)}`));
+			// Answer row: reuse the description renderer's indent/wrap, fed the
+			// formatted answer text. Skipped/custom/multi-select all flow through
+			// formatAnswerText, so the coloring matches the option screen.
+			const ansText = this.formatAnswerText(ans, maxW, th);
+			lines.push(row(`${bodyIndent}${ansText}`));
 		}
-		lines.push(th.fg("border", `├${"─".repeat(innerW)}┤`));
-		lines.push(row(th.fg("dim", " ↑↓ navigate · Tab edit selected · Enter confirm · Esc cancel")));
-		lines.push(th.fg("border", `╰${"─".repeat(innerW)}╯`));
+		if (total > this.reviewViewportH) {
+			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(th.fg(bc, `╰${"─".repeat(innerW)}╯`));
+		return lines;
+	}
+
+	/** Note editor screen: reached from the review's note entry via Tab. 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[] {
+		const lines: string[] = [];
+		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(` ${th.fg("accent", th.bold(`${ICON_OTHER} Note to assistant`))}`));
+		lines.push(th.fg(bc, `├${"─".repeat(innerW)}┤`));
+		for (const el of this.messageEditor.render(innerW - 2)) lines.push(row(` ${el}`));
+		lines.push(th.fg(bc, `├${"─".repeat(innerW)}┤`));
+		lines.push(row(th.fg("dim", " Esc back to review · Enter save note")));
+		lines.push(th.fg(bc, `╰${"─".repeat(innerW)}╯`));
 		return lines;
 	}
 
@@ -802,10 +983,12 @@ class AskUserPanel implements Component, Focusable {
 			const opt = opts[i]!;
 			const isCursor = i === st.cursor;
 			const prefix = isCursor ? `${th.fg("accent", ICON_CURSOR)} ` : "  ";
-			const customAnswered = !multi && !!this.answers.get(q.id)?.wasCustom;
+			const ans = this.answers.get(q.tab);
+			const committedCustom = multi ? st.customText : ans?.wasCustom ? ans.answerLabel : 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.
-			const displayLabel = opt.isOther && customAnswered ? this.answers.get(q.id)!.value : opt.label;
+			const displayLabel = opt.isOther && customAnswered ? committedCustom! : opt.label;
 			const labelColor = isCursor ? "accent" : opt.isOther ? (customAnswered ? "text" : "dim") : "text";
 			const labelText = th.fg(labelColor, displayLabel);
 			out.push(row(` ${prefix}${glyph} ${labelText}`));
@@ -844,13 +1027,15 @@ class AskUserPanel implements Component, Focusable {
 
 		// ── build left column lines (options) ──
 		const leftLines: string[] = [];
-		const customAnswered = !multi && !!this.answers.get(q.id)?.wasCustom;
+		const dualAns = this.answers.get(q.tab);
+		const dualCommittedCustom = multi ? st.customText : dualAns?.wasCustom ? dualAns.answerLabel : null;
+		const customAnswered = !!dualCommittedCustom;
 		for (let i = start; i < end; i++) {
 			const opt = opts[i]!;
 			const isCursor = i === st.cursor;
 			const prefix = isCursor ? `${th.fg("accent", ICON_CURSOR)} ` : "  ";
 			const glyph = this.optionGlyph(opt, i, st, multi, th, isCursor, customAnswered);
-			const displayLabel = opt.isOther && customAnswered ? this.answers.get(q.id)!.value : opt.label;
+			const displayLabel = opt.isOther && customAnswered ? dualCommittedCustom! : opt.label;
 			const labelColor = isCursor ? "accent" : opt.isOther ? (customAnswered ? "text" : "dim") : "text";
 			const labelLine = `${prefix}${glyph} ${th.fg(labelColor, displayLabel)}`;
 			leftLines.push(truncateToWidth(labelLine, leftW - 1, ""));
@@ -867,11 +1052,6 @@ class AskUserPanel implements Component, Focusable {
 			for (const ln of cursorOpt.preview.split("\n")) {
 				rightLines.push(th.fg("muted", truncateToWidth(ln, rightW - 1, "")));
 			}
-		} else if (cursorOpt?.description) {
-			// Fall back to wrapped description if no preview.
-			for (const ln of wrapTextWithAnsi(th.fg("muted", cursorOpt.description), rightW - 1)) {
-				rightLines.push(ln);
-			}
 		} else {
 			rightLines.push(th.fg("dim", truncateToWidth("(no preview)", rightW - 1, "")));
 		}
@@ -932,7 +1112,7 @@ export default function askUserExtension(pi: ExtensionAPI) {
 		name: "ask_user",
 		label: "Ask User",
 		description:
-			"Ask the user one or more questions with options. Supports single-select (◎→◉) and multi-select (□→▣, space toggles), per-question 'Type something.' custom input with draft preserved across tab switches, and rich per-option previews (ASCII diagrams render verbatim in a side column when any option has a `preview` field). The panel is collapsible (Ctrl+\\). Use for clarifying requirements, getting preferences, or confirming decisions.",
+			"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.",
 		parameters: AskUserParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -943,20 +1123,9 @@ export default function askUserExtension(pi: ExtensionAPI) {
 				return errorResult("Error: No questions provided");
 			}
 
-			// Default id: use `header` when unique, else fall back to `q{n}`.
-			// This keeps the result summary readable for both the LLM and the user
-			// (e.g. "颜色: 红色" instead of "q1: 红色").
-			const headerCounts = new Map<string, number>();
-			for (const q of params.questions) {
-				const h = q.id ? null : (q.header ?? "");
-				if (h) headerCounts.set(h, (headerCounts.get(h) ?? 0) + 1);
-			}
-			const questions: Question[] = params.questions.map((q, i) => ({
+			const questions: Question[] = params.questions.map((q) => ({
 				...q,
-				id: q.id || (q.header && (headerCounts.get(q.header) ?? 0) === 1 ? q.header : `q${i + 1}`),
-				label: q.label || `Q${i + 1}`,
-				allowOther: q.allowOther !== false,
-				options: q.options.map((o) => ({ ...o, value: o.value ?? o.label })),
+				options: q.options.map((o) => ({ ...o })),
 			}));
 
 			let overlayHandle: { focus: () => void; unfocus: () => void } | null = null;
@@ -999,14 +1168,19 @@ export default function askUserExtension(pi: ExtensionAPI) {
 				? `User cancelled the question(s). ${result.answers.length} question(s) were answered before cancellation.`
 				: result.answers
 						.map((a) => {
-							if (a.skipped) return `${a.id}: (skipped)`;
-							if (a.multiSelect) return `${a.id}: ${a.labels?.join(", ") ?? a.values?.join(", ") ?? ""}`;
-							return `${a.id}: ${a.wasCustom ? "(custom) " : ""}${a.label || a.value}`;
+							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;
 
 			return {
-				content: [{ type: "text", text: summary }],
+				content: [{ type: "text", text: withNote }],
 				details: result,
 			};
 		},