pi-cc-extensions 0.8.7 → 0.8.9

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="./assets/readme/hero.svg" width="100%" alt="pi-cc-extensions：集成 Claude Code 风格界面、上下文检查及 Agent 与 Session 引用的 Pi 效率扩展套件">
+  <img src="./assets/readme/hero.svg" width="100%" alt="pi-cc-extensions：集成 Claude Code 风格界面、结构化问卷、上下文检查及 Agent 与 Session 引用的 Pi 效率扩展套件">
 </p>
 
 <p align="center">
@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  面向 Pi 的终端效率扩展套件 · Claude Code 风格界面 · 上下文检查 · Agent 与 Session 引用
+  面向 Pi 的终端效率扩展套件 · Claude Code 风格界面 · 结构化问卷 · 上下文检查 · Agent 与 Session 引用
 </p>
 
 ---
@@ -86,9 +86,23 @@
 
 `mode` 可取 `on`、`off` 或 `compact`。旧版 `enabled: true/false` 会自动迁移为 `on/off`。排除名单使用精确工具名；手动修改配置后执行 `/reload`。`Agent` 的专用 renderer 始终保留。
 
-
 Compact transcript 行为改编自 [avhagedorn/pi-compact-transcript](https://github.com/avhagedorn/pi-compact-transcript) v0.6.2（MIT，Alan Hagedorn）。
 
+### 结构化问卷
+
+`extensions/ask-user-question/index.ts` 内置 `ask_user_question` 工具，支持：
+
+- 单选、多选、2–4 个选项及最多 4 个问题的标签页问卷
+- `Type something.` 自定义回答、备注和 Markdown 预览
+- RPC / ACP 原生对话框降级；无 UI 时自动移除工具
+- TUI 使用 Pi 原生临时 editor component，不替换 editor factory：兼容默认滚动编辑器，也兼容 `pi-zentui` fixed-editor
+- 响应式高度预算：常规终端为历史 transcript 至少保留 6 行、约 30% 高度；`Ctrl+]` 可折叠为单行并保留答案
+- UI 固定使用英文，不加载国际化套件或语言包
+
+配置文件为 `~/.config/rpiv-ask-user-question/config.json`。可通过 `collapseKey` 修改折叠快捷键，详见 [`extensions/ask-user-question/README.md`](./extensions/ask-user-question/README.md)。
+
+该扩展基于 [`@juicesharp/rpiv-ask-user-question`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question) v2.1.0（MIT）内置，并包含本项目针对默认滚动编辑器、固定编辑器与历史消息视口的兼容优化。
+
 ### 上下文窗口查看
 
 `extensions/context.ts` 注册 `/context`，展示当前上下文窗口的使用分布，并可进一步预览：
@@ -140,6 +154,7 @@ pi install git:github.com/minuque/pi-cc-extensions
 ```text
 /context
 /ccstyle on
+# ask_user_question 会自动作为工具提供给模型
 ```
 
 ## 本地开发
@@ -161,6 +176,8 @@ pi install /absolute/path/to/pi-cc-extensions
 /reload
 ```
 
+`ask-user-question` 的 TUI 模块会被进程缓存；修改该目录或重装依赖后需完整退出并重启 Pi，不能只执行 `/reload`。
+
 ## 兼容性
 
 - Node.js `>=22.19.0`
@@ -172,7 +189,6 @@ pi install /absolute/path/to/pi-cc-extensions
 | 扩展                                     | 作用                                                                          |
 | ------------------------------------------ | ------------------------------------------------------------------------------- |
 | `npm:pi-theme-picker`                    | 通过`/theme` 交互式切换 Pi 主题，支持模糊搜索和实时预览                       |
-| `npm:@juicesharp/rpiv-ask-user-question` | 提供`ask_user_question` 结构化问卷工具，支持单选、多选、预览和备注            |
 | `npm:pi-mcp-adapter`                     | 将 MCP 服务接入 Pi，并通过代理工具按需发现，减少上下文占用                    |
 | `npm:@tintinweb/pi-subagents`            | Claude Code 风格的并行 SubAgent、后台任务、任务编排、工作树隔离和自定义 Agent |
 | `npm:@ayulab/pi-rewind`                  | 基于 checkpoint 的`/rewind` 回退，支持分别恢复代码、对话或两者                |
@@ -182,6 +198,6 @@ pi install /absolute/path/to/pi-cc-extensions
 
 ### 使用注意
 
-- `pi-cc-extensions` 与 `pi-zentui` 都会修改 Pi 的 TUI / renderer。若出现布局或渲染冲突，建议先确定一个作为主要界面扩展，另一个按需停用。
+- 内置问卷采用非 overlay 的临时 editor component，兼容 `pi-zentui` 固定编辑器；常规终端会保留历史消息视口。
 - `pi-mcp-adapter` 默认延迟连接 MCP 服务，有助于节省上下文；包含凭据的 MCP 配置不要提交到仓库。
 - `pi-compact-thinking` 和 `pi-zentui` 都涉及 Pi 内部 UI 行为，升级 Pi 后若出现异常，优先执行 `/reload` 或暂时停用对应扩展。

package/extensions/ask-user-question/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/ask-user-question/README.md

@@ -0,0 +1,63 @@
+# ask_user_question
+
+English-only structured questionnaire bundled with `pi-cc-extensions`.
+
+## Features
+
+- One to four questions per call.
+- Two to four authored options per question.
+- Single-select and multi-select modes.
+- Automatically appended `Type something.` custom-answer row.
+- Optional notes and Markdown previews.
+- Submit review for multi-question calls.
+- RPC/ACP fallback through native select/input dialogs.
+- Removed from the model's tool list when no UI is available.
+
+## Editor compatibility
+
+The TUI uses Pi's native temporary editor flow and does not replace the configured editor factory.
+
+- Pi's default scrolling editor is restored with its draft and focus after the questionnaire closes.
+- Fixed-editor compositors remain active.
+- On terminals with at least 16 rows, the questionnaire preserves at least six transcript rows and about 30% of terminal height.
+- On smaller terminals, the questionnaire may use the full height to remain usable.
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Up` / `Down` | Move between options |
+| `Enter` | Confirm or activate the selected row |
+| `Space` | Toggle a multi-select option |
+| `Tab` / `Shift+Tab` | Switch question tabs |
+| `n` | Open notes |
+| `Ctrl+]` | Collapse or expand the questionnaire |
+| `Esc` | Cancel |
+
+## Configuration
+
+Optional file: `~/.config/rpiv-ask-user-question/config.json`
+
+```json
+{
+  "collapseKey": "alt+o",
+  "guidance": {
+    "promptSnippet": "Ask before guessing on ambiguous requirements",
+    "promptGuidelines": [
+      "Batch related questions into one ask_user_question call."
+    ]
+  }
+}
+```
+
+Set `collapseKey` to `"off"` to disable collapsing. UI text is intentionally English-only; no localization package or locale files are loaded.
+
+## Development
+
+The TUI module graph is cached for the process lifetime. After changing this extension or reinstalling dependencies, fully restart Pi instead of relying only on `/reload`.
+
+## Attribution
+
+Based on `@juicesharp/rpiv-ask-user-question` v2.1.0 with local editor-layout and transcript-viewport compatibility changes.
+
+MIT — see [LICENSE](./LICENSE).

package/extensions/ask-user-question/ask-user-question.ts

@@ -0,0 +1,244 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, resolveCollapseKey, validateGuidanceFields } from "./config.js";
+import {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+} from "./events.js";
+// Static import is fine: rpc-fallback does not pull in the TUI render graph.
+import { hasDialogUI, runRpcQuestionnaire } from "./rpc-fallback.js";
+import { ROW_INTENT_META, sentinelsToAppend } from "./state/row-intent.js";
+import { buildQuestionnaireResponse, buildToolResult } from "./tool/response-envelope.js";
+import {
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	type QuestionData,
+	type QuestionnaireError,
+	type QuestionnaireResult,
+	type QuestionParams,
+	QuestionParamsSchema,
+} from "./tool/types.js";
+import { validateQuestionnaire } from "./tool/validate-questionnaire.js";
+import type { WrappingSelectItem } from "./view/components/wrapping-select.js";
+
+function emitAskUserPromptEvent(pi: ExtensionAPI, params: QuestionParams): void {
+	const payload: AskUserPromptEventPayload = {
+		questions: params.questions.map((q) => ({
+			question: q.question,
+			header: q.header,
+			multiSelect: q.multiSelect ?? false,
+			options: q.options.map((o) => ({
+				label: o.label,
+				description: o.description,
+				hasPreview: typeof o.preview === "string" && o.preview.length > 0,
+			})),
+		})),
+	};
+	pi.events.emit(ASK_USER_PROMPT_EVENT, payload);
+}
+
+function emitAskUserBlockedEvent(pi: ExtensionAPI, active: boolean): void {
+	const payload: AskUserBlockedEventPayload = { active };
+	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
+}
+
+/** Canonical tool name — single source of truth shared with the reconcile module. */
+export const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+
+const ERROR_NO_UI = "Error: UI not available (running in non-interactive mode)";
+
+const ERROR_NO_CUSTOM_UI =
+	"Error: this client cannot render the questionnaire (custom UI is unavailable, e.g. RPC/ACP hosts such as Zed or Paseo). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, without using this tool.";
+
+const ERROR_SESSION_LOAD_FAILED =
+	"Error: the questionnaire UI failed to load — the host's installed dependencies were likely replaced or removed on disk while Pi was running (e.g. a package-manager install touched the store). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, and tell the user that restoring this tool requires repairing the install if needed and restarting Pi.";
+
+const ERROR_STALE_MODULE_CACHE =
+	"Error: the questionnaire UI cannot load — the host's module cache went stale after an earlier failed load (typically dependencies replaced on disk mid-session). This is unrecoverable within the current Pi process. The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, and tell the user to restart Pi to restore this tool.";
+
+/** Delay before the background session-graph pre-warm; mirrors rpiv-workflow's /wf prewarm. */
+export const PREWARM_DELAY_MS = 2000;
+
+type SessionModule = typeof import("./state/questionnaire-session.js");
+
+type SessionLoad =
+	| { ok: true; module: SessionModule }
+	| { ok: false; error: Extract<QuestionnaireError, "session_load_failed" | "stale_module_cache">; message: string };
+
+/**
+ * Lazy-load the ~560ms QuestionnaireSession view/TUI render graph, guarding
+ * the two failure shapes of issue #107. Pi's jiti loader registers a module in
+ * its graph cache BEFORE evaluating the body and does not evict it when
+ * evaluation throws (jiti 2.7.0), so one failed load — e.g. `pnpm install
+ * --force` replacing the store entry mid-session — leaves every later import
+ * of this specifier resolving to a namespace without the class. That state is
+ * unrecoverable in-process (cache-busting specifiers fail jiti resolution);
+ * both branches therefore return an LLM-facing envelope that names the restart
+ * requirement instead of leaking a bare "not a constructor" TypeError.
+ */
+export async function loadQuestionnaireSession(): Promise<SessionLoad> {
+	let mod: SessionModule;
+	try {
+		mod = await import("./state/questionnaire-session.js");
+	} catch (e) {
+		const cause = e instanceof Error ? e.message : String(e);
+		return { ok: false, error: "session_load_failed", message: `${ERROR_SESSION_LOAD_FAILED} (cause: ${cause})` };
+	}
+	if (typeof mod.QuestionnaireSession !== "function") {
+		const keys = JSON.stringify(Object.keys(mod));
+		return {
+			ok: false,
+			error: "stale_module_cache",
+			message: `${ERROR_STALE_MODULE_CACHE} (resolved namespace keys: ${keys})`,
+		};
+	}
+	return { ok: true, module: mod };
+}
+
+export function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {
+	const items: WrappingSelectItem[] = question.options.map((o) => ({
+		kind: "option",
+		label: o.label,
+		description: o.description,
+	}));
+	for (const kind of sentinelsToAppend(question)) {
+		items.push({ kind, label: ROW_INTENT_META[kind].label });
+	}
+	return items;
+}
+
+export const DEFAULT_PROMPT_SNIPPET = `Ask the user up to ${MAX_QUESTIONS} structured questions (${MIN_OPTIONS}-${MAX_OPTIONS} options each) when requirements are ambiguous`;
+export const DEFAULT_PROMPT_GUIDELINES: string[] = [
+	`Use ask_user_question whenever the user's request is underspecified and you cannot proceed without concrete decisions — you can ask up to ${MAX_QUESTIONS} questions per invocation.`,
+	`Each question MUST have ${MIN_OPTIONS}-${MAX_OPTIONS} options. Every option requires a concise label (1-5 words) and a description explaining what the choice means or its trade-offs. The user can additionally type a custom answer via the automatically appended "Type something." row on every question, or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.`,
+	`Set multiSelect: true when multiple answers are valid. Provide an options[].preview markdown string when an option benefits from richer side-by-side context (mockups, code snippets, diagrams, configs) — single-select only. The "Type something." row is appended to every question; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column. If you recommend a specific option, make that the first option and append "(Recommended)" to its label.`,
+	"Do not stack multiple ask_user_question calls back-to-back — group all clarifying questions into one invocation.",
+];
+
+export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
+	const guidance = validateGuidanceFields(loadConfig().guidance);
+	pi.registerTool({
+		name: ASK_USER_QUESTION_TOOL_NAME,
+		label: "Ask User Question",
+		description: `Ask the user one or more structured questions during execution. Use when you need to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take
+
+Usage notes:
+- Users can type a custom answer via the automatically appended "Type something." row on every question or press Esc to abandon the questionnaire. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
+- Use multiSelect: true when multiple answers are valid. The "Type something." row is available on every question, including when options carry a \`preview\`; in preview mode it expands to the full pane width while typing so the custom answer is not cramped into the narrow options column.
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label.
+
+Preview feature:
+Use the optional \`preview\` field on options when presenting concrete artifacts that users need to visually compare:
+- ASCII mockups of UI layouts or components
+- Code snippets showing different implementations
+- Diagram variations
+- Configuration examples
+
+Preview content is rendered as markdown in a monospace box. Multi-line text with newlines is supported. When any option has a preview, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).`,
+		promptSnippet: guidance.promptSnippet ?? DEFAULT_PROMPT_SNIPPET,
+		promptGuidelines: guidance.promptGuidelines ?? DEFAULT_PROMPT_GUIDELINES,
+		parameters: QuestionParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const typed = params as unknown as QuestionParams;
+			if (!ctx.hasUI) return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: "no_ui" });
+
+			const validation = validateQuestionnaire(typed);
+			if (validation.ok === false) {
+				return buildToolResult(validation.message, {
+					answers: [],
+					cancelled: true,
+					error: validation.error,
+				});
+			}
+
+			// Emit event for external listeners (e.g., notification plugins)
+			emitAskUserPromptEvent(pi, typed);
+
+			// RPC hosts (VSCode pendant, ACP clients like Zed/Paseo — issue #78):
+			// ui.custom() cannot render there, but the select/input dialog
+			// sub-protocol works. Hosts that advertise ctx.mode (pi ≥0.79) route to
+			// the sequential dialog walker up front, skipping the TUI render-graph
+			// import entirely; RPC builds that predate ctx.mode are caught by the
+			// custom()-resolved-undefined backstop below. See ./rpc-fallback.ts.
+			if ((ctx as { mode?: string }).mode === "rpc" && hasDialogUI(ctx.ui)) {
+				emitAskUserBlockedEvent(pi, true);
+				try {
+					return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
+				} finally {
+					emitAskUserBlockedEvent(pi, false);
+				}
+			}
+
+			const itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));
+
+			// Lazy — QuestionnaireSession pulls the ~560ms view/TUI render graph;
+			// load it only when the tool runs, not at extension registration.
+			const sessionLoad = await loadQuestionnaireSession();
+			if (sessionLoad.ok === false) {
+				return buildToolResult(sessionLoad.message, { answers: [], cancelled: true, error: sessionLoad.error });
+			}
+			const { QuestionnaireSession } = sessionLoad.module;
+			// Resolve the collapse/expand key spec from config. Default is `ctrl+]`; users
+			// with non-US layouts (e.g. Latin American, where `]` is shifted) can override
+			// via the `collapseKey` config field. `resolveCollapseKey` also accepts the
+			// sentinel value `"off"` to disable the shortcut entirely.
+			const collapseKey = resolveCollapseKey(loadConfig());
+
+			// Use Pi's native temporary editor flow without replacing the configured
+			// editor factory. The default scrolling editor is restored by the host, while
+			// fixed-editor compositors stay active and preserve their transcript viewport.
+
+			emitAskUserBlockedEvent(pi, true);
+			try {
+				const result = await ctx.ui.custom<QuestionnaireResult>((tui, theme, _kb, done) => {
+					const session = new QuestionnaireSession({
+						tui,
+						theme,
+						params: typed,
+						itemsByTab,
+						done,
+						collapseKey,
+					});
+					return session.component;
+				});
+
+				// A TUI questionnaire ALWAYS resolves a QuestionnaireResult (cancel
+				// included — state-reducer emits `{ answers, cancelled }`), so
+				// `undefined` uniquely means "host cannot render", never "user
+				// declined". RPC builds that predate ctx.mode land here: run the
+				// dialog walker when the host has the primitives; otherwise tell the
+				// model the user never saw the questions.
+				if (result === undefined) {
+					if (hasDialogUI(ctx.ui)) {
+						return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
+					}
+					return buildToolResult(ERROR_NO_CUSTOM_UI, { answers: [], cancelled: true, error: "no_custom_ui" });
+				}
+
+				return buildQuestionnaireResponse(result, typed);
+			} finally {
+				emitAskUserBlockedEvent(pi, false);
+			}
+		},
+	});
+
+	// Pre-warm the lazy session graph once startup settles (#107). A graph
+	// evaluated while the paths Pi resolved at boot still exist stays in memory
+	// for the process lifetime, so later on-disk dependency churn (e.g. `pnpm
+	// install --force` replacing the store mid-session) can no longer poison
+	// jiti's graph cache. Swallowed failure is safe: the first real call
+	// re-imports and surfaces it through loadQuestionnaireSession's structured
+	// envelope. unref keeps the timer from holding a non-TUI embedder's process
+	// open.
+	const timer = setTimeout(() => void loadQuestionnaireSession().catch(() => undefined), PREWARM_DELAY_MS);
+	timer.unref?.();
+}
+
+export { buildQuestionnaireResponse, buildToolResult };

package/extensions/ask-user-question/config.ts

@@ -0,0 +1,75 @@
+import type { GuidanceFields } from "@juicesharp/rpiv-config";
+import { loadJsonConfigWithLegacyFallback, validateGuidanceFields } from "@juicesharp/rpiv-config";
+
+/** Key spec for the questionnaire collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
+export type CollapseKeySpec = string;
+
+export const DEFAULT_COLLAPSE_KEY: CollapseKeySpec = "ctrl+]";
+export const COLLAPSE_KEY_OFF: CollapseKeySpec = "off";
+
+export interface AskUserQuestionConfig {
+	guidance?: GuidanceFields;
+	/**
+	 * Key spec for the collapse/expand shortcut, in the same format as pi-coding-agent
+	 * keybinding ids (`modifier+key`, e.g. `ctrl+]`, `alt+o`, `ctrl+shift+h`). Defaults
+	 * to `"ctrl+]"`. Set this to a key that is reachable on your keyboard layout — Latin
+	 * American layouts (where `]` is on the shifted layer) often want `"ctrl+}"` instead.
+	 * Pass `"off"` to disable the collapse shortcut entirely.
+	 */
+	collapseKey?: CollapseKeySpec;
+}
+
+// Named keys accepted by pi-tui's `matchesKey` (keys.js switch on the parsed base key).
+// parseKeyId lowercases the id before matching, so lowercase spellings are canonical.
+const SPECIAL_KEYS = new Set([
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	...Array.from({ length: 12 }, (_, i) => `f${i + 1}`),
+]);
+
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+function isValidCollapseKeySpec(spec: string): boolean {
+	// Mirror pi-tui's KeyId grammar strictly: zero or more distinct modifiers, then a
+	// base key that is a single printable character or a named special key. A loose
+	// check is not enough — pi-tui's `parseKeyId` takes the LAST `+`-part as the key
+	// and ignores unknown parts, so a typo like `ctr+]` would silently match every
+	// bare `]` keypress.
+	if (!spec) return false;
+	if (spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+	const parts = spec.split("+");
+	const base = parts[parts.length - 1] ?? "";
+	const modifiers = parts.slice(0, -1);
+	if (modifiers.length !== new Set(modifiers).size) return false;
+	if (!modifiers.every((m) => MODIFIERS.has(m))) return false;
+	return base.length === 1 ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base) : SPECIAL_KEYS.has(base);
+}
+
+export function resolveCollapseKey(config: Pick<AskUserQuestionConfig, "collapseKey">): CollapseKeySpec {
+	const raw = config.collapseKey?.trim().toLowerCase();
+	if (raw === undefined || raw === "") return DEFAULT_COLLAPSE_KEY;
+	if (raw === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+	return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
+}
+
+export function loadConfig(): AskUserQuestionConfig {
+	return loadJsonConfigWithLegacyFallback<AskUserQuestionConfig>("rpiv-ask-user-question");
+}
+
+export { validateGuidanceFields };

package/extensions/ask-user-question/events.ts

@@ -0,0 +1,55 @@
+/**
+ * Public event contract for @juicesharp/rpiv-ask-user-question.
+ *
+ * STABILITY POLICY — applies to every event in the `rpiv:*` namespace.
+ *
+ *   1. Channel names are immutable. Once shipped, never rename.
+ *   2. Payload changes are append-only. Listeners MUST tolerate unknown
+ *      fields. New fields ship as optional (`?:`).
+ *   3. Breaking changes (rename, retype, remove a field; change emission
+ *      semantics) require a NEW channel, e.g. `rpiv:ask-user:prompt.v2`,
+ *      with dual-emit during a deprecation window.
+ *   4. No `version` field inside payloads. Version via channel name only.
+ *   5. Payloads must be JSON-safe: primitives, arrays, plain objects.
+ *      No Set/Map/Date/class instances — payloads must survive JSON
+ *      serialization when listeners forward them across process or
+ *      network boundaries.
+ *
+ * Naming: `rpiv:<package-or-tool>:<phase>`, lowercase, hyphen-separated.
+ * Aligns with Pi's `"my-extension:status"` example and UniPi's `unipi:*`.
+ */
+
+export const ASK_USER_PROMPT_EVENT = "rpiv:ask-user:prompt" as const;
+
+export interface AskUserPromptEventPayload {
+	questions: ReadonlyArray<AskUserPromptQuestion>;
+}
+
+/**
+ * Emitted while the questionnaire is awaiting user input (TUI `ui.custom` and
+ * RPC dialog walker). Cleared with `{ active: false }` in `finally` so listeners
+ * can distinguish blocked-on-human from working.
+ */
+export const ASK_USER_BLOCKED_EVENT = "rpiv:ask-user:blocked" as const;
+
+export interface AskUserBlockedEventPayload {
+	/** True while input is awaited; false when the wait ends (answer, cancel, or error). */
+	active: boolean;
+}
+
+export interface AskUserPromptQuestion {
+	/** The full question text, exactly as the agent authored it. */
+	question: string;
+	/** The short chip/tag shown next to the question. */
+	header: string;
+	/** True iff the user may pick multiple options. Normalized from optional. */
+	multiSelect: boolean;
+	options: ReadonlyArray<AskUserPromptOption>;
+}
+
+export interface AskUserPromptOption {
+	label: string;
+	description: string;
+	/** True iff the option carries rich preview content (content not shipped). */
+	hasPreview: boolean;
+}

package/extensions/ask-user-question/index.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskUserQuestionTool } from "./ask-user-question.js";
+import { registerAskUserQuestionReconciler } from "./reconcile.js";
+
+export {
+  ASK_USER_BLOCKED_EVENT,
+  ASK_USER_PROMPT_EVENT,
+  type AskUserBlockedEventPayload,
+  type AskUserPromptEventPayload,
+  type AskUserPromptOption,
+  type AskUserPromptQuestion,
+} from "./events.js";
+
+export default function (pi: ExtensionAPI) {
+  registerAskUserQuestionTool(pi);
+  registerAskUserQuestionReconciler(pi);
+}

package/extensions/ask-user-question/reconcile.ts

@@ -0,0 +1,47 @@
+/**
+ * reconcile — mid-session lifecycle reconciliation for ask_user_question.
+ *
+ * Strips or re-adds the tool to the active set so it is invisible to the LLM
+ * in non-interactive runs (no UI) and present in interactive ones. Mirrors the
+ * advisor's reconcileAdvisorTool / registerAdvisorBeforeAgentStart pattern
+ * (packages/rpiv-advisor/advisor/handlers.ts), simplified: ask_user_question's
+ * only gating signal is ctx.hasUI (no model or executor blocklist), so it
+ * reads the flag directly and omits the notify.
+ *
+ * RPC hosts (ctx.mode === "rpc": VSCode pendant, Zed, Paseo) are deliberately
+ * NOT stripped: since PR #100 the tool renders there via the select/input
+ * dialog walker (rpc-fallback.ts), so hasUI is the honest signal again. The
+ * brief period where RPC was stripped (872ef1c) predates that fallback.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-user-question.js";
+
+/**
+ * Strip-or-restore `ask_user_question` to match `ctx.hasUI`. Reads the active
+ * tool list itself. Idempotent: when the tool is already in the right state it
+ * leaves the active set (and sibling tools) untouched.
+ */
+export function reconcileAskUserQuestionTool(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	const active = pi.getActiveTools();
+	const hasTool = active.includes(ASK_USER_QUESTION_TOOL_NAME);
+	// !hasUI → strip so the tool never reaches the LLM's tool list in
+	// non-interactive runs; hasUI → restore. The in-handler guards in
+	// ask-user-question.ts (!hasUI, and the custom()-undefined → dialog-walker /
+	// no_custom_ui backstop) remain as one-turn backstops if a future Pi change
+	// reorders the tool-list snapshot ahead of before_agent_start, or a host
+	// reports hasUI without any usable rendering primitive.
+	if (!ctx.hasUI && hasTool) {
+		pi.setActiveTools(active.filter((n) => n !== ASK_USER_QUESTION_TOOL_NAME));
+	} else if (ctx.hasUI && !hasTool) {
+		pi.setActiveTools([...active, ASK_USER_QUESTION_TOOL_NAME]);
+	}
+}
+
+/**
+ * Attach the reconciler to `before_agent_start` so the active set is fixed up
+ * before each turn's tool-list snapshot is read. Safe to call once at load.
+ */
+export function registerAskUserQuestionReconciler(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (_event, ctx) => reconcileAskUserQuestionTool(pi, ctx));
+}