@zhushanwen/pi-ask-user 0.2.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "0.2.0",
+  "version": "1.0.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",
@@ -37,11 +37,15 @@
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
-    "@sinclair/typebox": "*"
+    "@sinclair/typebox": "*",
+    "@zhushanwen/pi-subagent-workflow": "*"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-tui": {
       "optional": true
+    },
+    "@zhushanwen/pi-subagent-workflow": {
+      "optional": true
     }
   },
   "scripts": {

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

@@ -0,0 +1,286 @@
+// src/__tests__/channel-handler.test.ts
+//
+// Tests createAskUserChannelHandler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
+//
+// 覆盖：
+//   - 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/comment 四种答案形态）。
+//   - 取消（askUserInteract/custom 返回 null 或 cancelled）→ {cancelled: true}
+//   - 输入校验（channelPayload 缺失/无 questions）→ {cancelled: true}
+import type { AskUserQuestion } from "@xyz-agent/extension-protocol";
+import { describe, expect, it } from "vitest";
+
+import { createAskUserChannelHandler } from "../channel-handler";
+import type { Result } from "../types";
+
+// ── Mock ctx ───────────────────────────────────────────
+// RPC：ctx.ui.select 模拟前端回传的 proto answers（JSON.stringify(AskUserAnswers)）。
+// TUI：ctx.ui.custom 模拟 AskUserComponent 产出的内部 Result。
+type CtxMode = "tui" | "rpc";
+
+interface MockCtxOpts {
+	mode: CtxMode;
+	/** RPC：select 返回的 value（JSON.stringify 后的 proto answers）；undefined = 取消 */
+	selectResult?: string | undefined;
+	/** TUI：custom 返回的内部 Result；null = 用户取消 */
+	customResult?: Result | null;
+}
+
+function makeCtx(opts: MockCtxOpts): {
+	mode: CtxMode;
+	hasUI: boolean;
+	ui: {
+		select?: (title: string, options: string[], o?: { signal?: AbortSignal }) => Promise<string | undefined>;
+		custom: <T = void>(factory: unknown) => Promise<T>;
+	};
+} {
+	const { mode, selectResult, customResult } = opts;
+	const hasUI = true;
+	if (mode === "rpc") {
+		return {
+			mode,
+			hasUI,
+			ui: {
+				select: async (): Promise<string | undefined> => selectResult,
+				custom: async <T = void>(): Promise<T> => undefined as T,
+			},
+		};
+	}
+	// TUI
+	return {
+		mode,
+		hasUI,
+		ui: {
+			custom: async <T = void>(): Promise<T> => customResult as T,
+		},
+	};
+}
+
+// ── 样例 proto questions（handler 收到的格式） ──────────
+const singleProto: AskUserQuestion = {
+	question: "Which DB?",
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
+const multiProto: AskUserQuestion = {
+	question: "Which tools?",
+	header: "Tools",
+	multiSelect: true,
+	options: [
+		{ label: "A", value: "A" },
+		{ label: "B", value: "B" },
+		{ label: "C", value: "C" },
+	],
+};
+
+const commentProto: AskUserQuestion = {
+	question: "Which DB?",
+	allowComment: true,
+	options: [{ label: "Postgres", value: "Postgres" }, { label: "SQLite", value: "SQLite" }],
+};
+
+// ── Tests ───────────────────────────────────────────────
+
+describe("createAskUserChannelHandler", () => {
+	it("RPC: single-select proto answers → {value: JSON.stringify(answers)}", async () => {
+		// 前端回传 proto answers：{[key]: value}，key = question 全文（无 header）
+		const protoAnswers = { "Which DB?": "Postgres" };
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
+	});
+
+	it("RPC: multi-select proto answers (JSON array value) → 透传", async () => {
+		const protoAnswers = { Tools: JSON.stringify(["A", "C"]) };
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: JSON.stringify(protoAnswers) }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		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,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("TUI: internal Result single-select → 重新编码为 proto answers", async () => {
+		// 内部 Result.answers：key = question 全文，value = 选中 label
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		// 期望：proto answers { "Which DB?": "Postgres" }
+		expect(resp).toEqual({ value: JSON.stringify({ "Which DB?": "Postgres" }) });
+	});
+
+	it("TUI: multi-select internal Result → proto JSON array value", async () => {
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which tools?": "A, C" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [multiProto] } });
+		// 期望：key=header "Tools"，value = JSON.stringify(["A","C"])
+		expect(resp).toEqual({ value: JSON.stringify({ Tools: JSON.stringify(["A", "C"]) }) });
+	});
+
+	it("TUI: value≠label single-select → encodeTuiResultToProto 回查 proto option value（PR #85 #8 回归守护）", async () => {
+		// value≠label 是 #8 修复的核心场景：TUI 渲染用 label，但 proto 期望回传 option.value。
+		// 若 #8 修复回归（直接 push label），此测试会失败：返回 "显示名A" 而非 "val_a"。
+		const valueNeqLabelProto: AskUserQuestion = {
+			question: "选哪个?",
+			options: [
+				{ label: "显示名A", value: "val_a" },
+				{ label: "显示名B", value: "val_b" },
+			],
+		};
+		// 内部 Result.answers：用户在 TUI 选了"显示名A"（label）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "选哪个?": "显示名A" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [valueNeqLabelProto] } });
+		// 期望：proto answers 回查 value，返回 "val_a"（不是 label "显示名A"）
+		expect(resp).toEqual({ value: JSON.stringify({ "选哪个?": "val_a" }) });
+	});
+
+	it("TUI: value≠label multi-select → proto JSON 数组元素回查 value（PR #85 #8 回归守护）", async () => {
+		// 多选路径同样依赖 #8 修复：selected.push(opt?.value ?? t)，多选会 JSON.stringify 数组。
+		const valueNeqLabelMultiProto: AskUserQuestion = {
+			question: "选哪些?",
+			header: "Opts",
+			multiSelect: true,
+			options: [
+				{ label: "显示名A", value: "val_a" },
+				{ label: "显示名B", value: "val_b" },
+			],
+		};
+		const internalResult: Result = {
+			questions: [],
+			answers: { "选哪些?": "显示名A, 显示名B" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [valueNeqLabelMultiProto] } });
+		// 期望：多选 JSON 数组，每个元素回查 value（["val_a","val_b"]，不是 label）
+		expect(resp).toEqual({ value: JSON.stringify({ Opts: JSON.stringify(["val_a", "val_b"]) }) });
+	});
+
+	it("TUI: Other free text → ${key}__other", async () => {
+		// 内部 Result：selected label + Other 文本逗号拼接（与 getAnswerText 语义一致）
+		const internalResult: Result = {
+			questions: [],
+			answers: { "Which DB?": "Postgres, Custom DB" },
+			cancelled: false,
+		};
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "tui", customResult: internalResult }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({
+			value: JSON.stringify({ "Which DB?": "Postgres", "Which DB?__other": "Custom DB" }),
+		});
+	});
+
+	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,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("TUI: custom returns cancelled Result → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(
+			makeCtx({
+				mode: "tui",
+				customResult: { questions: [], answers: {}, cancelled: true },
+			}) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: channelPayload missing → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({});
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: questions empty array → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({ channelPayload: { questions: [] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: questions not an array → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		const resp = await handler({ channelPayload: { questions: "not-array" } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+
+	it("input: req is null/undefined → {cancelled: true}", async () => {
+		const handler = createAskUserChannelHandler(makeCtx({ mode: "rpc" }) as never);
+		expect(await handler(null)).toEqual({ cancelled: true });
+		expect(await handler(undefined)).toEqual({ cancelled: true });
+	});
+
+	it("RPC: allowCancel passed through to askUserInteract (default true)", async () => {
+		// allowCancel 默认 true：验证不抛错（select mock 返回 undefined=取消）
+		const handler = createAskUserChannelHandler(
+			makeCtx({ mode: "rpc", selectResult: undefined }) as never,
+		);
+		const resp = await handler({ channelPayload: { questions: [singleProto] } });
+		expect(resp).toEqual({ cancelled: true });
+	});
+});

package/src/__tests__/channel-registry-register.test.ts

@@ -0,0 +1,180 @@
+// src/__tests__/channel-registry-register.test.ts
+//
+// Tests registerAskUserChannelHandler：ask-user 侧的 globalThis Symbol 握手注册纯函数。
+//
+// 覆盖（PR #85 #M4 + #M5）：
+//   - 空 globalThis → 建 slot（仅 pending），handler 入 pending；**slot.registry === undefined**
+//     （M4 核心断言：ask-user 永不创建 registry 实例）
+//   - slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）
+//   - slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)，pending 不增长
+//   - 重复调用：registry 就绪时 register 多次（同名覆盖幂等）；未就绪时 pending.length 增长
+//   - version !== 1 → warn + 重建为新 slot，旧 pending 丢弃
+//
+// 隔离：每个用例前 Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY)。
+import { beforeEach,describe, expect, it, vi } from "vitest";
+
+import type { ChannelHandler } from "../channel-handler";
+import {
+	CHANNEL_HANDSHAKE_KEY,
+	type ChannelRegistryHandshake,
+	registerAskUserChannelHandler,
+} from "../channel-registry-register";
+
+// 拿到当前 slot（cast any 安全：测试控制 slot 写入，结构已知）
+function readSlot(): ChannelRegistryHandshake | undefined {
+	return Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as
+		| ChannelRegistryHandshake
+		| undefined;
+}
+
+/** 塞一个指定 version 的 slot（手动构造，绕过 registerAskUserChannelHandler）。 */
+function writeSlot(slot: ChannelRegistryHandshake): void {
+	Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
+}
+
+/** 用 spy 构造 mock registry：register 是 vi.fn，pending flush 时可断言调用。 */
+function makeMockRegistry(): {
+	register: ReturnType<typeof vi.fn>;
+	resolve: ReturnType<typeof vi.fn>;
+	list: ReturnType<typeof vi.fn>;
+} {
+	return {
+		register: vi.fn(),
+		resolve: vi.fn().mockReturnValue(undefined),
+		list: vi.fn().mockReturnValue([]),
+	};
+}
+
+// 占位 handler——测试只关心调用计数和参数，handler 实体不重要
+const noopHandler: ChannelHandler = async () => undefined;
+
+describe("registerAskUserChannelHandler", () => {
+	beforeEach(() => {
+		Reflect.deleteProperty(globalThis, CHANNEL_HANDSHAKE_KEY);
+	});
+
+	it("空 globalThis → 建 slot，handler 入 pending，slot.registry === undefined（M4 核心）", () => {
+		expect(readSlot()).toBeUndefined();
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		expect(slot).toBeDefined();
+		expect(slot!.version).toBe(1);
+		// M4 核心断言：ask-user 永不创建 registry 实例
+		expect(slot!.registry).toBeUndefined();
+		expect(slot!.pending).toHaveLength(1);
+		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: noopHandler });
+	});
+
+	it("slot 存在但 registry 未就绪 → push pending（registry 仍 undefined）", () => {
+		// 预置 slot：version=1，pending=[]，registry 缺失（模拟 subagent-workflow 尚未 session_start）
+		const preSlot: ChannelRegistryHandshake = { version: 1, pending: [] };
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		expect(slot).toBe(preSlot); // 同一对象，未重建
+		expect(slot!.registry).toBeUndefined();
+		expect(slot!.pending).toHaveLength(1);
+		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: noopHandler });
+	});
+
+	it("slot 存在且 registry 就绪 → 调 registry.register，pending 不增长", () => {
+		const mockRegistry = makeMockRegistry();
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: [],
+		};
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		expect(mockRegistry.register).toHaveBeenCalledWith("ask_user", noopHandler);
+		// pending 不增长（直接 register，不进队列）
+		expect(preSlot.pending).toHaveLength(0);
+	});
+
+	it("registry 就绪时重复 register → register 被调多次（同名覆盖幂等，pending 始终 0）", () => {
+		const mockRegistry = makeMockRegistry();
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: [],
+		};
+		writeSlot(preSlot);
+
+		const h1: ChannelHandler = async () => "a";
+		const h2: ChannelHandler = async () => "b";
+		registerAskUserChannelHandler(h1);
+		registerAskUserChannelHandler(h2);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(2);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(1, "ask_user", h1);
+		expect(mockRegistry.register).toHaveBeenNthCalledWith(2, "ask_user", h2);
+		expect(preSlot.pending).toHaveLength(0); // 幂等：不进 pending
+	});
+
+	it("registry 未就绪时多次 register → pending.length 增长（顺序保留）", () => {
+		// 第 1 次：空 globalThis → 建 slot + pending[0]
+		const h1: ChannelHandler = async () => "a";
+		registerAskUserChannelHandler(h1);
+		// 第 2 次：slot 已存在、registry 仍 undefined → pending[1]
+		const h2: ChannelHandler = async () => "b";
+		registerAskUserChannelHandler(h2);
+
+		const slot = readSlot();
+		expect(slot!.registry).toBeUndefined();
+		expect(slot!.pending).toHaveLength(2);
+		expect(slot!.pending[0]).toEqual({ channel: "ask_user", handler: h1 });
+		expect(slot!.pending[1]).toEqual({ channel: "ask_user", handler: h2 });
+	});
+
+	it("version !== 1 → warn + 重建为新 slot，旧 pending 丢弃", () => {
+		// 塞一个 version=2 的旧 slot（模拟未来协议升级 / 脏数据）
+		const spyWarn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		const legacyPending = [{ channel: "stale", handler: noopHandler }];
+		const legacySlot = {
+			version: 2 as const,
+			registry: makeMockRegistry() as unknown as ChannelRegistryHandshake["registry"],
+			pending: legacyPending,
+		};
+		writeSlot(legacySlot as unknown as ChannelRegistryHandshake);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		const slot = readSlot();
+		// 旧 slot 被替换（version 退回 1，pending 重置为仅含本次注册）
+		expect(slot).not.toBe(legacySlot);
+		expect(slot!.version).toBe(1);
+		expect(slot!.pending).toEqual([{ channel: "ask_user", handler: noopHandler }]);
+		// warn 被调用（包含 version mismatch 提示）
+		expect(spyWarn).toHaveBeenCalledTimes(1);
+		expect(spyWarn.mock.calls[0]![0]).toContain("version mismatch");
+
+		spyWarn.mockRestore();
+	});
+
+	it("registry 就绪但 slot 已预置 pending → 仍走 register 路径（pending 不被本函数消费）", () => {
+		// 边界：subagent-workflow flush 后理论上 pending 应为空，但若 flush 漏了，
+		// 新 handler 来时仍应直接 register（不消费遗留 pending——那是 subagent-workflow 的职责）。
+		const mockRegistry = makeMockRegistry();
+		const preExistingPending = [{ channel: "ask_user", handler: noopHandler }];
+		const preSlot: ChannelRegistryHandshake = {
+			version: 1,
+			registry: mockRegistry as unknown as ChannelRegistryHandshake["registry"],
+			pending: preExistingPending,
+		};
+		writeSlot(preSlot);
+
+		registerAskUserChannelHandler(noopHandler);
+
+		expect(mockRegistry.register).toHaveBeenCalledTimes(1);
+		// 遗留 pending 未被消费（长度不变）
+		expect(preSlot.pending).toHaveLength(1);
+		expect(preSlot.pending).toBe(preExistingPending);
+	});
+});

package/src/__tests__/e2e-harness.ts

@@ -16,6 +16,8 @@ interface PiShape {
 	registerTool(t: unknown): void;
 	getAllTools(): { name: string }[];
 	setActiveTools(names: string[]): void;
+	// session_start handler（factory 注册透传 channel 用）；测试不覆盖透传，空实现。
+	on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 
 export interface E2EApi {
@@ -48,6 +50,9 @@ export function makeE2E(questions: Question[], opts: E2EOptions = {}): E2EApi {
 		setActiveTools(names) {
 			this.activeTools = names;
 		},
+		on() {
+			// no-op：session_start handler（透传 channel 注册），测试不覆盖
+		},
 	};
 
 	factory(pi as never);

package/src/__tests__/e2e.test.ts

@@ -75,9 +75,9 @@ describe("E2E-3: single question + allowComment — Enter in comment skips", ()
 		expect(details.cancelled).toBe(false);
 		// 不含 " — " 分隔符
 		expect(details.answers["Which DB?"]).toBe("Postgres");
-			expect(details.answers["Which DB?"]).not.toContain("—");
-		});
+		expect(details.answers["Which DB?"]).not.toContain("—");
 	});
+});
 
 // ── E2E-4: 多问题提交 — 逐题选择后 Submit tab 提交（S-11）──────
 describe("E2E-4: multi-question submit — answer each then Submit tab", () => {

package/src/__tests__/index.test.ts

@@ -44,6 +44,9 @@ interface MockPi {
 	getAllTools(): { name: string }[];
 	activeTools?: string[] | null;
 	setActiveTools(names: string[]): void;
+	// session_start handler：factory 注册 ask_user channel handler 时调用（透传功能）。
+	// 测试不验证透传，提供空 on 让 factory 不抛错。
+	on(event: string, handler: (...args: unknown[]) => unknown): void;
 }
 
 /** Runs the factory, returns the captured registered tool. */
@@ -58,6 +61,10 @@ const getTool = (overrides: Partial<MockPi> = {}): RegisteredTool => {
 		setActiveTools(names) {
 			this.activeTools = names;
 		},
+		on() {
+			// no-op：session_start handler 注册透传 channel（subagent-workflow 可选），
+			// 测试不覆盖透传路径
+		},
 		...overrides,
 	};
 	factory(pi as never);
@@ -197,6 +204,24 @@ describe("execute — validation (FR-2 / AC-8 / AC-13)", () => {
 		);
 		expect(result.details.cancelled).toBe(true);
 	});
+
+	it("I-4b: string options (schema-relaxed) → execute → validateInput catches → isError + Correct hint", async () => {
+		// 端到端证明：schema 放宽（Union([OptionSchema, string])）后 string options
+		// 能穿过 TypeCompiler.Check、抵达 execute → validateInput 友好拦截。
+		// test-coverage reviewer 点名的“execute wiring 未测”缺口。
+		const tool = getTool();
+		const result = await tool.execute(
+			"id",
+			{ questions: [{ question: "Q", options: ["A", "B"] }] },
+			undefined,
+			undefined,
+			makeCtx(),
+		);
+		expect(result.isError).toBe(true);
+		expect(result.details.cancelled).toBe(true);
+		expect(result.content[0].text).toContain("not strings");
+		expect(result.content[0].text).toContain("Correct");
+	});
 });
 
 // ── I-5 ~ I-7: Headless（FR-8 / AC-7）──────────────────

package/src/__tests__/prompt-quality.test.ts

@@ -0,0 +1,95 @@
+// src/__tests__/prompt-quality.test.ts
+//
+// 提示词质量回归：ask_user tool 的 description 与 validate.ts 文案必须能让弱模型
+// 首次调用就用对参数形状，用错了也能拿到带 Correct 正例的纠正。
+//
+// 背景（系统性债务）：
+//  - description 缺 JSON 正例：弱模型最高频错误是把 options 当字符串数组传
+//    （"options":["A","B"] 而非 [{"label","description"}]）。
+//  - 条件必填（header）用 Type.Optional 表达，弱模型批量时漏 header。
+//  - schema 层 ajv 干报错先于 validate.ts 友好文案——故 InputSchema 故意放宽 options
+//    元素到 string，让误用能抵达 validateInput 的带正例纠正。
+//
+// 本测试用源码断言（读 .ts 文件文本）锁定这些约束，防止后续重构把正例/反例/调用信号
+// 删掉或弱化。读源码而非 import，避免 mock 链（index.ts 依赖 pi-tui/ExtensionAPI 等）。
+
+import { readFileSync } from "node:fs";
+import { dirname,join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const INDEX_SRC = readFileSync(join(__dirname, "../index.ts"), "utf-8");
+const VALIDATE_SRC = readFileSync(join(__dirname, "../validate.ts"), "utf-8");
+
+/** 提取 description: `...` 模板字符串的原始内容（模板内无反引号，匹配到闭合 `,）。 */
+function extractDescription(src: string): string {
+	const m = src.match(/description:\s*`([\s\S]*?)`,/);
+	if (!m) throw new Error("description template literal not found in index.ts");
+	return m[1];
+}
+
+const DESCRIPTION = extractDescription(INDEX_SRC);
+
+describe("ask_user description — 参数形状正例（B. 补正例）", () => {
+	it("含单问题 JSON 正例，options 为 {label, description} 对象数组", () => {
+		// 弱模型最高频错误是把 options 当字符串数组传；正例必须显式给出对象形态。
+		expect(DESCRIPTION).toContain('"options":[{"label"');
+		expect(DESCRIPTION).toContain('"question"');
+	});
+
+	it("含批量 JSON 正例，每个 question 带 header", () => {
+		// 批量模式下 header 是条件必填，正例必须展示 header 字段。
+		expect(DESCRIPTION).toContain('"header"');
+		// 批量正例含多个 question（questions 数组里至少两个 header）
+		const headerMatches = DESCRIPTION.match(/"header"/g) || [];
+		expect(headerMatches.length).toBeGreaterThanOrEqual(2);
+	});
+
+	it("正例里的 label 可带 (Recommended) 前缀（调用信号未被破坏）", () => {
+		expect(DESCRIPTION).toContain("(Recommended)");
+	});
+});
+
+describe("ask_user description — 参数结构反例（B. 补反例）", () => {
+	it("含 ≥2 条参数结构反例（string array / flatten / Other 等）", () => {
+		// 锁定关键反例措辞，防止后续精简掉。
+		const antiPatterns = [
+			"string array", // options 不能当字符串数组传
+			"Flatten", // 不能把字段铺到顶层（匹配 Flattening/Flatten）
+			"Other", // 不能手动加 Other
+		];
+		const hits = antiPatterns.filter((p) => DESCRIPTION.includes(p));
+		expect(hits.length).toBeGreaterThanOrEqual(2);
+	});
+});
+
+describe("ask_user description — 调用信号保留（不要破坏亮点）", () => {
+	it("保留 'Use ONLY when ALL hold' 调用门槛", () => {
+		// 这是 ask_user 写得比 subagent 原版好的调用信号引导，必须保留。
+		expect(DESCRIPTION).toContain("Use ONLY when");
+	});
+
+	it("保留 'Do NOT use' 边界段", () => {
+		expect(DESCRIPTION).toContain("Do NOT use");
+	});
+});
+
+describe("validate.ts — runtime 友好纠错（A. 带正例）", () => {
+	it("含 options 字符串元素检测（'objects, not strings'）", () => {
+		// schema 层已放宽让 string options 进到这里；validate 必须友好拦截。
+		expect(VALIDATE_SRC).toContain("objects, not strings");
+	});
+
+	it("options 字符串错误带 Correct 正例", () => {
+		// 友好文案必须给出最小可用形状，让弱模型直接抄。
+		expect(VALIDATE_SRC).toContain('Correct: "options":[{"label"');
+	});
+
+	it("header 缺失错误带 Correct 正例", () => {
+		// 多问题模式漏 header 是弱模型批量时的常见错误，纠正文案要带正例。
+		expect(VALIDATE_SRC).toContain("Correct: {\"header\"");
+	});
+});

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

@@ -1,7 +1,7 @@
 // src/__tests__/question-view.test.ts
 import { describe, expect, it } from "vitest";
 
-import { getSplitPaneWidths, renderQuestionView, type RenderContext } from "../question-view";
+import { getSplitPaneWidths, type RenderContext,renderQuestionView } from "../question-view";
 import { createQuestionState, type Question, type QuestionState } from "../types";
 import { stubTheme } from "./fixtures";
 

package/src/__tests__/sdk-contract.test.ts

@@ -10,8 +10,8 @@
 
 import { describe, expect, it } from "vitest";
 
-import { validateInput } from "../validate";
 import askUserExtension from "../index";
+import { validateInput } from "../validate";
 
 describe("ask-user SDK contract", () => {
 	it("default export is a function accepting ExtensionAPI", () => {

package/src/__tests__/validate.test.ts

@@ -1,7 +1,8 @@
 // src/__tests__/validate.test.ts
+import { Value } from "@sinclair/typebox/value";
 import { describe, expect, it } from "vitest";
 
-import { HEADER_MAX_CHARS, type Question } from "../types";
+import { HEADER_MAX_CHARS, InputSchema, type Question } from "../types";
 import { validateInput } from "../validate";
 
 const q = (overrides: Partial<Question> = {}): Question => ({
@@ -136,4 +137,67 @@ describe("validateInput", () => {
 	it("accepts header at exactly HEADER_MAX_CHARS (12)", () => {
 		expect(validateInput([q({ header: "123456789012" })])).toBeNull();
 	});
+
+	// V-17: options 元素是 string（弱模型最高频误用 "options":["A","B"]）→ 友好错误带 Correct 正例。
+	// schema 层已放宽让 string options 能进到这里（见 types.ts InputSchema），故可直接传 string[]。
+	it("rejects string option elements with a Correct example (weak-model misuse)", () => {
+		const result = validateInput([
+			{ question: "Which DB?", options: ["Postgres", "SQLite"] },
+		]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("objects, not strings");
+		expect(result).toContain('Correct: "options":[{"label"');
+	});
+
+	// V-18: 混合 [string, object] → 仍友好拦截第一个 string 元素
+	it("rejects mixed string/object options", () => {
+		const result = validateInput([
+			{ question: "Q", options: ["A", { label: "B" }] },
+		]);
+		expect(result).toContain("objects, not strings");
+	});
+
+	// V-19: header 缺失错误带 Correct 正例（A. runtime 友好纠错）
+	it("header-missing error includes a Correct example", () => {
+		const result = validateInput([
+			q({ question: "Q1", header: "H1" }),
+			q({ question: "Q2" }), // no header
+		]);
+		expect(result).toContain("Correct:");
+		expect(result).toContain('"header"');
+	});
+});
+
+// ── options 字符串「下沉」机制集成证明 ──────────────────
+// 目标（任务核心）：弱模型误用 "options":["A","B"] 不能被 schema 层干报错拦死，
+// 必须能进 validateInput 拿到带 Correct 正例的友好文案。Value.Check 是 Pi 运行时
+// TypeCompiler.Check 的等价校验（同一引擎），这里直接断言 schema 行为。
+describe("schema-vs-validate integration (options 字符串下沉)", () => {
+	it("string options PASS the schema layer (reach execute, not raw ajv error)", () => {
+		const malformed = {
+			questions: [{ question: "Which DB?", options: ["Postgres", "SQLite"] }],
+		};
+		expect(Value.Check(InputSchema, malformed)).toBe(true);
+	});
+
+	it("string options then caught by validateInput with a friendly Correct example", () => {
+		const result = validateInput([
+			{ question: "Which DB?", options: ["Postgres", "SQLite"] },
+		]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("objects, not strings");
+		expect(result).toContain('Correct: "options":[{"label"');
+	});
+
+	it("well-formed object options still pass schema AND validateInput", () => {
+		const wellFormed = {
+			questions: [
+				{ question: "Which DB?", options: [{ label: "A" }, { label: "B" }] },
+			],
+		};
+		expect(Value.Check(InputSchema, wellFormed)).toBe(true);
+		expect(
+			validateInput([{ question: "Which DB?", options: [{ label: "A" }, { label: "B" }] }]),
+		).toBeNull();
+	});
 });

package/src/channel-handler.ts

@@ -0,0 +1,215 @@
+// src/channel-handler.ts
+//
+// ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI 渲染。
+//
+// 设计（关键决策）：askUserInteract（@xyz-agent/extension-protocol）只在 RPC 模式可用
+// （内部 isGuiCapable 检查 mode==='rpc'，TUI 下抛错）。所以 handler 按 ctx.mode 分流：
+//   - RPC：转发器——调 askUserInteract(guiCtx, protoQuestions)，复用 select 通道 +
+//     ASK_USER_MARKER 契约，主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，
+//     不循环）。返回 {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 — 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 得到）。
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+	type AskUserAnswers,
+	askUserInteract,
+	type AskUserQuestion,
+} from "@xyz-agent/extension-protocol";
+
+import { AskUserComponent } from "./component";
+import { ANSWER_COMMENT_SEPARATOR, type Option, type Question, type Result, type ThemeLike } from "./types";
+
+/**
+ * channel handler 签名——与 subagent-workflow 的 UiChannelRegistry.ChannelHandler 一致
+ *（(req: unknown) => Promise<unknown>）。本文件不静态 import subagent-workflow（它是可选
+ * peerDep，未安装时静态 import 会导致整个 ask-user 加载失败）；注册时通过动态 import 拿
+ * registry，handler 签名用本地等价类型，运行时结构兼容。
+ */
+export type ChannelHandler = (req: unknown) => Promise<unknown>;
+
+/** handler 返回给 subagent-workflow 的 UiResponse 形状（dialog-queue.ts 定义）。
+ *  - {value}: select 的回传值（子进程 JSON.parse(value) 得 answers）
+ *  - {cancelled}: 用户取消 / 子进程 close / handler 抛错 */
+type ChannelResponse = { value: string } | { cancelled: true };
+
+/** handler 收到的 req 形状收窄（ChannelHandler 签名是 unknown，按形状 as 收窄）。
+ *  channelPayload 由 subagent-workflow parseChannel 填充。 */
+interface ChannelRequest {
+	channelPayload?: { questions?: AskUserQuestion[]; allowCancel?: boolean };
+}
+
+/** proto AskUserQuestion → 内部 Question（AskUserComponent 接受内部格式）。
+ *  proto options 可选（无 options=纯自由文本），内部 options 必填——无 options 的 protoQuestion
+ *  这里仍映射出 options（从子进程 ask-user 调用方保证 protoQuestions 总带 options；若缺则返 [] 由调用方判）。 */
+function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[] {
+	return protoQuestions.map((pq: AskUserQuestion): Question => {
+		const opts: Option[] = (pq.options ?? []).map((o: { label: string; description?: string }): Option => ({
+			label: o.label,
+			...(o.description !== undefined ? { description: o.description } : {}),
+		}));
+		return {
+			question: pq.question,
+			...(pq.header !== undefined ? { header: pq.header } : {}),
+			...(pq.context !== undefined ? { context: pq.context } : {}),
+			options: opts,
+			...(pq.multiSelect !== undefined ? { multiSelect: pq.multiSelect } : {}),
+			...(pq.allowComment !== undefined ? { allowComment: pq.allowComment } : {}),
+		};
+	});
+}
+
+/**
+ * 把 TUI 路径产出的内部 Result.answers 重新编码为 proto AskUserAnswers。
+ *
+ * 内部 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 自由文本；comment 由 ANSWER_COMMENT_SEPARATOR 切出。
+ */
+function encodeTuiResultToProto(
+	protoQuestions: AskUserQuestion[],
+	result: Result,
+): AskUserAnswers {
+	const answers: AskUserAnswers = {};
+	for (const pq of protoQuestions) {
+		const key = pq.header ?? pq.question;
+		const internalText = result.answers[pq.question];
+		if (internalText === undefined) continue; // 该问题未答（protoAnswersToResult 也跳过未答）
+
+		// 已知选项 label 集合（protoQuestion.options 的 label/value 都作候选——value 缺失时用 label）
+		const knownLabels = new Set<string>();
+		for (const o of pq.options ?? []) {
+			knownLabels.add(o.label);
+			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 = body.split(/[,，]/).map((t: string) => t.trim()).filter((t: string) => t !== "");
+		const selected: string[] = [];
+		const otherTokens: string[] = [];
+		for (const t of tokens) {
+			if (knownLabels.has(t)) {
+				// 回查 proto option 的 value（PR #85 #8）：TUI 渲染用 label，但 RPC 路径
+				// （askUserInteract）回传的是 option.value。value≠label 时若直接 push label，
+				// TUI/RPC 两条路径产出分裂。value 缺失时 fallback label（保持 ask-user 自身
+				// toProtoQuestions 的 value=label 语义，以及历史行为）。
+				const opt = pq.options?.find(o => o.label === t || o.value === t);
+				selected.push(opt?.value ?? t);
+			} else {
+				otherTokens.push(t);
+			}
+		}
+		const otherText = otherTokens.join(", ") || undefined;
+
+		// 主 key：单选 = 首个选中 value；多选 = JSON 数组（即便为空也写入，与 RPC 契约一致）
+		if (pq.multiSelect) {
+			answers[key] = JSON.stringify(selected);
+		} else if (selected.length > 0) {
+			answers[key] = selected[0]!;
+		}
+
+		if (otherText) answers[`${key}__other`] = otherText;
+		if (comment) answers[`${key}__comment`] = comment;
+	}
+	return answers;
+}
+
+/** TUI 路径：ctx.ui.custom + AskUserComponent 渲染，返回 proto answers 或 null（取消）。
+ *
+ *  allowCancel 透传预留（PR #85 #12）：AskUserComponent 构造函数暂未接收 allowCancel，
+ *  Esc 取消始终可用（component.ts 的 escBackOrConfirm / cancel 无条件生效）。待组件升级
+ *  支持禁用 Esc 后，应把 allowCancel 下传给 AskUserComponent 构造函数。当前 allowCancel=false
+ *  时 TUI 与 RPC 路径仍有分裂，但 handler 层已不再吞掉 allowCancel（修复分裂的第一步）。 */
+async function runTuiProtoInteraction(
+	protoQuestions: AskUserQuestion[],
+	ctx: ExtensionContext,
+	allowCancel: boolean,
+): Promise<AskUserAnswers | null> {
+	const questions = protoToInternalQuestions(protoQuestions);
+	// 预留：组件升级后此处改为 new AskUserComponent(questions, tui, theme, done, allowCancel)
+	void allowCancel;
+	const result = await ctx.ui.custom<Result | null>(
+		(tui: unknown, theme: unknown, _kb: unknown, done: (r: Result | null) => void) => {
+			const comp = new AskUserComponent(
+				questions,
+				tui as { requestRender(): void },
+				theme as ThemeLike,
+				done,
+			);
+			return comp;
+		},
+	);
+	if (result === null || result.cancelled) return null;
+	return encodeTuiResultToProto(protoQuestions, result);
+}
+
+/**
+ * 创建 ask_user channel handler。
+ *
+ * @param ctx 主进程 ExtensionContext（session_start 时注入）
+ * @returns ChannelHandler——req.channelPayload = {questions, allowCancel}（proto 格式），
+ *          返回 {value: JSON.stringify(answers)} 或 {cancelled: true}
+ */
+export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandler {
+	return async (req: unknown): Promise<unknown> => {
+		// req 正常是 subagent-workflow 构造的 UiRequest 对象；防御性收窄 null/undefined/
+		// 非 object（handler 抛错会被 dialog-queue 兜底为 {cancelled:true}，但这里直接返回更干净）
+		if (req === null || typeof req !== "object") {
+			return { cancelled: true } satisfies ChannelResponse;
+		}
+		const r = req as ChannelRequest;
+		const payload = r.channelPayload;
+		if (!payload || !Array.isArray(payload.questions) || payload.questions.length === 0) {
+			return { cancelled: true } satisfies ChannelResponse;
+		}
+		const { questions, allowCancel } = payload;
+
+		// 按 ctx.mode 分流（PR #85 #13 / #M6）：rpc 走 askUserInteract（select 通道+sidecar），
+		// 其余（tui/json/print/undefined）走 ctx.ui.custom+AskUserComponent。
+		// 用 ctx.mode === "rpc" 二值判定（与 index.ts execute 的 useRpc 判定一致）；
+		// 三值分类不需要——handler 只关心「rpc 转发」vs「TUI 内部渲染」两条路径。
+		const answers =
+			ctx.mode === "rpc"
+				? await runRpcForward(questions, ctx, allowCancel ?? true)
+				: await runTuiProtoInteraction(questions, ctx, allowCancel ?? true);
+
+		if (answers === null) return { cancelled: true } satisfies ChannelResponse;
+		return { value: JSON.stringify(answers) } satisfies ChannelResponse;
+	};
+}
+
+/** RPC 转发器：主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，不循环）。
+ *  完整复用 askUserInteract 的 encode/decode 契约。 */
+async function runRpcForward(
+	questions: AskUserQuestion[],
+	ctx: ExtensionContext,
+	allowCancel: boolean,
+): Promise<AskUserAnswers | null> {
+	const guiCtx = {
+		mode: ctx.mode,
+		hasUI: ctx.hasUI,
+		ui: { select: ctx.ui.select.bind(ctx.ui) },
+	};
+	return askUserInteract(guiCtx, questions, { allowCancel });
+}

package/src/channel-registry-register.ts

@@ -0,0 +1,108 @@
+// src/channel-registry-register.ts
+//
+// ask-user 侧的 channel handler 握手注册纯函数。
+//
+// 设计动机（PR #85 #M4 修复）：原实现 ask-user 先 session_start 时会自建简化 Map-based
+// registry 占据 canonical 槽位，劫持 subagent-workflow 后续 getOrCreateChannelRegistry 拿到的
+// 实例（subagent-workflow 的 createUiChannelRegistry 才是 canonical——它带排队、dialog 队列
+// 等完整能力）。修复后的握手协议改为「带 version 的 slot」：
+//   - subagent-workflow session_start 时往 slot 写 {version, registry, pending:[]}
+//   - ask-user session_start 时只读 slot，registry 就绪则调 registry.register，未就绪则 push pending
+//   - ask-user **永不**创建 registry 实例，**永不**写 slot.registry
+//
+// 这是 ask-user 侧的注册入口；canonical registry 由 subagent-workflow 创建。本模块永不创建
+// registry 实例——仅往 slot 写 pending 或调 slot.registry.register。
+
+import type { ChannelHandler } from "./channel-handler";
+
+/**
+ * 进程级 channel registry 握手的 globalThis key（Symbol.for 跨模块共享）。
+ *
+ * ⚠️ 必须与 extensions/subagent-workflow/src/execution/channel-registry-access.ts 的字面量
+ * 完全一致——两边用同一字符串确保拿到同一 slot 实例。改名必须两侧同步。
+ */
+export const CHANNEL_HANDSHAKE_KEY = Symbol.for(
+	"@zhushanwen/pi-subagents.channelHandshake",
+);
+
+/** 握手协议版本号。读写 slot 时校验 version !== 1 视为不兼容（warn + 重建 slot）。 */
+const HANDSHAKE_VERSION = 1;
+
+/** channel 名称（ask-user 固定注册 "ask_user"）。 */
+const ASK_USER_CHANNEL = "ask_user";
+
+/**
+ * channel registry 的本地等价接口（与 subagent-workflow UiChannelRegistry 形状一致）。
+ * 本模块不静态 import subagent-workflow（它是可选 peerDep，未安装时静态 import 会致整个
+ * ask-user 加载失败）；运行时结构兼容即可。
+ */
+interface ChannelRegistry {
+	register(channel: string, handler: ChannelHandler): void;
+	resolve(channel: string): ChannelHandler | undefined;
+	list(): string[];
+}
+
+/** pending 队列元素：channel + handler。subagent-workflow flush 时遍历调用 registry.register。 */
+interface PendingEntry {
+	channel: string;
+	handler: ChannelHandler;
+}
+
+/**
+ * globalThis slot 的形状。
+ *
+ * - `version`：握手协议版本（运行时校验，不兼容则丢弃重建）
+ * - `registry`：canonical 实例，**仅 subagent-workflow 创建**；缺失表示 registry 未就绪，
+ *   ask-user 把 handler 入 pending 队列等待 flush
+ * - `pending`：未消费的注册请求（registry 就绪后由 subagent-workflow 一次性 flush）
+ */
+export interface ChannelRegistryHandshake {
+	version: 1;
+	registry?: ChannelRegistry;
+	pending: PendingEntry[];
+}
+
+/** 从 globalThis 读 slot；version !== 1 视为无 slot（返回 undefined）。 */
+function readSlot(): ChannelRegistryHandshake | undefined {
+	const slot = Reflect.get(globalThis, CHANNEL_HANDSHAKE_KEY) as
+		| ChannelRegistryHandshake
+		| undefined;
+	if (slot === undefined) return undefined;
+	if (slot.version !== HANDSHAKE_VERSION) {
+		console.warn(
+			`[ask-user] channel handshake slot version mismatch: expected ${HANDSHAKE_VERSION}, got ${slot.version}; discarding and rebuilding slot`,
+		);
+		return undefined;
+	}
+	return slot;
+}
+
+/** 在 globalThis 上建一个空 slot（仅 pending，无 registry——ask-user 永不建 registry）。 */
+function ensureSlot(): ChannelRegistryHandshake {
+	const slot: ChannelRegistryHandshake = { version: HANDSHAKE_VERSION, pending: [] };
+	Reflect.set(globalThis, CHANNEL_HANDSHAKE_KEY, slot);
+	return slot;
+}
+
+/**
+ * 注册 ask_user channel handler 到 globalThis 握手 slot。
+ *
+ * 行为：
+ *   1. slot 不存在或 version 不兼容 → 建 slot（仅 pending），handler 入 pending；
+ *      **slot.registry 保持 undefined**（M4 核心：ask-user 不建 registry）
+ *   2. slot 存在但 registry 未就绪 → handler 入 pending
+ *   3. slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)
+ *
+ * 多次调用幂等：registry 就绪时 register 同名覆盖；未就绪时 pending.length 增长
+ * （subagent-workflow flush 时一次性消费所有 pending）。
+ *
+ * @param handler ask_user channel handler（createAskUserChannelHandler 产出）
+ */
+export function registerAskUserChannelHandler(handler: ChannelHandler): void {
+	const slot = readSlot() ?? ensureSlot();
+	if (slot.registry !== undefined) {
+		slot.registry.register(ASK_USER_CHANNEL, handler);
+		return;
+	}
+	slot.pending.push({ channel: ASK_USER_CHANNEL, handler });
+}

package/src/index.ts

@@ -11,8 +11,10 @@ import {
 	getAskUserOther,
 } from "@xyz-agent/extension-protocol";
 
-import { AskUserComponent } from "./component";
 import { formatAnswer, parseAnswerParts } from "./answer-format";
+import { createAskUserChannelHandler } from "./channel-handler";
+import { registerAskUserChannelHandler } from "./channel-registry-register";
+import { AskUserComponent } from "./component";
 import {
 	type AskUserDetails,
 	type ErrorDetails,
@@ -208,6 +210,22 @@ async function runRpcInteraction(
 }
 
 export default function (pi: ExtensionAPI): void {
+	// 注册 ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
+	//
+	// 跨扩展握手协议（PR #85 #M4）：通过 globalThis Symbol.for 约定 slot 形状
+	//（CHANNEL_HANDSHAKE_KEY，与 subagent-workflow/src/execution/channel-registry-access.ts
+	// 用同一字符串 key），不依赖 dynamic import npm 包名（两个扩展都通过
+	// ~/.pi/agent/extensions/ symlink 加载，互相之间无法用 npm 包名 import）。
+	//
+	// 握手流程（registerAskUserChannelHandler 内部完成）：
+	//   1. 读 slot；不存在或 version 不兼容 → 建 slot（仅 pending，**永不建 registry**）
+	//   2. slot.registry 就绪（subagent-workflow 先到）→ 直接调 registry.register
+	//   3. slot.registry 未就绪 → handler 入 pending，等 subagent-workflow flush
+	// ask-user 永不创建 registry 实例——canonical registry 仅 subagent-workflow 创建。
+	pi.on("session_start", (_event, ctx) => {
+		registerAskUserChannelHandler(createAskUserChannelHandler(ctx));
+	});
+
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",
@@ -215,7 +233,18 @@ export default function (pi: ExtensionAPI): void {
 
 Do NOT use this tool to outsource judgment you should make — if you can form a defensible recommendation from the codebase, proceed and state your choice. Do NOT use for trivia answerable by reading code/docs, or for simple confirmations ("I'll delete X") where plain text suffices. You cannot use this tool to collect free-form requirements, long-form feedback, or multi-paragraph input — it returns short selections only.
 
-If you recommend an option, prefix its label with "(Recommended)" and list it first. For structured multi-option decisions, prefer this tool over plain-text questions; for everything else, reply in plain text.`,
+If you recommend an option, prefix its label with "(Recommended)" and list it first. For structured multi-option decisions, prefer this tool over plain-text questions; for everything else, reply in plain text.
+
+Examples:
+{"questions":[{"question":"Which DB?","context":"Need ACID + JSON columns.","options":[{"label":"(Recommended) Postgres","description":"Mature, strong consistency."},{"label":"SQLite","description":"Zero-ops, embedded."}]}]}
+
+{"questions":[{"header":"DB","question":"Which database?","options":[{"label":"Postgres","description":"..."},{"label":"SQLite","description":"..."}]},{"header":"Region","question":"Which region?","options":[{"label":"us-east-1","description":"..."},{"label":"eu-west-1","description":"..."}]}]}
+
+Don't:
+- Passing options as a string array ("options":["A","B"]) — each option must be {"label","description"}.
+- Forgetting header in multi-question mode (questions.length > 1).
+- Flattening question/header/options to the top level — wrap them in questions:[...].
+- Including an "Other" option — it is added automatically.`,
 		promptSnippet:
 			"Ask the user structured clarifying questions with options — only when you cannot resolve the ambiguity yourself",
 		promptGuidelines: [
@@ -235,9 +264,11 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 			_onUpdate: AgentToolUpdateCallback<AskUserDetails> | undefined,
 			ctx: ExtensionContext,
 		): Promise<ExecuteResult> {
-			const questions = params.questions;
+			const questions = params.questions as Question[];
 
-			// 1. 参数校验（spec FR-2）
+			// 1. 参数校验（spec FR-2）。validateInput 接收宽松 InputQuestion[]：
+			// options 可能含 string 误用（schema 已故意放宽以抵达这里的友好文案），
+			// validateInput 会先拦截 string options 再跑其余校验。通过后 questions 已是干净 Question[]。
 			const validationError = validateInput(questions);
 			if (validationError) {
 				return cancelledResult(questions, `Error: ${validationError}`, true);
@@ -308,7 +339,8 @@ If you recommend an option, prefix its label with "(Recommended)" and list it fi
 		},
 
 		renderCall(args: Static<typeof InputSchema>, theme: ThemeLike) {
-			const questions: Question[] = args.questions ?? [];
+			// args 来自 LLM 原始入参（options 可能是 string），只读 header/question 不碰 options。
+			const questions = (args.questions ?? []) as Question[];
 			const topics = questions.map((q) => q.header ?? truncateToWidth(q.question, HEADER_MAX_CHARS)).join(", ");
 			return new TruncatedText(
 				theme.fg("toolTitle", theme.bold("ask_user ")) + theme.fg("muted", topics),

package/src/types.ts

@@ -52,17 +52,47 @@ export const QuestionSchema = Type.Object({
 	),
 });
 
+/**
+ * LLM-facing input schema (宽松版 options 元素)。
+ *
+ * options 元素故意放宽为 `OptionSchema | string`：弱模型最高频误用是把 options
+ * 当字符串数组传（`"options":["A","B"]`）。严格 schema 会让 Pi 运行时的 typebox
+ * TypeCompiler.Check 直接拦截（干报错 "must be object"），根本进不了 validateInput
+ * 的友好文案。这里放宽让 string 元素通过 schema 层、抵达 validateInput，由它返回带
+ * Correct 正例的纠正错误（runtime 友好纠错）。
+ *
+ * 字段描述复用 QuestionSchema.properties（只覆盖 options 数组元素类型），避免描述
+ * 双份维护。Static 派生的 InputQuestion.options 是 `(Option | string)[]`，让
+ * validateInput 里的 `typeof opt === "string"` 检查在 TS 层 sound（而非死分支）。
+ * 通过 validateInput 后，运行时已保证无 string，index.ts 以 `as Question[]` 收窄使用。
+ */
+const inputOptionElement = Type.Union([OptionSchema, Type.String()]);
+
 export const InputSchema = Type.Object({
-	questions: Type.Array(QuestionSchema, {
-		minItems: 1,
-		maxItems: 4,
-		description: "1-4 questions, each a single decision. Batch only related decisions that the user should resolve together; otherwise ask the most important one alone.",
-	}),
+	questions: Type.Array(
+		Type.Object({
+			...QuestionSchema.properties,
+			options: Type.Array(inputOptionElement, {
+				minItems: 2,
+				maxItems: 4,
+				description:
+					"2-4 mutually exclusive options. Each must be a {label, description} OBJECT, never a bare string; do NOT include an 'Other' option — it is added automatically.",
+			}),
+		}),
+		{
+			minItems: 1,
+			maxItems: 4,
+			description: "1-4 questions, each a single decision. Batch only related decisions that the user should resolve together; otherwise ask the most important one alone.",
+		},
+	),
 });
 
 // ── 派生类型 ─────────────────────────────────────────
 export type Option = Static<typeof OptionSchema>;
+/** 内部使用的严格 question 形状（options 为干净 Option[]）。validateInput 通过后使用。 */
 export type Question = Static<typeof QuestionSchema>;
+/** LLM 入参 question 形状：options 可能含 string 误用，validateInput 负责友好拦截。 */
+export type InputQuestion = Static<typeof InputSchema>["questions"][number];
 
 // ── Result schema（details，renderResult 数据源） ─────
 export const ResultSchema = Type.Object({

package/src/validate.ts

@@ -1,20 +1,29 @@
 // src/validate.ts
-import { HEADER_MAX_CHARS, type Question, QUESTION_MAX_CHARS } from "./types";
+import { HEADER_MAX_CHARS, type InputQuestion, QUESTION_MAX_CHARS } from "./types";
 
 /** 控制字符（含 \n \r \t 等）：question 文本禁止包含，避免 answers key 含不可见字符（spec FR-2） */
 const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
 
+/** 错误消息里 question/header 文本预览的截断长度（避免长文本撑爆错误消息）。 */
+const ERROR_PREVIEW_CHARS = 20;
+
 /**
  * 校验输入参数。通过返回 null，失败返回错误消息字符串。
+ *
+ * 入参类型是宽松的 InputQuestion[]（options 元素可能是 string 误用）——见 types.ts
+ * InputSchema 注释。Pi 运行时只放宽到让 string options 能进到这里被友好拦截；这里先
+ * 预检 string options，再跑原有结构/语义校验。
+ *
  * 校验项（spec FR-2）：
+ * - options 元素必须是 {label, description} 对象，不能是 string（弱模型高频误用）
  * - question 文本长度上限与无控制字符（保证 answers key 有界、可预测）
  * - question 文本在数组内唯一
  * - 同问题内 option label 唯一
  * - 多问题（questions.length > 1）时每个 question 必须有非空 header
  *
- * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改）。
+ * 错误消息面向 LLM：除描述违规外，附带一句修复指引（如何改），对结构误用附 Correct 正例。
  */
-export function validateInput(questions: Question[]): string | null {
+export function validateInput(questions: InputQuestion[]): string | null {
 	const seenQuestions = new Set<string>();
 
 	for (const q of questions) {
@@ -22,11 +31,11 @@ export function validateInput(questions: Question[]): string | null {
 
 		// 1a. question 文本长度上限（key 有界）
 		if (qt.length > QUESTION_MAX_CHARS) {
-			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, 20)}...". Shorten it to a single concise decision; move extra context into the context field.`;
+			return `Question text exceeds ${QUESTION_MAX_CHARS} chars: "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Shorten it to a single concise decision; move extra context into the context field.`;
 		}
 		// 1b. question 文本无控制字符（key 可预测，不影响下游渲染/解析）
 		if (CONTROL_CHAR_RE.test(qt)) {
-			return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, 20)}...". Use plain single-line text; split multi-part questions into separate entries.`;
+			return `Question text must not contain control characters (incl. newlines): "${qt.slice(0, ERROR_PREVIEW_CHARS)}...". Use plain single-line text; split multi-part questions into separate entries.`;
 		}
 
 		// 1c. question 文本唯一
@@ -35,14 +44,20 @@ export function validateInput(questions: Question[]): string | null {
 		}
 		seenQuestions.add(qt);
 
-		// 2. option label 唯一且非空（空 label 会污染 details.answers 的值）
+		// 2. option 元素必须是 {label, description} 对象，不能是 string。
+		//    弱模型最高频误用："options":["A","B"]。schema 层已放宽让 string 进来，这里友好拦截
+		//    （InputQuestion.options 是 (Option | string)[]，typeof 收窄后 opt 为 Option）。
 		const seenLabels = new Set<string>();
 		for (const opt of q.options) {
+			if (typeof opt === "string") {
+				return `Options for question "${qt}" must be an array of {label, description} objects, not strings. Correct: "options":[{"label":"A","description":"..."},{"label":"B","description":"..."}]`;
+			}
+			// opt 已收窄为 Option
 			if (opt.label.trim() === "") {
-				return `Option label must not be empty in question "${q.question}". Give every option a distinct, descriptive label.`;
+				return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
 			}
 			if (seenLabels.has(opt.label)) {
-				return `Duplicate option label "${opt.label}" in question "${q.question}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
+				return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
 			}
 			seenLabels.add(opt.label);
 		}
@@ -52,7 +67,7 @@ export function validateInput(questions: Question[]): string | null {
 	if (questions.length > 1) {
 		for (const q of questions) {
 			if (!q.header || q.header.trim() === "") {
-				return `Question "${q.question}" requires a non-empty header in multi-question mode (it labels the tab). Provide a header of <=12 chars.`;
+				return `Question "${q.question}" requires a non-empty header in multi-question mode (it labels the tab). Provide a header of <=12 chars. Correct: {"header":"DB","question":"...","options":[{"label":"...","description":"..."}]}`;
 			}
 		}
 
@@ -72,7 +87,7 @@ export function validateInput(questions: Question[]): string | null {
 	//    这里提前拒绝，让 LLM 拿到可修复错误而非残缺 UI（兑现 schema description 的 ≤12 契约）。
 	for (const q of questions) {
 		if (q.header !== undefined && q.header.length > HEADER_MAX_CHARS) {
-			return `Header exceeds ${HEADER_MAX_CHARS} chars: "${q.header.slice(0, 20)}..." in question "${q.question}". Shorten it; longer headers are truncated in the tab bar.`;
+			return `Header exceeds ${HEADER_MAX_CHARS} chars: "${q.header.slice(0, ERROR_PREVIEW_CHARS)}..." in question "${q.question}". Shorten it; longer headers are truncated in the tab bar.`;
 		}
 	}