@zhushanwen/pi-ask-user 4.0.0 → 5.0.0-dev.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "4.0.0",
-  "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview and inline editor.",
+  "version": "5.0.0-dev.1",
+  "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview, inline editor and optional comments.",
   "type": "module",
   "main": "index.ts",
   "pi": {
@@ -26,7 +26,7 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "^0.3.0"
+    "@xyz-agent/extension-protocol": "^0.3.1-dev.0"
   },
   "devDependencies": {
     "@earendil-works/pi-tui": "*",
@@ -38,7 +38,7 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
-    "@zhushanwen/pi-subagent-workflow": "4.0.0"
+    "@zhushanwen/pi-subagent-workflow": "5.0.0-dev.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

package/src/__tests__/answer-format.test.ts

@@ -4,16 +4,23 @@
 // 覆盖审查 S5 发现的覆盖盲区：
 //   - parseAnswerParts 子串误匹配（"A" 不应命中 "AB"）
 //   - formatAnswer 空 parts → null
+//   - comment 分隔符边界
 
 import { describe, expect, it } from "vitest";
 
 import { formatAnswer, parseAnswerParts } from "../answer-format.js";
+import { ANSWER_COMMENT_SEPARATOR } from "../types.js";
 
 describe("formatAnswer", () => {
 	it("returns null for empty parts (unanswered)", () => {
 		expect(formatAnswer([])).toBeNull();
 	});
 
+	it("returns null for empty parts even with comment", () => {
+		// parts 空 = 没有选中选项，即使有 comment 也不应产出有效答案行
+		expect(formatAnswer([], "some comment")).toBeNull();
+	});
+
 	it("joins single part without separator", () => {
 		expect(formatAnswer(["yes"])).toBe("yes");
 	});
@@ -21,6 +28,15 @@ describe("formatAnswer", () => {
 	it("joins multiple parts with ', '", () => {
 		expect(formatAnswer(["A", "B", "C"])).toBe("A, B, C");
 	});
+
+	it("appends comment with ANSWER_COMMENT_SEPARATOR", () => {
+		const result = formatAnswer(["A", "B"], "my comment");
+		expect(result).toBe(`A, B${ANSWER_COMMENT_SEPARATOR}my comment`);
+	});
+
+	it("handles null comment (no separator appended)", () => {
+		expect(formatAnswer(["A"], null)).toBe("A");
+	});
 });
 
 describe("parseAnswerParts", () => {
@@ -28,6 +44,7 @@ describe("parseAnswerParts", () => {
 		const labels = ["yes", "no", "maybe"];
 		const result = parseAnswerParts("yes, no", labels);
 		expect(result.selected).toEqual(["yes", "no"]);
+		expect(result.comment).toBeUndefined();
 	});
 
 	// S5 核心：防子串误匹配——"A" 不应命中 label "AB"
@@ -52,21 +69,39 @@ describe("parseAnswerParts", () => {
 		expect(result.selected).toEqual(["C", "A"]);
 	});
 
+	it("extracts comment after ANSWER_COMMENT_SEPARATOR", () => {
+		const labels = ["yes"];
+		const answer = `yes${ANSWER_COMMENT_SEPARATOR}because reasons`;
+		const result = parseAnswerParts(answer, labels);
+		expect(result.selected).toEqual(["yes"]);
+		expect(result.comment).toBe("because reasons");
+	});
+
 	it("handles full-width comma (，) as separator", () => {
 		const labels = ["A", "B"];
 		const result = parseAnswerParts("A，B", labels);
 		expect(result.selected).toEqual(["A", "B"]);
 	});
 
-	it("returns non-matching tokens as neither selected (Other free text)", () => {
+	it("returns non-matching tokens as neither selected nor comment (Other free text)", () => {
 		const labels = ["yes", "no"];
 		// "custom text" 不匹配任何 label → 是 Other 自由文本
 		const result = parseAnswerParts("custom text", labels);
 		expect(result.selected).toEqual([]);
+		expect(result.comment).toBeUndefined();
 	});
 
 	it("handles empty answer string", () => {
 		const result = parseAnswerParts("", ["A", "B"]);
 		expect(result.selected).toEqual([]);
+		expect(result.comment).toBeUndefined();
+	});
+
+	it("handles answer with only comment (no selected labels)", () => {
+		const labels = ["A"];
+		const answer = `${ANSWER_COMMENT_SEPARATOR}just a comment`;
+		const result = parseAnswerParts(answer, labels);
+		expect(result.selected).toEqual([]);
+		expect(result.comment).toBe("just a comment");
 	});
 });

package/src/__tests__/channel-handler.test.ts

@@ -6,7 +6,7 @@
 //   - RPC 路径（ctx.mode === 'rpc'）：转发器——handler 内部调 askUserInteract（select 通道），
 //     把 proto answers JSON.stringify 成 {value} 返回，子进程 JSON.parse(value) 正确 decode。
 //   - TUI 路径（ctx.mode === 'tui'）：handler 走 ctx.ui.custom（mock 成返回预设 Result），
-//     验证内部 Result → proto AskUserAnswers 重新编码（single/multi/Other 三种答案形态）。
+//     验证内部 Result → proto AskUserAnswers 重新编码（single/multi/Other/comment 四种答案形态）。
 //   - 取消（askUserInteract/custom 返回 null 或 cancelled）→ {cancelled: true}
 //   - 输入校验（channelPayload 缺失/无 questions）→ {cancelled: true}
 import type { AskUserQuestion } from "@xyz-agent/extension-protocol";
@@ -75,6 +75,12 @@ const multiProto: AskUserQuestion = {
 	],
 };
 
+const commentProto: AskUserQuestion = {
+	question: "Which DB?",
+	allowComment: true,
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
 // ── Tests ───────────────────────────────────────────────
 
 describe("createAskUserChannelHandler", () => {
@@ -97,6 +103,19 @@ describe("createAskUserChannelHandler", () => {
 		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
 	});
 
+	it("RPC: Other + comment proto answers → 透传", async () => {
+		const protoAnswers = {
+			"Which DB?": "Postgres",
+			"Which DB?__other": "Custom DB",
+			"Which DB?__comment": "prod constraint",
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [commentProto] } });
+		expect(resp).toEqual({ value: JSON.stringify(protoAnswers) });
+	});
+
 	it("RPC: user cancel (select undefined) → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
@@ -198,6 +217,21 @@ describe("createAskUserChannelHandler", () => {
 		});
 	});
 
+	it("TUI: comment → ${key}__comment", async () => {
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres — prod constraint" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [commentProto] } });
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__comment": "prod constraint" }),
+		});
+	});
+
 	it("TUI: user cancel (custom returns null) → {cancelled: true}", async () => {
 		const handler = createAskUserChannelHandler(
 			makeCtx({ mode: "tui", customResult: null }) as never,

package/src/__tests__/component-keymap.test.ts

@@ -30,6 +30,7 @@ import {
 	INSERT,
 	LEFT,
 	make,
+	multiQWithComment,
 	OSC_BEL,
 	OSC_ST,
 	PAGE_DOWN,
@@ -50,6 +51,14 @@ import {
 	UP,
 } from "./fixtures";
 
+/** Helper: 打开 comment 编辑器并返回 component（多问题避免单问题 auto-submit） */
+function openComment(): AskUserComponent {
+	const { c } = make(multiQWithComment);
+	// Q1 (allowComment): select A → enters comment mode
+	c.handleInput(ENTER);
+	return c;
+}
+
 /** Helper: 打开 freeform 编辑器并返回 component（不渲染，避免缓存） */
 function openFreeform(q: Question[]): AskUserComponent {
 	const { c } = make(q);
@@ -255,6 +264,25 @@ describe("AskUserComponent — key leak fix (C-ARROW / C-KEYMAP)", () => {
 		expect(editorLine).not.toContain("abc");
 	});
 
+	// ── C-KEYMAP-COMMENT-UP: arrow key no-op in comment editor too ──
+	it("C-KEYMAP-COMMENT-UP: arrow keys are no-op in comment editor", () => {
+		const c = openComment();
+		c.handleInput("a");
+		c.handleInput(UP);
+		c.handleInput(RIGHT);
+		c.handleInput("b");
+		// comment editor renders text and cursor on separate lines;
+		// check the text line (before cursor) contains "ab"
+		const lines = c.render(60);
+		const textLine = lines.find((l) => l.includes("ab"));
+		expect(textLine).toBeDefined();
+		expect(textLine).toContain("ab");
+		// Ensure no leaked bracket characters from arrow escape sequences
+		const allText = lines.join("\n");
+		expect(allText).not.toMatch(/\[A/); // no leaked UP sequence
+		expect(allText).not.toMatch(/\[C/); // no leaked RIGHT sequence
+	});
+
 	// ── C-KEYMAP-MOD: modifier key combinations matrix (18 cases) ──
 	const modifierCases: Array<{ name: string; seq: string }> = [
 		{ name: "ctrl+up", seq: CTRL_UP },
@@ -401,6 +429,18 @@ describe("AskUserComponent — unknown control sequence leak fix (C-CSI)", () =>
 		expect(editorLine).not.toContain("\x1b[A"); expect(editorLine).not.toContain("\x1b[B"); expect(editorLine).not.toContain("\x1b[C"); expect(editorLine).not.toContain("\x1b[D");
 	});
 
+	it("C-CSI-10: unknown CSI does not leak in comment editor", () => {
+		const c = openComment();
+		c.handleInput(UNKNOWN_CSI);
+		c.handleInput("ab");
+		const lines = c.render(60);
+		const textLine = lines.find((l) => l.includes("ab"));
+		expect(textLine).toBeDefined();
+		expect(textLine).toContain("ab");
+		const allText = lines.join("\n");
+		expect(allText).not.toMatch(/\[9/);
+	});
+
 	it("C-CSI-R1: plain text still appended correctly", () => {
 		const c = openFreeform([singleQ]);
 		c.handleInput("hello");

package/src/__tests__/component.test.ts

@@ -11,9 +11,11 @@ import {
 	LEFT,
 	mockTui,
 	multiQ,
+	multiQWithComment,
 	RIGHT,
 	singleQ,
 	singleQMulti,
+	singleQWithComment,
 	stubTheme,
 	TAB,
 	UP,
@@ -161,20 +163,24 @@ describe("AskUserComponent — multi question tab nav", () => {
 		const { c, result } = make([singleQMulti]);
 		// singleQMulti: [Auth, Search]，光标初始在 Auth(0)
 		c.handleInput(DOWN); // 光标移到 Search(1)，未 toggle
-		c.handleInput(ENTER); // Enter 应同时选中 Search + confirm → submit（单问题）
+		c.handleInput(ENTER); // Enter 应同时选中 Search + confirm + allowComment → comment
+		// 断言进入了评论模式（说明 Enter 确认了，而非 no-op）
+		const lines = c.render(60);
+		expect(lines.some((l) => l.toLowerCase().includes("comment"))).toBe(true);
+		c.handleInput(ENTER); // 跳过评论 → submit（单问题）
 		expect(result.val!.answers["Which features?"]).toBe("Search");
 	});
 
-	it("C-S3: auto-confirm（←/→ 切 tab）已答问题自动确认", () => {
-		// S-3 锁定：←/→ 切走时已答问题 auto-confirm
+	it("C-S3: auto-confirm（←/→ 切 tab）跳过评论输入行，仅 Enter 路径才进评论", () => {
+		// S-3 锁定：allowComment 的问题，←/→ 切走只 auto-confirm，不进评论模式
 		const twoQMulti: Question[] = [
-			{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }], multiSelect: true },
+			{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }], multiSelect: true, allowComment: true },
 			{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
 		];
 		const { c, result } = make(twoQMulti);
 		c.handleInput(" "); // Q1 toggle A
-		c.handleInput(RIGHT); // → Q2，auto-confirm Q1
-		// 验证：当前在 Q2。Q2 选 X → Submit
+		c.handleInput(RIGHT); // → Q2，auto-confirm Q1，不进评论
+		// 验证：当前在 Q2（非 Q1 的评论模式）。Q2 选 X → Submit
 		c.handleInput(ENTER); // Q2 select X → Submit
 		c.handleInput(ENTER); // Submit
 		expect(result.val!.answers["Q1"]).toBe("A"); // auto-confirm 生效
@@ -262,14 +268,13 @@ describe("AskUserComponent — multi-select toggle", () => {
 		expect(lines.some((l) => l.includes("[ ]") && l.includes("Auth"))).toBe(true);
 	});
 
-	it("C-24 (AC-18): multi-select toggle stays in options mode (no editor)", () => {
+	it("C-24 (AC-18): multi-select toggle does NOT trigger comment mode", () => {
+		// singleQMulti has allowComment:true + multiSelect:true
 		const { c } = make([singleQMulti]);
-		c.handleInput(" "); // toggle — stays in options mode
+		c.handleInput(" "); // toggle — should NOT enter comment mode
 		const lines = c.render(60);
-		// 未进入编辑器模式（无反色光标行）
-		expect(lines.some((l) => l.includes("\x1b[7m"))).toBe(false);
-		// toggle 状态可见
-		expect(lines.some((l) => l.includes("[✓]") && l.includes("Auth"))).toBe(true);
+		// No comment prompt shown
+		expect(lines.some((l) => l.toLowerCase().includes("comment"))).toBe(false);
 	});
 });
 
@@ -467,6 +472,108 @@ describe("AskUserComponent — multi-char paste in editor", () => {
 	});
 });
 
+// ── 5f. 评论流程（FR-4.6 / FR-11 / AC-6/12/17）─────────
+describe("AskUserComponent — comment flow", () => {
+	it("C-33: single-select + allowComment Enter enters comment mode", () => {
+		const { c } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select Postgres
+		const lines = c.render(60);
+		expect(lines.some((l) => l.toLowerCase().includes("comment"))).toBe(true);
+	});
+
+	it("C-34 (AC-12): comment Enter empty skips and submits (single)", () => {
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select → comment mode
+		c.handleInput(ENTER); // empty comment → skip → submit
+		expect(result.val).not.toBeUndefined();
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres");
+	});
+
+	it("C-35: comment Enter with text saves comment", () => {
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select → comment mode
+		c.handleInput("f");
+		c.handleInput("a");
+		c.handleInput("s");
+		c.handleInput("t");
+		c.handleInput(ENTER); // save comment → submit
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres — fast");
+	});
+
+	it("C-38: multi-select + allowComment: Enter after toggle enters comment", () => {
+		const { c } = make([singleQMulti]);
+		c.handleInput(" "); // toggle Auth
+		c.handleInput(ENTER); // confirm → comment mode
+		const lines = c.render(60);
+		expect(lines.some((l) => l.toLowerCase().includes("comment"))).toBe(true);
+	});
+
+	it("C-39: Other + allowComment: freeText then comment", () => {
+		const { c, result } = make([singleQWithComment]);
+		// Navigate to Other
+		c.handleInput(DOWN);
+		c.handleInput(DOWN);
+		c.handleInput(ENTER); // open freeform
+		c.handleInput("c");
+		c.handleInput("u");
+		c.handleInput("s");
+		c.handleInput("t");
+		c.handleInput("o");
+		c.handleInput("m");
+		c.handleInput(ENTER); // save freeText → allowComment → comment mode
+		c.handleInput(ENTER); // empty comment → skip → submit
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("custom");
+	});
+
+	it("C-36 (AC-17): comment Esc skips comment and advances (single)", () => {
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select Postgres → comment mode
+		c.handleInput(ESC); // Esc in comment = skip comment → advance → submit
+		expect(result.val).not.toBeUndefined();
+		// commentValue stays null (no prior comment), answer is the selected option
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres");
+	});
+
+	it("C-36b (AC-17): comment Esc advances to next tab (multi-question)", () => {
+		const { c, result } = make(multiQWithComment);
+		// Q1 (allowComment): select A → comment mode
+		c.handleInput(ENTER); // select A → comment mode
+		c.handleInput(ESC); // Esc in comment = skip → advance to Q2
+		// Q2: select X → Submit
+		c.handleInput(ENTER); // select X → Submit
+		c.handleInput(ENTER); // Submit
+		expect(result.val).not.toBeUndefined();
+		expect(result.val!.answers["Q1"]).toBe("A");
+		expect(result.val!.answers["Q2"]).toBe("X");
+	});
+
+	it("C-36c (AC-17): Esc-in-comment discards typed text (vs Enter which saves)", () => {
+		// Contrast: typing then Enter would save commentValue and append " — keep".
+		// Esc should discard the typed editor text and advance without attaching it.
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select Postgres → comment mode
+		c.handleInput("k");
+		c.handleInput("e");
+		c.handleInput("e");
+		c.handleInput("p");
+		c.handleInput(ESC); // Esc in comment = discard typed text → advance → submit
+		expect(result.val).not.toBeUndefined();
+		// No " — keep" suffix: Esc did not commit the typed text
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres");
+	});
+
+	it("C-37: answer + comment combined format 'label — note'", () => {
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select Postgres → comment mode
+		c.handleInput("n");
+		c.handleInput("o");
+		c.handleInput("t");
+		c.handleInput("e");
+		c.handleInput(ENTER); // save comment → submit
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres — note");
+	});
+});
+
 // ── 5g. 防重入（FR-12）─────────────────────────────────
 describe("AskUserComponent — re-entry guard", () => {
 	it("C-40: ignores input after resolution (submit)", () => {
@@ -551,12 +658,12 @@ describe("AskUserComponent — Submit tab", () => {
 	});
 
 	it("C-46: Submit Enter when all confirmed submits", () => {
-		const { c, result } = make([
-			{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }] },
-			{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
-		]);
-		c.handleInput(ENTER); // Q1 select A → Q2
-		c.handleInput(ENTER); // Q2 select X → Submit
+		const { c, result } = make(multiQWithComment);
+		// Q1 (allowComment): select A → comment mode → skip
+		c.handleInput(ENTER); // select A
+		c.handleInput(ENTER); // skip comment → Q2
+		// Q2: select X
+		c.handleInput(ENTER); // → Submit
 		c.handleInput(ENTER); // Submit
 		expect(result.val).not.toBeUndefined();
 		expect(result.val!.answers["Q1"]).toBe("A");
@@ -699,7 +806,7 @@ describe("AskUserComponent — confirm-checkmark, Esc-back, Tab browsing", () =>
 // ── 5l. 新行为：←/→ 不切 tab、Other Enter 切 freeform 原生、Submit tab focus ──
 describe("AskUserComponent — new behavior (post-refactor)", () => {
 	it("C-NEW-1: multi-select Other + Enter opens freeform; Other row turns into [ ] <input>█ in-place", () => {
-		// singleQMulti: [Auth, Search]，多选
+		// singleQMulti: [Auth, Search]，多选 + allowComment
 		const { c, result } = make([singleQMulti]);
 		// 1) Space toggle Auth
 		c.handleInput(" ");
@@ -720,13 +827,14 @@ describe("AskUserComponent — new behavior (post-refactor)", () => {
 		expect(lines.some((l) => l.includes("Search"))).toBe(true);
 		// [✓] 标记的 Auth 仍存在（toggle 状态保留）
 		expect(lines.some((l) => l.includes("[✓]") && l.includes("Auth"))).toBe(true);
-		// 4) 输 "redis" → Enter 保存 → submit（单问题）
+		// 4) 输 "redis" → Enter 保存 → allowComment → comment mode
 		c.handleInput("r");
 		c.handleInput("e");
 		c.handleInput("d");
 		c.handleInput("i");
 		c.handleInput("s");
-		c.handleInput(ENTER); // 保存 freeText → submit（单问题）
+		c.handleInput(ENTER); // 保存 freeText → comment mode
+		c.handleInput(ENTER); // 跳过评论 → submit（单问题）
 		// 答案含多选 toggle 项 + Other 自定义
 		expect(result.val!.answers["Which features?"]).toBe("Auth, redis");
 	});
@@ -769,12 +877,11 @@ describe("AskUserComponent — new behavior (post-refactor)", () => {
 	});
 
 	it("C-NEW-4: Submit tab Enter on Submit focus (all confirmed) submits", () => {
-		const { c, result } = make([
-			{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }] },
-			{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
-		]);
+		// multiQWithComment: Q1 allowComment, Q2 plain
+		const { c, result } = make(multiQWithComment);
 		// 答完 Q1 + Q2
-		c.handleInput(ENTER); // Q1 select A → Q2
+		c.handleInput(ENTER); // Q1 select A → comment mode
+		c.handleInput(ENTER); // skip comment → Q2
 		c.handleInput(ENTER); // Q2 select X → Submit tab（Q2 是最后一个问题，advance 到 Submit）
 		// 已经在 Submit tab，focus=Submit，按 Enter 提交
 		c.handleInput(ENTER);

package/src/__tests__/e2e.test.ts

@@ -7,8 +7,8 @@ import { describe, expect, it } from "vitest";
 
 import { makeE2E } from "./e2e-harness";
 
-// ── E2E-1: 单问题 — 选第二项提交 ────────────────────
-describe("E2E-1: single question — pick 2nd option", () => {
+// ── E2E-1: 单问题无评论 — 选第二项提交 ─────────────────
+describe("E2E-1: single question, no comment — pick 2nd option", () => {
 	const questions = [
 		{
 			question: "Which DB?",
@@ -32,6 +32,53 @@ describe("E2E-1: single question — pick 2nd option", () => {
 	});
 });
 
+// ── E2E-2: 单问题 + allowComment — 选项 + 评论拼接 ─────
+describe("E2E-2: single question + allowComment — option + comment joined", () => {
+	const questions = [
+		{
+			question: "Which DB?",
+			allowComment: true,
+			options: [{ label: "Postgres" }, { label: "SQLite" }],
+		},
+	];
+
+	it("joins selected option with comment via ' — '", async () => {
+		const e = makeE2E(questions);
+		// Enter 选 Postgres → 进评论模式 → 输 "fast" → Enter 保存（allowComment 分支）
+		e.keys(["\r", "f", "a", "s", "t", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		expect(details.answers["Which DB?"]).toBe("Postgres — fast");
+		expect(result.content[0].text).toContain("Postgres — fast");
+	});
+});
+
+// ── E2E-3: 单问题 + allowComment — Enter 空评论跳过 ─────
+describe("E2E-3: single question + allowComment — Enter in comment skips", () => {
+	const questions = [
+		{
+			question: "Which DB?",
+			allowComment: true,
+			options: [{ label: "Postgres" }, { label: "SQLite" }],
+		},
+	];
+
+	it("empty Enter in comment mode keeps option without ' — ' suffix", async () => {
+		const e = makeE2E(questions);
+		// Enter 选 Postgres → 直接 Enter 评论模式跳过（AC-12）
+		e.keys(["\r", "\r"]);
+		const result = await e.getExecuted();
+		const details = result.details;
+
+		expect(details.cancelled).toBe(false);
+		// 不含 " — " 分隔符
+		expect(details.answers["Which DB?"]).toBe("Postgres");
+		expect(details.answers["Which DB?"]).not.toContain("—");
+	});
+});
+
 // ── E2E-4: 多问题提交 — 逐题选择后 Submit tab 提交（S-11）──────
 describe("E2E-4: multi-question submit — answer each then Submit tab", () => {
 	const questions = [

package/src/__tests__/fixtures.ts

@@ -42,6 +42,7 @@ export const singleQ: Question = {
 
 export const singleQWithComment: Question = {
 	question: "Which DB? (with comment)",
+	allowComment: true,
 	options: [
 		{ label: "Postgres", description: "Battle-tested" },
 		{ label: "SQLite", description: "Embedded" },
@@ -51,6 +52,7 @@ export const singleQWithComment: Question = {
 export const singleQMulti: Question = {
 	question: "Which features?",
 	multiSelect: true,
+	allowComment: true,
 	options: [
 		{ label: "Auth", description: "OAuth + session" },
 		{ label: "Search", description: "Full-text" },
@@ -69,7 +71,7 @@ export const multiQ: Question[] = [
 ];
 
 export const multiQWithComment: Question[] = [
-	{ question: "Q1", header: "First", options: [{ label: "A" }, { label: "B" }] },
+	{ question: "Q1", header: "First", allowComment: true, options: [{ label: "A" }, { label: "B" }] },
 	{ question: "Q2", header: "Second", options: [{ label: "X" }, { label: "Y" }] },
 ];
 

package/src/__tests__/index.test.ts

@@ -645,6 +645,31 @@ describe("execute — RPC mode (askUserInteract via select channel)", () => {
 		expect(result.details.answers["Which DB?"]).toBe("Postgres, Custom DB");
 	});
 
+	it("R-4: comment → inlined with ' — ' separator", async () => {
+		const tool = getTool();
+		const withComment = {
+			questions: [
+				{
+					question: "Which DB?",
+					options: [{ label: "Postgres" }, { label: "SQLite" }],
+					allowComment: true,
+				},
+			],
+		};
+		const protoAnswers = JSON.stringify({
+			"Which DB?": "Postgres",
+			"Which DB?__comment": "prod constraint",
+		});
+		const result = await tool.execute(
+			"id",
+			withComment,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+		expect(result.details.answers["Which DB?"]).toBe("Postgres — prod constraint");
+	});
+
 	it("R-5: user cancel (select returns undefined) → cancelled details", async () => {
 		const tool = getTool();
 		const result = await tool.execute(
@@ -696,7 +721,7 @@ describe("execute — RPC mode (askUserInteract via select channel)", () => {
 		expect(result.details.answers["Which database?"]).toBe("Postgres");
 	});
 
-	it("R-8: multi-question mixed (single-select + multi-select + Other)", async () => {
+	it("R-8: multi-question mixed (single-select + multi-select + Other + comment)", async () => {
 		const tool = getTool();
 		const mixed = {
 			questions: [
@@ -715,6 +740,7 @@ describe("execute — RPC mode (askUserInteract via select channel)", () => {
 					question: "Which region?",
 					header: "Region",
 					options: [{ label: "US" }, { label: "EU" }],
+					allowComment: true,
 				},
 			],
 		};
@@ -743,4 +769,40 @@ describe("execute — RPC mode (askUserInteract via select channel)", () => {
 		// Q3: 无选中 → 跳过（不在 answers map 中）
 		expect(result.details.answers["Which region?"]).toBeUndefined();
 	});
+
+	it("R-9: multi-question with comment on one question", async () => {
+		const tool = getTool();
+		const multiQ = {
+			questions: [
+				{
+					question: "Which DB?",
+					header: "DB",
+					options: [{ label: "Postgres" }],
+				},
+				{
+					question: "Why?",
+					header: "Reason",
+					options: [{ label: "Performance" }],
+					allowComment: true,
+				},
+			],
+		};
+		const protoAnswers = JSON.stringify({
+			DB: "Postgres",
+			Reason: "Performance",
+			"Reason__comment": "benchmarked",
+		});
+		const result = await tool.execute(
+			"id",
+			multiQ,
+			undefined,
+			undefined,
+			makeCtx({ mode: "rpc", selectResult: protoAnswers }),
+		);
+
+		// Q1: 无 comment
+		expect(result.details.answers["Which DB?"]).toBe("Postgres");
+		// Q2: 有 comment → 内联
+		expect(result.details.answers["Why?"]).toBe("Performance — benchmarked");
+	});
 });

package/src/__tests__/question-view.test.ts

@@ -252,7 +252,7 @@ describe("renderQuestionView — Other editor mode", () => {
 	});
 
 	it("Q-28-WIDE: freeform 模式在宽终端下用全宽渲染（不被分屏左列压窄）", () => {
-		// 回归：freeform 模式忽略分屏，编辑器用全 width。
+		// 回归：freeform/comment 模式忽略分屏，编辑器用全 width。
 		// 修复前：宽终端走 split.left(≈40)，Other 输入被压在左半屏换行频繁。
 		const width = 100;
 		// getSplitPaneWidths(100) 非 null（宽终端会进分屏分支），但 freeform 应绕过它
@@ -335,6 +335,35 @@ describe("renderQuestionView — Other editor mode", () => {
 	});
 });
 
+// ── Q-18 ~ Q-19: 评论模式 ───────────────────────────────
+describe("renderQuestionView — comment mode", () => {
+	it("Q-18: comment mode renders editor with note text", () => {
+		const lines = rv(
+			singleQ,
+			makeState({ mode: "comment", selectedIndex: 0 }),
+			stubTheme,
+			60,
+			true,
+			"my note",
+		);
+		const t = text(lines);
+		expect(t.toLowerCase()).toContain("comment");
+		expect(t).toContain("my note");
+	});
+
+	it("Q-19: comment prompt includes (optional)", () => {
+		const lines = rv(
+			singleQ,
+			makeState({ mode: "comment", selectedIndex: 0 }),
+			stubTheme,
+			60,
+			true,
+			"",
+		);
+		expect(text(lines)).toContain("(optional)");
+	});
+});
+
 // ── Q-20 ~ Q-23: 帮助行 ─────────────────────────────────
 describe("renderQuestionView — help line", () => {
 	it("Q-20: single-select help shows 'Enter select'", () => {

package/src/__tests__/submit-view.test.ts

@@ -124,6 +124,11 @@ describe("getAnswerText", () => {
 		expect(getAnswerText(q1, s)).toBe("custom");
 	});
 
+	it("S-9: comment appended with separator", () => {
+		const s = makeState({ confirmed: true, selectedIndex: 0, commentValue: "fast" });
+		expect(getAnswerText(q1, s)).toBe("Postgres — fast");
+	});
+
 	it("S-10: unconfirmed returns null", () => {
 		const s = makeState({ confirmed: false });
 		expect(getAnswerText(q1, s)).toBeNull();
@@ -143,6 +148,21 @@ describe("getAnswerText", () => {
 		const sEmptyMulti = makeState({ confirmed: true, selectedIndices: new Set<number>() });
 		expect(getAnswerText(multiQ, sEmptyMulti)).toBeNull();
 	});
+
+	it("S-9b: multi-select + comment combined", () => {
+		const multiQ: Question = {
+			question: "Features",
+			multiSelect: true,
+			allowComment: true,
+			options: [{ label: "A" }, { label: "B" }],
+		};
+		const s = makeState({
+			confirmed: true,
+			selectedIndices: new Set([0, 1]),
+			commentValue: "nice",
+		});
+		expect(getAnswerText(multiQ, s)).toBe("A, B — nice");
+	});
 });
 
 // ── S-11 ~ S-12: buildResult ─────────────────────────────

package/src/__tests__/types.test.ts

@@ -40,6 +40,7 @@ describe("types", () => {
 		expect(s.selectedIndices).toBeInstanceOf(Set);
 		expect(s.confirmed).toBe(false);
 		expect(s.freeTextValue).toBeNull();
+		expect(s.commentValue).toBeNull();
 		expect(s.mode).toBe("options");
 	});
 

package/src/__tests__/validate.test.ts

@@ -82,7 +82,7 @@ describe("validateInput", () => {
 	});
 
 	// V-10/S3: 多 question 时 header 必须唯一——重复 header 会导致 askUserKey 碰撞
-	// （协议 helper 用 header 作 answers 读取 key，后一个覆盖前一个的 Other）
+	// （协议 helper 用 header 作 answers 读取 key，后一个覆盖前一个的 Other/comment）
 	it("rejects duplicate headers across different questions", () => {
 		const result = validateInput([
 			q({ question: "Q1", header: "Same" }),

package/src/__tests__/w2-draft-hint.test.ts

@@ -13,6 +13,7 @@ import {
 	multiQ,
 	RIGHT,
 	singleQ,
+	singleQWithComment,
 	stubTheme,
 	UP,
 } from "./fixtures";
@@ -77,6 +78,15 @@ describe("W2 — draftText migration", () => {
 		expect(editorLine1).toContain("aaa");
 		expect(editorLine1).not.toContain("ccc");
 	});
+
+	it("C-BC4C: comment flow submits comment with answer", () => {
+		const { c, result } = make([singleQWithComment]);
+		c.handleInput(ENTER); // select A → comment mode
+		c.handleInput("my note");
+		c.handleInput(ENTER); // submit
+		expect(result.val).toBeDefined();
+		expect(result.val!.answers["Which DB? (with comment)"]).toBe("Postgres — my note");
+	});
 });
 
 // ── hint line: append-only UX hint ──
@@ -92,6 +102,16 @@ describe("W2 — hint line", () => {
 		expect(hintLine).toContain("Enter submit");
 		expect(hintLine).toContain("Esc back");
 	});
+
+	it("C-HINT-2: comment editor hint contains all expected hints", () => {
+		const { c } = make([singleQWithComment]);
+		c.handleInput(ENTER);
+		const lines = c.render(80);
+		const hintLine = lines.find((l: string) => l.includes("move") && l.includes("Backspace deletes"));
+		expect(hintLine).toBeDefined();
+		expect(hintLine).toContain("Enter submit");
+		expect(hintLine).toContain("Esc back");
+	});
 });
 
 // ── freeDraft 隔离：丢弃的 freeform 草稿不污染答案、不触发 auto-confirm ──

package/src/__tests__/w3-regression.test.ts

@@ -1,5 +1,5 @@
 // src/__tests__/w3-regression.test.ts
-// W3: Forward regression — freeform/bksp edge cases.
+// W3: Forward regression — freeform/comment/bksp edge cases.
 // No-op keymap coverage moved to component-keymap.test.ts (deduplicated).
 import { describe, expect, it } from "vitest";
 
@@ -14,6 +14,7 @@ import {
 	LEFT,
 	mockTui,
 	multiQ,
+	multiQWithComment,
 	RIGHT,
 	singleQ,
 	stubTheme,
@@ -71,6 +72,33 @@ describe("W3 — freeform Enter clears selectedIndex (C-BC4B)", () => {
 	});
 });
 
+// ── C-BC4C: comment edge cases ──
+// C-BC4C-REEDIT (initial comment submit) removed — duplicate of w2-draft-hint C-BC4C.
+describe("W3 — comment re-edit (C-BC4C-CLEAR)", () => {
+	it("C-BC4C-CLEAR: Esc in comment mode skips comment, keeps existing commentValue", () => {
+		const { c, result } = make(multiQWithComment);
+		// Q1: select A → comment mode
+		c.handleInput(ENTER);
+		c.handleInput("my note");
+		c.handleInput(ENTER); // submit comment → advance to Q2
+		// Q2: select X
+		c.handleInput(ENTER);
+		c.handleInput(ENTER); // confirm Q2 → advance to submit tab
+		// Go back to Q1
+		c.handleInput(LEFT);
+		// Q1 is already confirmed, re-select A to trigger comment again
+		c.handleInput(ENTER); // re-select A → afterConfirm → comment mode
+		c.handleInput(ESC); // skip comment
+		// Submit
+		c.handleInput(RIGHT);
+		c.handleInput(RIGHT); // navigate to submit tab
+		c.handleInput(ENTER);
+		expect(result.val).toBeDefined();
+		// Comment should still be "my note" (Esc preserved commentValue)
+		expect(result.val!.answers["Q1"]).toBe("A — my note");
+	});
+});
+
 // ── C-BKSP-EDGE: backspace at cursorIndex=0 ──
 
 describe("W3 — backspace at cursorIndex=0 (C-BKSP-EDGE)", () => {

package/src/answer-format.ts

@@ -1,16 +1,19 @@
 // src/answer-format.ts
 // 答案文本格式的唯一权威模块。
 // TUI 路径（submit-view.ts:getAnswerText）和 RPC 路径（index.ts:protoAnswersToResult）
-// 都调 formatAnswer 产出 "label1, label2" 格式，确保两条路径一致。
+// 都调 formatAnswer 产出 "label1, label2 — comment" 格式，确保两条路径一致。
 // renderExpandedOptions（index.ts）调 parseAnswerParts 精确反解析选中项。
+import { ANSWER_COMMENT_SEPARATOR } from "./types";
 
 /**
- * 把答案各部分拼装为最终文本格式："part1, part2"。
+ * 把答案各部分拼装为最终文本格式："part1, part2 — comment"。
  * - parts 为空 → 返回 null（未答）
+ * - comment 有值 → 追加 ANSWER_COMMENT_SEPARATOR + comment
  */
-export function formatAnswer(parts: string[]): string | null {
+export function formatAnswer(parts: string[], comment?: string | null): string | null {
 	if (parts.length === 0) return null;
-	return parts.join(", ");
+	const base = parts.join(", ");
+	return comment ? `${base}${ANSWER_COMMENT_SEPARATOR}${comment}` : base;
 }
 
 /**
@@ -19,15 +22,24 @@ export function formatAnswer(parts: string[]): string | null {
  *
  * @param answer 最终答案文本（formatAnswer 产出）
  * @param labels 候选 label 列表（q.options 的 label），精确匹配
- * @returns selected=命中的 labels（按 answer 中出现顺序）
+ * @returns selected=命中的 labels（按 answer 中出现顺序），comment=评论文本（如有）
  */
 export function parseAnswerParts(
 	answer: string,
 	labels: string[],
-): { selected: string[] } {
-	// answer 形如 "label1, label2" → 精确匹配候选 label
+): { selected: string[]; comment?: string } {
+	// 先提取 comment（ANSWER_COMMENT_SEPARATOR 之后的部分）
+	let body = answer;
+	let comment: string | undefined;
+	const sepIdx = answer.indexOf(ANSWER_COMMENT_SEPARATOR);
+	if (sepIdx >= 0) {
+		body = answer.slice(0, sepIdx);
+		comment = answer.slice(sepIdx + ANSWER_COMMENT_SEPARATOR.length).trim();
+	}
+
+	// body 形如 "label1, label2" → 精确匹配候选 label
 	const labelSet = new Set(labels);
-	const tokens = answer.split(/[,，]/).map((t) => t.trim()).filter(Boolean);
+	const tokens = body.split(/[,，]/).map((t) => t.trim()).filter(Boolean);
 	const selected: string[] = [];
 	// 剩余 tokens 不匹配任何 label → 是 Other 自由文本（不返回，调用方自行处理）
 	for (const token of tokens) {
@@ -35,5 +47,5 @@ export function parseAnswerParts(
 			selected.push(token);
 		}
 	}
-	return { selected };
+	return { selected, comment };
 }

package/src/channel-handler.ts

@@ -9,8 +9,8 @@
 //     不循环）。返回 {value: JSON.stringify(answers)} 让子进程 JSON.parse(value) decode。
 //   - TUI：走 ctx.ui.custom + AskUserComponent。三步：(1) protoQuestions → 内部 Question[]，
 //     (2) ctx.ui.custom 渲染拿内部 Result，(3) 内部 Result.answers（key=question 全文，
-//     value="label1, label2"）→ 重新编码为 proto AskUserAnswers（key=header/question，
-//     单选=value，多选=JSON 数组，Other→__other），让子进程 decode 一致。
+//     value="label1, label2 — comment"）→ 重新编码为 proto AskUserAnswers（key=header/question，
+//     单选=value，多选=JSON 数组，Other→__other，comment→__comment），让子进程 decode 一致。
 //
 // handler 收到的 req.channelPayload = {questions: AskUserQuestion[], allowCancel}（proto 格式，
 // 由子进程 askUserInteract 编码、subagent-workflow parseChannel 解析 options[0] JSON 得到）。
@@ -23,7 +23,7 @@ import {
 } from "@xyz-agent/extension-protocol";
 
 import { AskUserComponent } from "./component";
-import { type Option, type Question, type Result, type ThemeLike } from "./types";
+import { ANSWER_COMMENT_SEPARATOR, type Option, type Question, type Result, type ThemeLike } from "./types";
 
 /**
  * channel handler 签名——与 subagent-workflow 的 UiChannelRegistry.ChannelHandler 一致
@@ -59,6 +59,7 @@ function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[]
 			...(pq.context !== undefined ? { context: pq.context } : {}),
 			options: opts,
 			...(pq.multiSelect !== undefined ? { multiSelect: pq.multiSelect } : {}),
+			...(pq.allowComment !== undefined ? { allowComment: pq.allowComment } : {}),
 		};
 	});
 }
@@ -66,17 +67,18 @@ function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[]
 /**
  * 把 TUI 路径产出的内部 Result.answers 重新编码为 proto AskUserAnswers。
  *
- * 内部 Result.answers：key = question 全文，value = "label1, label2"
- * （Other 自由文本与 selected 标签逗号拼接）。
+ * 内部 Result.answers：key = question 全文，value = "label1, label2 — comment"
+ * （Other 自由文本与 selected 标签逗号拼接，comment 用 ANSWER_COMMENT_SEPARATOR 分隔）。
  *
  * proto AskUserAnswers 契约（@xyz-agent/extension-protocol）：
  *   - key = question.header ?? question 全文
  *   - 单选：value = 选中项 value string
  *   - 多选：value = JSON.stringify(选中项 value 数组)
  *   - Other 自由文本：单独 key `${header}__other`
+ *   - comment：单独 key `${header}__comment`
  *
  * 解码（无信息丢失）：用 protoQuestion.options 的 label 集合精确匹配 selected；
- * 不匹配的 token = Other 自由文本。
+ * 不匹配的 token = Other 自由文本；comment 由 ANSWER_COMMENT_SEPARATOR 切出。
  */
 function encodeTuiResultToProto(
 	protoQuestions: AskUserQuestion[],
@@ -95,8 +97,15 @@ function encodeTuiResultToProto(
 			if (o.value !== undefined) knownLabels.add(o.value);
 		}
 
+		// 切 body / comment（comment 在 ANSWER_COMMENT_SEPARATOR 之后）
+		const sepIdx = internalText.indexOf(ANSWER_COMMENT_SEPARATOR);
+		const body = sepIdx >= 0 ? internalText.slice(0, sepIdx) : internalText;
+		const comment = sepIdx >= 0
+			? internalText.slice(sepIdx + ANSWER_COMMENT_SEPARATOR.length).trim() || undefined
+			: undefined;
+
 		// body tokens：匹配 knownLabels 的为 selected，其余为 Other 自由文本
-		const tokens = internalText.split(/[,，]/).map((t: string) => t.trim()).filter((t: string) => t !== "");
+		const tokens = body.split(/[,，]/).map((t: string) => t.trim()).filter((t: string) => t !== "");
 		const selected: string[] = [];
 		const otherTokens: string[] = [];
 		for (const t of tokens) {
@@ -121,6 +130,7 @@ function encodeTuiResultToProto(
 		}
 
 		if (otherText) answers[`${key}__other`] = otherText;
+		if (comment) answers[`${key}__comment`] = comment;
 	}
 	return answers;
 }

package/src/component.ts

@@ -201,8 +201,8 @@ export class AskUserComponent implements Component {
 		const state = this.states[this.activeTab]!;
 		const q = this.questions[this.activeTab]!;
 
-		// freeform mode → editor text input
-		if (state.mode === "freeform") {
+		// freeform / comment mode → editor text input
+		if (state.mode === "freeform" || state.mode === "comment") {
 			this.handleEditorInput(data, state, q);
 			return;
 		}
@@ -264,14 +264,14 @@ export class AskUserComponent implements Component {
 			}
 			if (matchesKey(data, "enter")) {
 				state.selectedIndices.add(state.cursorIndex);
-				this.afterConfirm(state);
+				this.afterConfirm(state, q);
 				return;
 			}
 		} else if (!q.multiSelect && !onOther) {
 			if (matchesKey(data, "enter")) {
 				state.selectedIndex = state.cursorIndex;
 				state.freeTextValue = null;
-				this.afterConfirm(state);
+				this.afterConfirm(state, q);
 				return;
 			}
 		}
@@ -364,8 +364,16 @@ export class AskUserComponent implements Component {
 		// 其他 special key（功能键/modifier 组合）→ no-op（不泄漏）
 	}
 
-	/** Esc：freeform 存 freeDraft 草稿后回 options。 */
+	/** Esc：comment 跳过评论并 advance；freeform 存 freeDraft 草稿后回 options。 */
 	private handleEditorEsc(state: QuestionState): void {
+		if (state.mode === "comment") {
+			// comment Esc: skip comment, advance (keep existing commentValue)
+			state.mode = "options";
+			state.draftText = "";
+			state.cursorIndex = state.savedOptionsCursorIndex;
+			this.advance();
+			return;
+		}
 		// freeform Esc: save draft to freeDraft (separate from submitted freeTextValue)
 		// so discarded drafts don't pollute the answer or trigger auto-confirm.
 		state.freeDraft = state.draftText || null;
@@ -375,26 +383,34 @@ export class AskUserComponent implements Component {
 		this.rerender();
 	}
 
-	/** Enter：freeform 有文本→提交，空文本→回退。 */
+	/** Enter：freeform 有文本→提交，空文本→回退；comment→保存评论并 advance。 */
 	private handleEditorEnter(state: QuestionState, q: Question): void {
 		const text = state.draftText.trim();
-		state.cursorIndex = state.savedOptionsCursorIndex;
-		if (text) {
-			state.freeTextValue = text;
-			state.selectedIndex = null;
-			state.mode = "options";
-			state.draftText = "";
-			this.afterConfirm(state);
-		} else {
-			state.freeTextValue = null;
-			state.mode = "options";
-			state.draftText = "";
-			// freeTextValue 刚清空；confirmed 仅在无其他选择时置 false（允许重新作答）
-			if (q.multiSelect ? state.selectedIndices.size === 0 : state.selectedIndex === null) {
-				state.confirmed = false;
+		if (state.mode === "freeform") {
+			state.cursorIndex = state.savedOptionsCursorIndex;
+			if (text) {
+				state.freeTextValue = text;
+				state.selectedIndex = null;
+				state.mode = "options";
+				state.draftText = "";
+				this.afterConfirm(state, q);
+			} else {
+				state.freeTextValue = null;
+				state.mode = "options";
+				state.draftText = "";
+				// freeTextValue 刚清空；confirmed 仅在无其他选择时置 false（允许重新作答）
+				if (q.multiSelect ? state.selectedIndices.size === 0 : state.selectedIndex === null) {
+					state.confirmed = false;
+				}
+				this.rerender();
 			}
-			this.rerender();
+			return;
 		}
+		state.commentValue = text || null;
+		state.mode = "options";
+		state.draftText = "";
+		state.cursorIndex = state.savedOptionsCursorIndex;
+		this.advance();
 	}
 
 	private toggleIndex(state: QuestionState, index: number): void {
@@ -434,9 +450,17 @@ export class AskUserComponent implements Component {
 		this.rerender();
 	}
 
-	/** 选中确认后的处理：直接前进到下一题（或单问题提交）。 */
-	private afterConfirm(state: QuestionState): void {
+	/** 选中确认后的处理：若 allowComment（4.0.1 restore 字段），进入评论模式（可重入编辑/清除已有评论）；否则前进。 */
+	private afterConfirm(state: QuestionState, q: Question): void {
 		state.confirmed = true;
+		if (q.allowComment && state.mode !== "comment") {
+			state.savedOptionsCursorIndex = state.cursorIndex;
+			state.mode = "comment";
+			state.draftText = state.commentValue ?? "";
+			state.cursorIndex = state.draftText.length;
+			this.rerender();
+			return;
+		}
 		this.advance();
 	}
 

package/src/index.ts

@@ -7,6 +7,7 @@ import {
 	askUserInteract,
 	type AskUserQuestion,
 	getAskUserAnswer,
+	getAskUserComment,
 	getAskUserOther,
 } from "@xyz-agent/extension-protocol";
 
@@ -127,14 +128,15 @@ function toProtoQuestions(questions: Question[]): AskUserQuestion[] {
 		})),
 		multiSelect: q.multiSelect,
 		allowOther: true,
+		allowComment: q.allowComment ?? false,
 	}));
 }
 
 /**
  * 把协议包 AskUserAnswers 转换为 ask-user 内部 Result.answers。
  *
- * 协议格式：key=header/question, 单选=string, 多选=JSON数组, Other=__other
- * ask-user 格式：key=question 全文, value=逗号分隔 label + Other
+ * 协议格式：key=header/question, 单选=string, 多选=JSON数组, Other=__other, comment=__comment（4.0.1 restore）
+ * ask-user 格式：key=question 全文, value=逗号分隔 label + Other, comment 内联（` — `）
  *
  * 拼装逻辑复用 formatAnswer（与 TUI 版 getAnswerText 共享同一格式函数），
  * 确保 RPC 和 TUI 两条路径产出的 Result.answers 格式一致。
@@ -150,6 +152,7 @@ function protoAnswersToResult(
 		const iq = protoQuestions[i]!;
 		const selected = getAskUserAnswer(answers, iq);
 		const other = getAskUserOther(answers, iq);
+		const comment = getAskUserComment(answers, iq);
 
 		const parts: string[] = [];
 		if (Array.isArray(selected)) {
@@ -167,7 +170,7 @@ function protoAnswersToResult(
 			parts.push(selected);
 		}
 		if (other) parts.push(other);
-		const formatted = formatAnswer(parts);
+		const formatted = formatAnswer(parts, comment);
 		if (formatted !== null) out[q.question] = formatted;
 	}
 	return out;

package/src/question-view.ts

@@ -136,7 +136,7 @@ function buildOptionLines(
 	for (let i = 0; i < opts.length; i++) {
 		const opt = opts[i]!;
 		// 编辑器模式下用 savedOptionsCursorIndex 判断选项高亮，cursorIndex 此时是文本光标
-		const activeOptionCursor = state.mode === "freeform" ? state.savedOptionsCursorIndex : state.cursorIndex;
+		const activeOptionCursor = (state.mode === "freeform" || state.mode === "comment") ? state.savedOptionsCursorIndex : state.cursorIndex;
 		const isSelected = i === activeOptionCursor;
 		const isOther = opt.isOther === true;
 		const prefix = isSelected ? t.fg("accent", ">") : " ";
@@ -224,6 +224,33 @@ function buildPreviewLines(
 	return lines;
 }
 
+/**
+ * freeform 模式：editor 已在 buildOptionLines 中原地渲染（[ ] <input> 反色光标 行），
+ * buildEditorBlock 在此模式下不重复输出，**仅留出与正常 help 行同位置的视觉空隙**。
+ * comment 模式：保留独立编辑块（与 normal help 行解耦：comment 行有更长的 prompt）。
+ */
+function buildEditorBlock(
+	ctx: RenderContext,
+): string[] {
+	const { state, theme: t, width } = ctx;
+	if (state.mode === "freeform") {
+		return [""];
+	}
+	const lines: string[] = [];
+	const add = (s: string): void => {
+		lines.push(truncateToWidth(s, width));
+	};
+	add("");
+	const prompt = t.fg("muted", " Your comment (optional):");
+	add(prompt);
+	// 渲染当前编辑器文本，光标用反色高亮当前字符（surrogate pair 安全）
+	const cursorText = renderCursorText(state.draftText, state.cursorIndex);
+	add(` ${t.fg("text", cursorText)}`);
+	add("");
+	add(t.fg("dim", EDITOR_HINT));
+	return lines;
+}
+
 /** 渲染分屏模式下的左右双列（选项列表 + 详情预览）。 */
 function buildSplitPane(
 	ctx: RenderContext,
@@ -275,20 +302,21 @@ export function renderQuestionView(ctx: RenderContext): string[] {
 
 	// 选项模式下：question/context 与 options 之间加分割线（三段式）
 	// 编辑器模式不加（编辑器块自带视觉边界）
-	if (state.mode !== "freeform") {
+	if (state.mode !== "freeform" && state.mode !== "comment") {
 		divider();
 	}
 
-	// 编辑器模式：选项列表 + 原地编辑器行（freeform 模式下 buildOptionLines 原地渲染）。
+	// 编辑器/评论模式：选项列表 + 编辑器块（freeform 模式下编辑器块为空，由 buildOptionLines 原地渲染）。
 	// 编辑器模式一律用全 width 单列渲染——分屏左列仅约 42% 宽，Other 自由输入会被压窄换行，
 	// 且右侧详情预览在输入自定义内容时无意义。隐藏 descriptions 以避免行数爆炸。
-	if (state.mode === "freeform") {
+	if (state.mode === "freeform" || state.mode === "comment") {
 		add("");
 		for (const line of buildOptionLines(ctx, false)) add(line);
-		// 选项列表与 help 行之间的视觉空隙（旧 buildEditorBlock freeform 分支返回 [""] 提供）
-		add("");
-		// freeform 模式 help 行：光标锁在 Other 上，正在输入
-		add(t.fg("dim", EDITOR_HINT));
+		lines.push(...buildEditorBlock(ctx));
+		if (state.mode === "freeform") {
+			// freeform 模式 help 行：光标锁在 Other 上，正在输入
+			add(t.fg("dim", EDITOR_HINT));
+		}
 		return lines;
 	}
 

package/src/submit-view.ts

@@ -44,7 +44,7 @@ export function getAnswerText(q: Question, s: QuestionState): string | null {
 		if (label) parts.push(label);
 	}
 	if (s.freeTextValue !== null) parts.push(s.freeTextValue);
-	return formatAnswer(parts);
+	return formatAnswer(parts, s.commentValue);
 }
 
 /**

package/src/types.ts

@@ -10,6 +10,7 @@ export const SPLIT_PANE_MIN_WIDTH = 84;
 export const SPLIT_PANE_SEPARATOR = " │ ";
 export const SPLIT_PANE_LEFT_MIN = 32;
 export const SPLIT_PANE_RIGHT_MIN = 28;
+export const ANSWER_COMMENT_SEPARATOR = " — "; // 答案内联评论分隔符（4.0.1 restore，见 .changeset/restore-ask-user-comment.md）
 
 // ── Input schema（LLM 调用参数） ─────────────────────
 // description 用英文：这些字符串会进 LLM 的 tool schema，英文更利于模型理解。
@@ -46,6 +47,9 @@ export const QuestionSchema = Type.Object({
 	multiSelect: Type.Optional(
 		Type.Boolean({ description: "Default false. Set true only when more than one option can validly apply simultaneously; otherwise leave false for a single best answer." }),
 	),
+	allowComment: Type.Optional(
+		Type.Boolean({ description: "Default false. Set true to let the user append a short free-text comment after selecting (e.g. to note a constraint). Restored in 4.0.1." }),
+	),
 });
 
 /**
@@ -119,7 +123,7 @@ export interface ThemeLike {
 }
 
 /** 单问题的交互模式 */
-export type QuestionMode = "options" | "freeform";
+export type QuestionMode = "options" | "freeform" | "comment";
 
 /** 单问题的交互状态（每问题一个实例） */
 export interface QuestionState {
@@ -136,6 +140,8 @@ export interface QuestionState {
 	/** freeform Esc 保存的未提交草稿；null=无草稿。
 	 *  与 freeTextValue（已提交答案）分离，避免放弃的草稿污染答案、触发 auto-confirm。 */
 	freeDraft: string | null;
+	/** 可选评论；null=未输入 */
+	commentValue: string | null;
 	/** 当前交互模式 */
 	mode: QuestionMode;
 	/** 编辑器草稿文本（每问题独立持有，进编辑器时预填、退出时清空） */
@@ -153,6 +159,7 @@ export function createQuestionState(): QuestionState {
 		confirmed: false,
 		freeTextValue: null,
 		freeDraft: null,
+		commentValue: null,
 		mode: "options",
 		draftText: "",
 		savedOptionsCursorIndex: 0,

package/src/validate.ts

@@ -72,12 +72,12 @@ export function validateInput(questions: InputQuestion[]): string | null {
 		}
 
 		// S3: 多问题时 header 唯一——重复 header 会导致 askUserKey 碰撞，
-		// 后一个 question 的 __other 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
+		// 后一个 question 的 __other/__comment 覆盖前一个（协议 helper 用 header 作 answers 读取 key）。
 		const seenHeaders = new Set<string>();
 		for (const q of questions) {
 			const h = q.header!.trim();
 			if (seenHeaders.has(h)) {
-				return `Duplicate header "${h}" in questions. Headers must be unique in multi-question mode — shared headers cause answer key collisions (one question's Other overwrites another's). Rephrase one header to differ.`;
+				return `Duplicate header "${h}" in questions. Headers must be unique in multi-question mode — shared headers cause answer key collisions (one question's Other/comment overwrites another's). Rephrase one header to differ.`;
 			}
 			seenHeaders.add(h);
 		}