@zhushanwen/pi-ask-user 7.0.15 → 7.1.0

package/ARCHITECTURE.md

@@ -69,14 +69,14 @@ Encoding is **one-way** — the old `parseAnswerParts` text reverse-parsing was
 
 | Step | Check | Returns | Why this order |
 |------|-------|---------|----------------|
-| 1 | `validateInput(questions)` | `isError:true` + fix hint | Pure function, no side effects — cheapest gate. Reject before any UI/state work. |
-| 2 | `!ctx.hasUI` (headless) | `isError:true` + **`setActiveTools` removes ask_user** | Must run before the agent can retry. Physically removing the tool breaks a function-calling retry loop that plain `isError` cannot. |
+| 1 | `validateInput(questions)` | `throw` (Pi marks `isError:true`, empty `details`) + fix hint | Pure function, no side effects — cheapest gate. Reject before any UI/state work. |
+| 2 | `ctx.mode !== "tui" && ctx.mode !== "rpc"` (headless) | `throw` + **`setActiveTools` removes ask_user** | Must run before the agent can retry. Physically removing the tool breaks a function-calling retry loop that a thrown error cannot. |
 | 3 | `signal?.aborted` | `cancelled:true` | O(1) short-circuit before the expensive blocking `ctx.ui.custom` call. |
-| 4 | `try { ctx.ui.custom(...) } catch` | `isError:true` + `{ error }` | `ctx.ui.custom` is the only call that runs user interaction / editor construction / theme reads — the largest blast radius, so it is the only thing wrapped. |
+| 4 | `try { ctx.ui.custom(...) } catch` | `throw` (Pi marks `isError:true`, empty `details`) | `ctx.ui.custom` is the only call that runs user interaction / editor construction / theme reads — the largest blast radius, so it is the only thing wrapped. |
 | 5 | `result === null \|\| result.cancelled` | `cancelled:true` | Component resolved to cancel. |
 | 6 | normal | `{ answers }` | Compose the summary. |
 
-**The order is load-bearing**: swapping 1↔2 wastes a UI check on invalid params; swapping 2↔3 lets an aborted agent enter a blocking UI; moving 4's try/catch wider catches nothing extra. The headless branch's `setActiveTools` is the key insight — returning `isError` alone does not stop an LLM from calling the tool again in the same turn, so the tool is removed from the session's active set and the error text says "do not retry".
+**The order is load-bearing**: swapping 1↔2 wastes a UI check on invalid params; swapping 2↔3 lets an aborted agent enter a blocking UI; moving 4's try/catch wider catches nothing extra. Business outcomes (answers / cancellation) are returned as normal results — only validation failures and unexpected exceptions `throw` (Pi converts a throw into an `isError:true` tool result with empty `details`). The headless branch's `setActiveTools` is the key insight — even an `isError` tool result does not stop an LLM from calling the tool again in the same turn, so the tool is removed from the session's active set and the error text says "do not retry".
 
 ## `QuestionState` machine
 
@@ -122,7 +122,7 @@ If you add a new path that changes the answer set, audit both directions of this
 
 ### `autoConfirmIfAnswered` trigger
 
-Called only from `gotoTab()` — when the user navigates between tabs via Tab/Shift+Tab without pressing Enter. It promotes an implicitly-answered tab (toggled but not confirmed) to `confirmed`. A Tab navigation intent should not force a confirm prompt — only the Enter path confirms via `afterConfirm`.
+Called only from `gotoTab()` — when the user navigates between tabs via `←/→` (Tab is not a tab-navigation key: on the Submit tab it toggles Submit/Cancel focus, and `Shift+Tab` is deliberately unused because Pi's global `app.thinking.cycle` intercepts it). It promotes an implicitly-answered tab (toggled but not confirmed) to `confirmed`. A navigation intent should not force a confirm prompt — only the Enter path confirms via `afterConfirm`.
 
 ## Race guards
 
@@ -132,7 +132,7 @@ Three independent guards protect against three different races. They are dimensi
 |-------|------|----------|----------|-----------|
 | `_resolved` | `boolean` field | `component.ts` | **Double `done()`**: user already submitted/cancelled, then a signal-abort listener or a late keypress fires `done` again → Pi receives two resolves. | `submit()`/`cancel()` set `_resolved = true` before `done(...)`; **both `handleInput` and `cancel()` itself early-return if already set** — so a signal-abort firing after resolution (the listener calls `comp.cancel()`) is a no-op (see `execute` step 4). |
 | `pendingCancel` | `boolean` field | `component.ts` | **Accidental cancel losing answers**: Esc on the first question (or single question) cancelling outright would discard everything. | Two-step confirm: first Esc sets `pendingCancel = true` and shows an overlay; a second Esc truly cancels; any other key exits the overlay and keeps the form. The Submit-tab Cancel button bypasses this (already at the terminus). |
-| `autoConfirmIfAnswered` | **method** (not a field) | `component.ts` | **Zombie unanswered tab**: in multi-question mode, toggling an option then Tab-ing away leaves a tab "answered but not confirmed", so the Submit gate (`allConfirmed()`) stays false and the user cannot tell why Submit is blocked. | `gotoTab()` calls it before switching; if the current state has an answer but `!confirmed`, it sets `confirmed = true`. |
+| `autoConfirmIfAnswered` | **method** (not a field) | `component.ts` | **Zombie unanswered tab**: in multi-question mode, toggling an option then navigating away (`←/→`) leaves a tab "answered but not confirmed", so the Submit gate (`allConfirmed()`) stays false and the user cannot tell why Submit is blocked. | `gotoTab()` calls it before switching; if the current state has an answer but `!confirmed`, it sets `confirmed = true`. |
 
 ## Three-layer rendering
 
@@ -164,7 +164,7 @@ Constants: `SPLIT_PANE_MIN_WIDTH = 84`, `SPLIT_PANE_LEFT_MIN = 32`, `SPLIT_PANE_
 
 ## Spec cross-reference
 
-Design spec: `.xyz-harness/2026-06-15-ask-user/spec.md` (FR = functional requirement, AC = acceptance criterion). Implementation anchors:
+The original spec files (`.xyz-harness/2026-06-15-ask-user/`) are no longer in the repo — this table is self-contained (FR = functional requirement from the original spec). Implementation anchors:
 
 | Spec | Implemented in |
 |------|----------------|

package/README.md

@@ -1,6 +1,6 @@
 # @zhushanwen/pi-ask-user
 
-Inline adaptive `ask_user` tool for the Pi coding agent. Resolves ambiguity the agent cannot resolve itself — a single question (no tab bar) or 1-4 questions (tabbed view + submit), with split-pane option preview on wide terminals, an inline free-text editor, and optional comments.
+Inline adaptive `ask_user` tool for the Pi coding agent. Resolves ambiguity the agent cannot resolve itself — a single question (no tab bar) or 1-4 questions (tabbed view + submit), with split-pane option preview on wide terminals and an inline free-text editor. There is no comment feature: the free-text "Other" editor is the only free-form input.
 
 The tool's primary caller is the LLM. This README covers both **how an agent should use it** (top sections) and **how a maintainer reads the code** (File structure → Design notes).
 
@@ -46,7 +46,6 @@ If you recommend an option, prefix its label with `(Recommended)` and list it fi
       description?: string;  // short rationale shown under the label and in the preview pane
     }>;
     multiSelect?: boolean;   // default false; true only when several options can validly apply
-    allowComment?: boolean;  // default false; lets the user append a free-text note after selecting
   }>
 }  // questions: 1-4 entries
 ```
@@ -61,7 +60,7 @@ If you recommend an option, prefix its label with `(Recommended)` and list it fi
 | `header` | ≤12 chars; required when `questions.length > 1` | `validate.ts` (length + non-empty) |
 | `options[].label` | non-empty, unique within the question | `validate.ts` |
 
-Validation errors are returned as `isError: true` with a message that names the violation and tells you how to fix it — correct the parameters and retry.
+Validation failures make the tool `throw` with a message that names the violation and tells you how to fix it — correct the parameters and retry. (Pi converts a thrown error into an `isError: true` tool result; business outcomes like answers and cancellation are returned normally.)
 
 ## Result format
 
@@ -69,8 +68,7 @@ On success the tool returns the answers joined as `"question" = "answer"` lines.
 
 - **Single-select**: the chosen `label`.
 - **Multi-select**: selected labels joined with `, ` (e.g. `A, B`).
-- **Free-text (Other)**: whatever the user typed.
-- **Comment**: if `allowComment` was set, the user's note is appended after ` — ` (e.g. `Postgres — needs TLS`).
+- **Free-text (Other)**: whatever the user typed (appended to the selection with `, ` when both exist).
 
 A question with no answer reports as `(no answer)`.
 
@@ -78,11 +76,13 @@ A question with no answer reports as `(no answer)`.
 
 | Situation | Return | What the agent should do |
 |-----------|--------|--------------------------|
-| Parameter validation fails | `isError: true` + fix hint | Correct params and retry |
-| No interactive UI (headless) | `isError: true`, tool **disabled for the session** | Proceed with a defensible decision stated in text, or wait for the user — **do not retry** |
+| Parameter validation fails | `throw` (Pi shows it as `isError: true`) + fix hint | Correct params and retry |
+| No interactive UI (headless) | `throw`, tool **disabled for the session** | Proceed with a defensible decision stated in text, or wait for the user — **do not retry** |
 | Agent aborted (goal cancelled / context compacted) | `cancelled: true` | The text identifies it as an agent abort, not a user cancel. Do not assume an answer; do not retry ask_user — propagate the abort, or wait for new instructions if the decision is still required. |
 | User cancels (Esc → confirm, or Cancel button) | `cancelled: true` | Wait for new instructions, or re-ask with refined options if the decision is still required |
-| Unexpected error | `isError: true` + `{ error }` | Retry once with corrected parameters, or proceed with a defensible decision |
+| Unexpected error during interaction | `throw` (Pi shows it as `isError: true`) | Retry once with corrected parameters, or proceed with a defensible decision |
+
+Business outcomes (answers / cancellation) are returned as normal results; only validation failures and unexpected exceptions `throw` — Pi marks a thrown error `isError: true` with empty `details`.
 
 The headless branch physically removes the tool from the session (`setActiveTools`) — this is deliberate, so a function-calling loop cannot keep retrying `ask_user` in a non-interactive context.
 
@@ -90,11 +90,10 @@ The headless branch physically removes the tool from the session (`setActiveTool
 
 - **Adaptive layout**: single question → no tab bar; 1-4 questions → tabbed view + Submit tab.
 - **Split-pane preview** (≥84 cols): option list left, selected option detail right. The right pane is **plain-text** option detail (label + description), not a Markdown renderer.
-- **Inline free-text editor**: select "Other" → Enter → type a custom answer. Multi-line aware, soft-wrapped.
-- **Optional comments**: `allowComment: true` → after selecting, the user may append a short note.
+- **Inline free-text editor**: select "Other" → Enter → type a custom answer. Multi-line aware, soft-wrapped. No comment mode — this editor is the only free-form input.
 - **Multi-select**: `multiSelect: true` → toggle checkboxes with Space, Enter to confirm.
 - **Esc confirm-to-cancel**: Esc on the first question opens a confirm overlay (a second Esc cancels; any other key stays).
-- **Headless-safe**: disables the tool and returns `isError` when no UI is available.
+- **Headless-safe**: disables the tool and throws when no UI is available.
 
 ## File structure
 
@@ -111,7 +110,11 @@ extensions/universal/ask-user/
     ├── validate.ts           # pure parameter validation; error messages aimed at LLM fixability
     ├── component.ts          # AskUserComponent: state machine, input routing, race guards
     ├── question-view.ts      # pure render: option list, split-pane, inline editor
-    └── submit-view.ts        # pure render: Submit tab, answer summary, buildResult
+    ├── submit-view.ts        # pure render: Submit tab, answer summary, buildResult
+    ├── answer-codec.ts       # pure encode: AnswerValue → proto answers entries (protocol boundary)
+    ├── channel-handler.ts    # subagent channel passthru: RPC forward / TUI re-render → proto answers
+    ├── channel-registry-register.ts  # globalThis Symbol slot handshake (handler registration)
+    └── editor-ops.ts         # pure editor ops: insert/delete/cursor/paste (UTF-16 surrogate aware)
 ```
 
 `types.ts` is intentionally the shared dependency leaf — it holds `QuestionState`/`ThemeLike` (not `component.ts`) so the two pure-render views depend only on the leaf, breaking a would-be `component → view → component` cycle. See ARCHITECTURE.md for the full graph.
@@ -130,18 +133,12 @@ All three are consistent and point the same direction. If you tune behavior, edi
 
 - **Why inline, not overlay** (`execute` → `ctx.ui.custom` without `options`): the question belongs in the conversation flow, not a modal that obscures context.
 - **Why `Other` is auto-appended, not in the schema**: free-text input is the user's escape hatch and must not be something the LLM can omit or mislabel. Keeping it out of `options` guarantees it is always present and always last.
-- **Why `←/→` does not switch tabs**: left/right is reserved for the Submit tab's Submit/Cancel focus toggle, so it does not yank focus away while navigating an option list.
+- **Why `←/→` switches tabs but `Tab` does not**: arrow keys move between question tabs (and wrap on the Submit tab), so tab navigation never conflicts with the option-list cursor (`↑/↓`) or text editing. On the Submit tab, `Tab` alone toggles focus between Submit and Cancel — a deliberate single-key bidirectional toggle; `Shift+Tab` is intentionally unused because Pi's global `app.thinking.cycle` intercepts it.
 - **Why validation messages are verbose**: every message names the violation and gives a fix path, because the reader is an LLM that will retry.
 
 ## Spec reference
 
-The original design spec, acceptance criteria (FR-x / AC-x), and E2E test cases live under `.xyz-harness/2026-06-15-ask-user/`:
-
-- `spec.md` — requirements + functional/acceptance criteria
-- `e2e-test-cases.md` — end-to-end scenarios
-- `clarification.md` / `plan.md` — design rationale
-
-Cross-references between these and the implementation are in ARCHITECTURE.md.
+The original design spec (requirements, functional requirements FR-x, acceptance criteria AC-x, E2E test cases) predates this repository — the original spec files are no longer in the repo. The FR cross-reference table in ARCHITECTURE.md is self-contained: each entry names the behavior and where it is implemented in this codebase.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.0.15",
-  "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview, inline editor and optional comments.",
+  "version": "7.1.0",
+  "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview and an inline free-text editor.",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -29,11 +29,11 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.7.0",
-    "@zhushanwen/pi-extension-logger": "0.3.0"
+    "@xyz-agent/extension-protocol": "0.8.0",
+    "@zhushanwen/pi-extension-logger": "0.4.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-tui": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "fast-check": "^4.9.0",
@@ -41,8 +41,8 @@
     "vitest": "^4.1.8"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

package/src/__tests__/e2e.test.ts

@@ -1,7 +1,7 @@
 // src/__tests__/e2e.test.ts
 // E2E test cases for ask_user. Drives tool.execute() → real AskUserComponent
 // → simulated keypresses → asserts on final execute() result contract.
-// Spec: .xyz-harness/2026-06-15-ask-user/e2e-test-cases.md
+// （原始 spec 文件已不在仓内——用例自包含，编号 E2E-x 沿用原始 spec 命名）
 
 import { describe, expect, it } from "vitest";
 

package/src/__tests__/index.test.ts

@@ -453,17 +453,8 @@ describe("renderCall / renderResult (FR-9)", () => {
 		expect(renderText(node)).toContain("Cancelled");
 	});
 
-	it("I-19: renderResult error shows ✗ <error>", () => {
-		const tool = getTool();
-		const node = tool.renderResult(
-			{ details: { error: "something broke" } },
-			{ expanded: false },
-			stubTheme,
-		) as unknown as { render(width: number): string[] };
-		const text = renderText(node);
-		expect(text).toContain("✗");
-		expect(text).toContain("something broke");
-	});
+	// （I-19 已随 ErrorDetails 死类型删除：错误路径全部 throw（W4），pi 置 isError 后
+	// details 为空对象，renderResult 不存在 {error} details 分支可渲染）
 
 	// S-3: options.expanded 展开 —— 显示全部选项 + ●/○ 选中标记（spec FR-9）
 	it("I-20: renderResult expanded shows all options with ●/○ marks", () => {

package/src/channel-handler.ts

@@ -13,7 +13,8 @@
 //     （key=header/question，单选=string，多选=JSON 数组，Other→__other），让子进程 decode 一致。
 //
 // handler 收到的 req.channelPayload = {questions: AskUserQuestion[], allowCancel}（proto 格式，
-// 由子进程 askUserInteract 编码、subagent-workflow parseChannel 解析 options[0] JSON 得到）。
+// 由子进程 askUserInteract 编码、packages/subagent-core 的 parseChannel（execution/ui-channels.ts）
+// 解析 options[0] JSON 得到）。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
@@ -27,20 +28,20 @@ import { encodeAnswer } from "./answer-codec";
 import { type AnswerValue, 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 签名用本地等价类型，运行时结构兼容。
+ * channel handler 签名——与 packages/subagent-core 的 UiChannelRegistry.ChannelHandler 一致
+ *（execution/ui-channels.ts 定义，(req: unknown) => Promise<unknown>）。本文件不静态 import
+ * packages/subagent-core（host 侧包，非本包依赖——两侧扩展经 globalThis slot 握手协作，
+ * 见 index.ts 工厂注释）；handler 签名用本地等价类型，运行时结构兼容。
  */
 export type ChannelHandler = (req: unknown) => Promise<unknown>;
 
-/** handler 返回给 subagent-workflow 的 UiResponse 形状（dialog-queue.ts 定义）。
+/** handler 返回给 packages/subagent-core 的 UiResponse 形状（execution/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 填充。 */
+ *  channelPayload 由 packages/subagent-core 的 parseChannel 填充。 */
 interface ChannelRequest {
 	channelPayload?: { questions?: AskUserQuestion[]; allowCancel?: boolean };
 }
@@ -138,7 +139,7 @@ async function runTuiProtoInteraction(
  */
 export function createAskUserChannelHandler(ctx: ExtensionContext): ChannelHandler {
 	return async (req: unknown): Promise<unknown> => {
-		// req 正常是 subagent-workflow 构造的 UiRequest 对象；防御性收窄 null/undefined/
+		// req 正常是 packages/subagent-core 构造的 UiRequest 对象；防御性收窄 null/undefined/
 		// 非 object（handler 抛错会被 dialog-queue 兜底为 {cancelled:true}，但这里直接返回更干净）
 		if (req === null || typeof req !== "object") {
 			return { cancelled: true } satisfies ChannelResponse;

package/src/channel-registry-register.ts

@@ -3,14 +3,16 @@
 // 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:[]}
+// registry 占据 canonical 槽位，劫持后续 getOrCreateChannelRegistry 拿到的实例
+// （packages/subagent-core 的 createUiChannelRegistry（execution/ui-channels.ts）才是
+// canonical——它带排队、dialog 队列等完整能力）。修复后的握手协议改为「带 version 的 slot」：
+//   - 承载 subagent-core 的 subagent-workflow 扩展 session_start 时往 slot 写
+//     {version, registry, pending:[]}（registry 由 subagent-core 创建）
 //   - ask-user session_start 时只读 slot，registry 就绪则调 registry.register，未就绪则 push pending
 //   - ask-user **永不**创建 registry 实例，**永不**写 slot.registry
 //
-// 这是 ask-user 侧的注册入口；canonical registry 由 subagent-workflow 创建。本模块永不创建
+// 这是 ask-user 侧的注册入口；canonical registry 由 packages/subagent-core 创建（经
+// channel-registry-access.ts 的 getOrCreateChannelRegistry + flush）。本模块永不创建
 // registry 实例——仅往 slot 写 pending 或调 slot.registry.register。
 
 import type { ChannelHandler } from "./channel-handler";
@@ -21,7 +23,7 @@ const logger = getLogger("ask-user");
 /**
  * 进程级 channel registry 握手的 globalThis key（Symbol.for 跨模块共享）。
  *
- * ⚠️ 必须与 extensions/universal/subagent-workflow/src/execution/channel-registry-access.ts 的字面量
+ * ⚠️ 必须与 packages/subagent-core/src/execution/channel-registry-access.ts 的字面量
  * 完全一致——两边用同一字符串确保拿到同一 slot 实例。改名必须两侧同步。
  */
 export const CHANNEL_HANDSHAKE_KEY = Symbol.for(
@@ -35,9 +37,9 @@ const HANDSHAKE_VERSION = 1;
 const ASK_USER_CHANNEL = "ask_user";
 
 /**
- * channel registry 的本地等价接口（与 subagent-workflow UiChannelRegistry 形状一致）。
- * 本模块不静态 import subagent-workflow（它是可选 peerDep，未安装时静态 import 会致整个
- * ask-user 加载失败）；运行时结构兼容即可。
+ * channel registry 的本地等价接口（与 packages/subagent-core 的 UiChannelRegistry 形状一致，
+ * execution/ui-channels.ts 定义）。本模块不静态 import packages/subagent-core（host 侧包，
+ * 非本包依赖——两侧经 globalThis slot 握手协作）；运行时结构兼容即可。
  */
 interface ChannelRegistry {
 	register(channel: string, handler: ChannelHandler): void;
@@ -45,7 +47,7 @@ interface ChannelRegistry {
 	list(): string[];
 }
 
-/** pending 队列元素：channel + handler。subagent-workflow flush 时遍历调用 registry.register。 */
+/** pending 队列元素：channel + handler。packages/subagent-core flush（channel-registry-access.ts）时遍历调用 registry.register。 */
 interface PendingEntry {
 	channel: string;
 	handler: ChannelHandler;
@@ -55,9 +57,9 @@ interface PendingEntry {
  * globalThis slot 的形状。
  *
  * - `version`：握手协议版本（运行时校验，不兼容则丢弃重建）
- * - `registry`：canonical 实例，**仅 subagent-workflow 创建**；缺失表示 registry 未就绪，
+ * - `registry`：canonical 实例，**仅 packages/subagent-core 创建**；缺失表示 registry 未就绪，
  *   ask-user 把 handler 入 pending 队列等待 flush
- * - `pending`：未消费的注册请求（registry 就绪后由 subagent-workflow 一次性 flush）
+ * - `pending`：未消费的注册请求（registry 就绪后由 packages/subagent-core 一次性 flush）
  */
 export interface ChannelRegistryHandshake {
 	version: 1;
@@ -98,7 +100,7 @@ function ensureSlot(): ChannelRegistryHandshake {
  *   3. slot 存在且 registry 就绪 → 直接调 registry.register("ask_user", handler)
  *
  * 多次调用幂等：registry 就绪时 register 同名覆盖；未就绪时 pending.length 增长
- * （subagent-workflow flush 时一次性消费所有 pending）。
+ * （packages/subagent-core flush 时一次性消费所有 pending）。
  *
  * @param handler ask_user channel handler（createAskUserChannelHandler 产出）
  */

package/src/editor-ops.ts

@@ -10,8 +10,6 @@ import { isHighSurrogate, SURROGATE_PAIR_LEN, type QuestionState } from "./types
 
 // ── 编辑器纯操作 ──
 
-// ── 编辑器纯操作 ──
-
 /** 在光标处插入文本，光标前移 text.length。 */
 export function insertAtCursor(state: QuestionState, text: string): void {
 	state.draftText = state.draftText.slice(0, state.cursorIndex) + text + state.draftText.slice(state.cursorIndex);

package/src/index.ts

@@ -211,15 +211,16 @@ 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
+	//（CHANNEL_HANDSHAKE_KEY，与 packages/subagent-core/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 创建。
+	//   2. slot.registry 就绪（承载 packages/subagent-core 的 subagent-workflow 扩展先到）→ 直接调 registry.register
+	//   3. slot.registry 未就绪 → handler 入 pending，等 subagent-core flush
+	// ask-user 永不创建 registry 实例——canonical registry 仅 packages/subagent-core 创建
+	//（execution/ui-channels.ts 的 createUiChannelRegistry）。
 	pi.on("session_start", (_event, ctx) => {
 		registerAskUserChannelHandler(createAskUserChannelHandler(ctx));
 	});
@@ -351,10 +352,8 @@ Don't:
 			theme: ThemeLike,
 		) {
 			const details = result.details;
-			if (details && "error" in details && details.error) {
-				return new Text(theme.fg("error", `✗ ${details.error}`), 0, 0);
-			}
-			// details 现已排除 ErrorDetails 分支，收窄为 Result | undefined
+			// 错误路径已全部改 throw（W4）：pi 置 isError:true 后 details 为空对象，
+			// 不存在 ErrorDetails 形态——这里 details 要么 undefined 要么 Result
 			const d = details as Result | undefined;
 			if (!d || d.cancelled) {
 				return new Text(theme.fg("warning", "Cancelled"), 0, 0);

package/src/question-view.ts

@@ -18,6 +18,8 @@ const SPLIT_PANE_LEFT_RATIO = 0.42;
 const DESCRIPTION_INDENT_MULTI = 10;
 const DESCRIPTION_INDENT_SINGLE = 8;
 const PREVIEW_MIN_WIDTH = 10;
+/** 分屏右列（详情预览）最小行数（左列较短时占位，避免预览区域过矮）。 */
+const PREVIEW_MIN_LINES = 8;
 const QUESTION_TEXT_MARGIN = 2;
 
 export interface DisplayOption {
@@ -238,7 +240,7 @@ function buildSplitPane(
 	const leftCtx: RenderContext = { ...ctx, width: split.left };
 	const rightCtx: RenderContext = { ...ctx, width: split.right };
 	const leftLines = buildOptionLines(leftCtx, true);
-	const rightLines = buildPreviewLines(rightCtx, Math.max(leftLines.length, 8));
+	const rightLines = buildPreviewLines(rightCtx, Math.max(leftLines.length, PREVIEW_MIN_LINES));
 	const rowCount = Math.max(leftLines.length, rightLines.length);
 	const sep = t.fg("dim", SPLIT_PANE_SEPARATOR);
 	for (let i = 0; i < rowCount; i++) {

package/src/types.ts

@@ -109,13 +109,12 @@ export const ResultSchema = Type.Object({
 
 export type Result = Static<typeof ResultSchema>;
 
-/** execute 意外异常时返回的错误 details（区别于 Result.cancelled 的业务取消） */
-export interface ErrorDetails {
-	error: string;
-}
-
-/** execute 返回的 details 联合：正常/取消/校验失败走 Result，意外异常走 ErrorDetails */
-export type AskUserDetails = Result | ErrorDetails;
+/**
+ * execute 返回的 details 形状：正常/取消/校验失败都复用 Result。
+ * 错误路径已全部改为 throw（W4）——pi 对 throw 生成 isError:true 且 details 为空对象，
+ * 不存在「错误 details」形态；曾有的 ErrorDetails 死类型随不可达分支一并删除。
+ */
+export type AskUserDetails = Result;
 
 // ── 跨模块共享的交互状态类型 ─────────────────────────
 // 放这里（而非 component.ts）是为了让 question-view.ts / submit-view.ts