@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

package/node_modules/@herbertgao/pi-subagents/src/usage.ts

@@ -6,23 +6,151 @@
  * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
  * the cumulative cached prefix re-read on that one call — summing across
  * turns counts the prefix N times. See issue #38.
+ *
+ * That exclusion is about this *display* total, not about what was billed: the
+ * prefix really is re-read and re-charged on every call. So `cacheRead` is
+ * accumulated here anyway, kept out of `getLifetimeTotal` and used only where
+ * billing is the question — reporting to the parent session, whose own messages
+ * pi counts the same way (`addUsageToTotals`). Reporting 0 there would make a
+ * subagent's rows count differently from every other row in one total.
+ *
+ * `cost` is a plain sum for the same reason: it is what pi charged for that one
+ * message (`usage.cost.total`, priced from the model's rates), not a cumulative
+ * figure. Both are optional because a model with no pricing data reports no
+ * cost, and because every accumulator predates them; absent reads as 0.
  */
 export type LifetimeUsage = {
   input: number
   output: number
   cacheWrite: number
+  cacheRead?: number
+  cost?: number
 }
 
-/** Sum of lifetime usage components, or 0 if undefined. */
+/**
+ * Sum of lifetime *token* components for DISPLAY, or 0 if undefined.
+ * Deliberately excludes `cacheRead` (see above) and `cost` — that is money, not
+ * tokens, and lives on the same object only because it accumulates on the same
+ * events.
+ */
 export function getLifetimeTotal(u?: LifetimeUsage): number {
   return u ? u.input + u.output + u.cacheWrite : 0
 }
 
+/** Accumulated cost in USD, or 0 when unpriced/undefined. */
+export function getLifetimeCost(u?: LifetimeUsage): number {
+  return u?.cost ?? 0
+}
+
 /** Add a usage delta into a target accumulator (mutates target). */
 export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
   into.input += delta.input
   into.output += delta.output
   into.cacheWrite += delta.cacheWrite
+  if (delta.cacheRead) into.cacheRead = (into.cacheRead ?? 0) + delta.cacheRead
+  if (delta.cost) into.cost = (into.cost ?? 0) + delta.cost
+}
+
+/**
+ * A pi `Usage`. Rebuilt here rather than imported so this module stays
+ * dependency-free for tests; the fields are pi's, and every one of them must be
+ * present: pi's `addUsageToTotals` dereferences `usage.cost.total` with no
+ * guard, so a partial object throws inside pi rather than at the call site.
+ *
+ * This is pi's convention for spend in anything handed to a consumer — every
+ * extension-facing payload that carries it takes the whole object
+ * (`ToolResultEvent`, `ToolResultEventResult`, `AssistantMessage`, …), never a
+ * flattened cost. Pi flattens only in computed read APIs it expects you to
+ * render, like `SessionStats`. So both places we hand usage to someone else —
+ * `AgentToolResult.usage` and the `subagents:completed` / `subagents:failed`
+ * events — carry this, and gain whatever pi adds to `Usage` for free.
+ */
+export type ReportedUsage = {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  totalTokens: number
+  cost: {
+    input: number
+    output: number
+    cacheRead: number
+    cacheWrite: number
+    total: number
+  }
+}
+
+/**
+ * Render an accumulator as a pi `Usage`, or undefined when nothing was spent —
+ * callers attach nothing rather than a zero, so a consumer can tell "spent
+ * nothing" from "never ran".
+ *
+ * `cacheRead` IS included, unlike in `getLifetimeTotal`: pi sums it across a
+ * session's own assistant messages, and the prefix genuinely is re-read and
+ * re-billed on every call. Only `total` is populated on the cost breakdown; pi
+ * reads nothing else from it, and the per-kind split is not tracked.
+ */
+export function toReportedUsage(u: LifetimeUsage): ReportedUsage | undefined {
+  const { input, output, cacheWrite, cacheRead = 0, cost = 0 } = u
+  if (
+    input === 0 &&
+    output === 0 &&
+    cacheWrite === 0 &&
+    cacheRead === 0 &&
+    cost === 0
+  )
+    return undefined
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    totalTokens: input + output + cacheRead + cacheWrite,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: cost },
+  }
+}
+
+/**
+ * Subagent spend that the parent session has not been told about yet.
+ *
+ * Subagents run in their own pi sessions, so none of what they spend appears in
+ * the parent's `getSessionStats()`. Pi does aggregate `toolResult.usage` into
+ * those stats, though — so the way back into the parent's footer and `/cost` is
+ * to hang the spend on a tool result. Background and scheduled agents finish
+ * between tool calls with nothing to hang it on, hence a pool: every assistant
+ * message lands here as it happens, and the next tool result we return carries
+ * whatever has accumulated.
+ *
+ * Drain empties it, so each message is reported exactly once no matter how many
+ * results are returned or how many agents were running.
+ */
+export class PendingUsagePool {
+  private pending: LifetimeUsage = {
+    input: 0,
+    output: 0,
+    cacheWrite: 0,
+    cacheRead: 0,
+    cost: 0,
+  }
+  private dirty = false
+
+  add(delta: LifetimeUsage): void {
+    addUsage(this.pending, delta)
+    this.dirty = true
+  }
+
+  /**
+   * Take everything accumulated so far as a pi `Usage`, resetting the pool.
+   * Returns undefined when nothing is pending, so callers can leave the tool
+   * result untouched rather than attaching a zero.
+   */
+  drain(): ReportedUsage | undefined {
+    if (!this.dirty) return undefined
+    const drained = toReportedUsage(this.pending)
+    this.pending = { input: 0, output: 0, cacheWrite: 0, cacheRead: 0, cost: 0 }
+    this.dirty = false
+    return drained
+  }
 }
 
 /** Minimal shape we read from upstream `getSessionStats()`. */

package/node_modules/@herbertgao/pi-subagents/src/worktree.ts

@@ -28,6 +28,26 @@ export interface WorktreeInfo {
   workPath: string
 }
 
+/**
+ * Project-wide switch for worktree isolation (`worktreeIsolation` in
+ * subagents.json). Default `true` — unchanged behaviour.
+ *
+ * The `"off"` isolation value gives a model a legal way to decline a worktree,
+ * but it still depends on the model choosing it. This is the deterministic half
+ * of the same fix: on a large repo where every worktree costs real time and
+ * disk (#184), turning it off means no caller can create one, whatever it
+ * passes.
+ */
+let worktreeIsolationEnabled = true
+
+export function setWorktreeIsolationEnabled(enabled: boolean): void {
+  worktreeIsolationEnabled = enabled
+}
+
+export function isWorktreeIsolationEnabled(): boolean {
+  return worktreeIsolationEnabled
+}
+
 export interface WorktreeCleanupResult {
   /** Whether changes were found in the worktree. */
   hasChanges: boolean

package/node_modules/@juicesharp/rpiv-ask-user-question/README.md

@@ -25,7 +25,7 @@ Nothing to set up — the tool is live as soon as Pi restarts. Hand the model a
 
 > Add caching to the API client.
 
-Rather than picking a strategy on your behalf, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `↑`/`↓`, choose with `Enter`, press `n` to attach a note, or land on the `Type something.` row to answer in your own words. While typing, `Shift+Enter` adds a line, `Ctrl+G` opens Pi's configured external editor, and `Ctrl+U` clears the draft; browsing another option and returning keeps what you wrote. `Esc` abandons the questionnaire entirely.
+Rather than picking a strategy on your behalf, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `↑`/`↓`, choose with `Enter`, press `n` to attach a note to a question — or a global note to the whole questionnaire from the Submit tab — or land on the `Type something.` row to answer in your own words. While typing, `Shift+Enter` adds a line, `Ctrl+G` opens Pi's configured external editor, and `Ctrl+U` clears the draft; browsing another option and returning keeps what you wrote. `Esc` abandons the questionnaire entirely.
 
 When the questionnaire begins waiting in an interactive TTY, it emits one standard terminal BEL (`\x07`). Your terminal configuration determines whether that appears as an audible alert, a visual alert, or nothing; redirected and non-TTY output is untouched.
 
@@ -33,7 +33,7 @@ When the questionnaire begins waiting in an interactive TTY, it emits one standa
 
 When the model asks several things at once, `Tab` moves between them and a Submit tab reviews everything before it goes back:
 
-![Submit tab of a four-question dialog: a Review your answers list showing Feature Type set to Bug fix and Testing set to Unit tests plus Integration tests, a warning naming Design Tab and Release as still unanswered, and a picker offering Submit answers or Cancel](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/submit-tab.jpg)
+![Submit tab of a four-question dialog: a Review your answers list showing Feature Type set to Bug fix and Testing set to Unit tests plus Integration tests, a warning naming Design Tab and Release as still unanswered, a picker offering Submit answers or Cancel, and a dim bottom key-hint row including n to add a note](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/submit-tab.jpg)
 
 ## What you get
 
@@ -41,9 +41,9 @@ When the model asks several things at once, `Tab` moves between them and a Submi
 - **You can always answer in your own words** — a `Type something.` row is appended to every question, single- or multi-select, widens to the full pane while you type, keeps its multiline draft visible in that row while you browse, and supports Pi's `Shift+Enter` newline and `Ctrl+G` external-editor flows.
 - **Compare real artifacts, not just labels** — an option can carry a markdown `preview` (ASCII mockup, code, diagram, config) that renders in a bordered box beside the option list.
 - **One interruption, not five** — up to four questions arrive in a single tabbed dialog, and the Submit tab lists your answers and names anything still blank before you commit.
-- **Notes on any answer** — `n` opens a multiline note editor on any question tab; the note travels back to the model alongside the choice without marking the question answered.
+- **Notes on any answer — or on all of them** — `n` opens a multiline note editor on any question tab, and on the Submit tab it opens one global note for the whole questionnaire. Per-question notes reach the model as `user notes: <text>`, the global note as `global note: <text>`; neither marks a question answered.
 - **Read the transcript behind the dialog** — `Ctrl+]` collapses the overlay so you can scroll the conversation, then brings it back with your answers intact.
-- **Works outside the terminal too** — in RPC and ACP hosts such as the VS Code pendant or Zed the questionnaire walks through the host's native dialogs, and in non-interactive runs the tool is removed from the model's tool list instead of failing every call.
+- **Works outside the terminal too** — in RPC and ACP hosts such as the VS Code pendant or Zed the questionnaire walks through the host's native dialogs (notes are terminal-only and do not carry over), and in non-interactive runs the tool is removed from the model's tool list instead of failing every call.
 
 ## Configuration
 
@@ -52,6 +52,7 @@ Optional. Settings live in `~/.config/rpiv-ask-user-question/config.json`; the f
 | Setting | What it does | Default |
 | --- | --- | --- |
 | `collapseKey` | Key that collapses and expands the dialog. Accepts Pi keybinding ids such as `alt+o`; `"off"` disables the shortcut. | `"ctrl+]"` |
+| `guidance.description` | Full replacement for the tool description the model sees. A non-empty string replaces the built-in text entirely — no merging. | built-in description |
 | `guidance.promptSnippet` | One-line description of the tool in the system prompt — tune how eagerly the model asks. | built-in snippet |
 | `guidance.promptGuidelines` | Usage guidelines given to the model, as a list of strings. | 4 built-in guidelines |
 

package/node_modules/@juicesharp/rpiv-ask-user-question/ask-user-question.ts

@@ -1,6 +1,12 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
-import { loadConfig, resolveCollapseKey, validateGuidanceFields } from "./config.js";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { isKeyRelease, isKeyRepeat, matchesKey, type OverlayHandle, type TUI } from "@earendil-works/pi-tui";
+import {
+	COLLAPSE_KEY_OFF,
+	formatKeySpecForDisplay,
+	loadConfig,
+	resolveCollapseKey,
+	validateGuidanceFields,
+} from "./config.js";
 import {
 	ASK_USER_BLOCKED_EVENT,
 	ASK_USER_PROMPT_EVENT,
@@ -9,7 +15,7 @@ import {
 } from "./events.js";
 // Static import is fine — rpc-fallback pulls only types + the i18n bridge,
 // none of the ~560ms TUI render graph that QuestionnaireSession lazy-loads.
-import { hasDialogUI, runRpcQuestionnaire } from "./rpc-fallback.js";
+import { type DialogUI, hasDialogUI, runRpcQuestionnaire } from "./rpc-fallback.js";
 import { displayLabel, t } from "./state/i18n-bridge.js";
 import { sentinelsToAppend } from "./state/row-intent.js";
 import { buildQuestionnaireResponse, buildToolResult } from "./tool/response-envelope.js";
@@ -47,6 +53,22 @@ function emitAskUserBlockedEvent(pi: ExtensionAPI, active: boolean): void {
 	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
 }
 
+/** Non-interactive host backstop (the reconciler normally strips the tool first). */
+function rejectWithoutUi() {
+	return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: "no_ui" });
+}
+
+/** Sequential native-dialog walker for RPC hosts; brackets it with the blocked-event pair + terminal bell. */
+async function runRpcPath(pi: ExtensionAPI, ui: DialogUI, typed: QuestionParams) {
+	emitAskUserBlockedEvent(pi, true);
+	try {
+		emitTerminalAttention();
+		return buildQuestionnaireResponse(await runRpcQuestionnaire(ui, typed), typed);
+	} finally {
+		emitAskUserBlockedEvent(pi, false);
+	}
+}
+
 /** Canonical tool name — single source of truth shared with the reconcile module. */
 export const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
 
@@ -84,6 +106,9 @@ export const PREWARM_DELAY_MS = 2000;
 
 type SessionModule = typeof import("./state/questionnaire-session.js");
 
+type SessionRef = { current: import("./state/questionnaire-session.js").QuestionnaireSession | null };
+type OverlayHandleRef = { current: OverlayHandle | undefined };
+
 type SessionLoad =
 	| { ok: true; module: SessionModule }
 	| { ok: false; error: Extract<QuestionnaireError, "session_load_failed" | "stale_module_cache">; message: string };
@@ -118,6 +143,122 @@ export async function loadQuestionnaireSession(): Promise<SessionLoad> {
 	return { ok: true, module: mod };
 }
 
+/**
+ * Register the raw terminal listener that toggles collapse while the overlay is hidden.
+ * Returns the remover, or undefined when the key is off / the host has no raw input hook —
+ * callers derive `canReopenWhileHidden` from that.
+ */
+function registerCollapseKeyListener(
+	ctx: ExtensionContext,
+	collapseKey: string,
+	sessionRef: SessionRef,
+	overlayHandleRef: OverlayHandleRef,
+): (() => void) | undefined {
+	if (collapseKey === COLLAPSE_KEY_OFF || typeof ctx.ui.onTerminalInput !== "function") return undefined;
+	let hasAnnouncedHide = false;
+	return ctx.ui.onTerminalInput((data) => {
+		const handle = overlayHandleRef.current;
+		if (!handle) return undefined;
+		// Only act while the questionnaire is hidden (its handleInput is
+		// unreachable) or actually focused. When some other overlay is on
+		// top (e.g. `/btw`), leave the keystroke to that overlay instead of
+		// toggling the questionnaire from underneath it.
+		if (!handle.isHidden() && !handle.isFocused()) return undefined;
+		if (!matchesKey(data, collapseKey as Parameters<typeof matchesKey>[1])) return undefined;
+		// Kitty-protocol terminals report press, repeat, and release separately.
+		// Toggle only on the initial press so a tap does not immediately reopen
+		// the overlay and a held key does not toggle it repeatedly.
+		if (isKeyRelease(data) || isKeyRepeat(data)) return { consume: true };
+		sessionRef.current?.toggleCollapsedExternal();
+		if (handle.isHidden() && !hasAnnouncedHide) {
+			hasAnnouncedHide = true;
+			ctx.ui.notify?.(`ask_user_question hidden — press ${formatKeySpecForDisplay(collapseKey)} to reopen`, "info");
+		}
+		return { consume: true };
+	});
+}
+
+/**
+ * Build the `ctx.ui.custom` component factory: constructs the session (capturing it in
+ * `sessionRef`) and exposes its component. `editInput` keeps its two dynamic imports —
+ * they must stay lazy per-invocation.
+ */
+function makeSessionFactory(config: {
+	ctx: ExtensionContext;
+	typed: QuestionParams;
+	itemsByTab: WrappingSelectItem[][];
+	collapseKey: string;
+	canReopenWhileHidden: boolean;
+	sessionRef: SessionRef;
+	Session: SessionModule["QuestionnaireSession"];
+}) {
+	const { ctx, typed, itemsByTab, collapseKey, canReopenWhileHidden, sessionRef, Session } = config;
+	return (
+		tui: TUI,
+		theme: Theme,
+		keybindings: import("./state/questionnaire-session.js").QuestionnaireSessionConfig["keybindings"],
+		done: (result: QuestionnaireResult) => void,
+	): import("./state/questionnaire-session.js").QuestionnaireSessionComponent => {
+		const session = new Session({
+			tui,
+			theme,
+			params: typed,
+			itemsByTab,
+			done,
+			keybindings,
+			editInput: async (value) => {
+				try {
+					const [{ SettingsManager }, { editWithExternalEditor }] = await Promise.all([
+						import("@earendil-works/pi-coding-agent"),
+						import("./state/external-editor.js"),
+					]);
+					const editorCommand = SettingsManager.create(ctx.cwd, undefined, {
+						projectTrusted: ctx.isProjectTrusted(),
+					}).getExternalEditorCommand();
+					if (!editorCommand) throw new Error("No external editor command is configured");
+					return await editWithExternalEditor(tui, editorCommand, value);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					ctx.ui.notify(`${t("editor.failed", "External editor failed")}: ${message}`, "error");
+					return undefined;
+				}
+			},
+			collapseKey,
+			canReopenWhileHidden,
+		});
+		sessionRef.current = session;
+		return session.component;
+	};
+}
+
+/**
+ * A TUI questionnaire ALWAYS resolves a QuestionnaireResult (cancel included), 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.
+ */
+async function resolveUndefinedResult(ctx: ExtensionContext, typed: QuestionParams) {
+	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" });
+}
+
+/**
+ * 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.
+ */
+function prewarmSessionGraph(): void {
+	const timer = setTimeout(() => void loadQuestionnaireSession().catch(() => undefined), PREWARM_DELAY_MS);
+	timer.unref?.();
+}
+
 export function buildItemsForQuestion(question: QuestionData): WrappingSelectItem[] {
 	const items: WrappingSelectItem[] = question.options.map((o) => ({
 		kind: "option",
@@ -138,12 +279,7 @@ export const DEFAULT_PROMPT_GUIDELINES: string[] = [
 	"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:
+export const DEFAULT_TOOL_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
@@ -161,14 +297,21 @@ Use the optional \`preview\` field on options when presenting concrete artifacts
 - 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).`,
+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).`;
+
+export function registerAskUserQuestionTool(pi: ExtensionAPI): void {
+	const guidance = validateGuidanceFields(loadConfig().guidance);
+	pi.registerTool({
+		name: ASK_USER_QUESTION_TOOL_NAME,
+		label: "Ask User Question",
+		description: guidance.description ?? DEFAULT_TOOL_DESCRIPTION,
 		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" });
+			if (!ctx.hasUI) return rejectWithoutUi();
 
 			const validation = validateQuestionnaire(typed);
 			if (!validation.ok) {
@@ -189,13 +332,7 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 			// 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 {
-					emitTerminalAttention();
-					return buildQuestionnaireResponse(await runRpcQuestionnaire(ctx.ui, typed), typed);
-				} finally {
-					emitAskUserBlockedEvent(pi, false);
-				}
+				return runRpcPath(pi, ctx.ui, typed);
 			}
 
 			const itemsByTab: WrappingSelectItem[][] = typed.questions.map((q) => buildItemsForQuestion(q));
@@ -217,72 +354,27 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 			// user toggles collapse, and register a raw terminal input listener for the
 			// same key so the toggle still works while the overlay is hidden (pi-tui does
 			// not route input to a hidden overlay's `component.handleInput`).
-			const sessionRef: {
-				current: import("./state/questionnaire-session.js").QuestionnaireSession | null;
-			} = { current: null };
-			const overlayHandleRef: { current: import("@earendil-works/pi-tui").OverlayHandle | undefined } = {
-				current: undefined,
-			};
-			let hasAnnouncedHide = false;
-			let removeOverlayInputListener: (() => void) | undefined;
-
-			if (collapseKey !== "off" && typeof ctx.ui.onTerminalInput === "function") {
-				removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
-					const handle = overlayHandleRef.current;
-					if (!handle) return undefined;
-					// Only act while the questionnaire is hidden (its handleInput is
-					// unreachable) or actually focused. When some other overlay is on
-					// top (e.g. `/btw`), leave the keystroke to that overlay instead of
-					// toggling the questionnaire from underneath it.
-					if (!handle.isHidden() && !handle.isFocused()) return undefined;
-					if (!matchesKey(data, collapseKey as Parameters<typeof matchesKey>[1])) return undefined;
-					// Kitty-protocol terminals report press, repeat, and release separately.
-					// Toggle only on the initial press so a tap does not immediately reopen
-					// the overlay and a held key does not toggle it repeatedly.
-					if (isKeyRelease(data) || isKeyRepeat(data)) return { consume: true };
-					sessionRef.current?.toggleCollapsedExternal();
-					if (handle.isHidden() && !hasAnnouncedHide) {
-						hasAnnouncedHide = true;
-						ctx.ui.notify?.(`ask_user_question hidden — press ${collapseKey} to reopen`, "info");
-					}
-					return { consume: true };
-				});
-			}
+			const sessionRef: SessionRef = { current: null };
+			const overlayHandleRef: OverlayHandleRef = { current: undefined };
+			const removeOverlayInputListener = registerCollapseKeyListener(ctx, collapseKey, sessionRef, overlayHandleRef);
+			// Hiding the overlay is only reversible through the raw listener above, so
+			// the session may emit `setHidden` only when it was actually registered;
+			// otherwise collapse falls back to the visible one-line row.
+			const canReopenWhileHidden = removeOverlayInputListener !== undefined;
 
 			emitAskUserBlockedEvent(pi, true);
 			try {
 				emitTerminalAttention();
 				const result = await ctx.ui.custom<QuestionnaireResult>(
-					(tui, theme, keybindings, done) => {
-						const session = new QuestionnaireSession({
-							tui,
-							theme,
-							params: typed,
-							itemsByTab,
-							done,
-							keybindings,
-							editInput: async (value) => {
-								try {
-									const [{ SettingsManager }, { editWithExternalEditor }] = await Promise.all([
-										import("@earendil-works/pi-coding-agent"),
-										import("./state/external-editor.js"),
-									]);
-									const editorCommand = SettingsManager.create(ctx.cwd, undefined, {
-										projectTrusted: ctx.isProjectTrusted(),
-									}).getExternalEditorCommand();
-									if (!editorCommand) throw new Error("No external editor command is configured");
-									return await editWithExternalEditor(tui, editorCommand, value);
-								} catch (error) {
-									const message = error instanceof Error ? error.message : String(error);
-									ctx.ui.notify(`${t("editor.failed", "External editor failed")}: ${message}`, "error");
-									return undefined;
-								}
-							},
-							collapseKey,
-						});
-						sessionRef.current = session;
-						return session.component;
-					},
+					makeSessionFactory({
+						ctx,
+						typed,
+						itemsByTab,
+						collapseKey,
+						canReopenWhileHidden,
+						sessionRef,
+						Session: QuestionnaireSession,
+					}),
 					{
 						overlay: true,
 						overlayOptions: {
@@ -298,17 +390,8 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 					},
 				);
 
-				// 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 resolveUndefinedResult(ctx, typed);
 				}
 
 				return buildQuestionnaireResponse(result, typed);
@@ -319,16 +402,7 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 		},
 	});
 
-	// 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?.();
+	prewarmSessionGraph();
 }
 
 export { buildQuestionnaireResponse, buildToolResult };

package/node_modules/@juicesharp/rpiv-ask-user-question/config.ts

@@ -68,6 +68,31 @@ export function resolveCollapseKey(config: Pick<AskUserQuestionConfig, "collapse
 	return isValidCollapseKeySpec(raw) ? raw : DEFAULT_COLLAPSE_KEY;
 }
 
+// The only compound-word names in SPECIAL_KEYS — first-letter capitalization
+// alone would render them "Pageup"/"Pagedown".
+const COMPOUND_KEY_DISPLAY: Record<string, string> = {
+	pageup: "PageUp",
+	pagedown: "PageDown",
+};
+
+/**
+ * Pretty-print a resolved key spec for UI copy: each `+`-part gets its first
+ * character uppercased (`"ctrl+]"` → `"Ctrl+]"`, `"alt+o"` → `"Alt+O"`,
+ * `"f9"` → `"F9"`, `"ctrl+pagedown"` → `"Ctrl+PageDown"`). Display-only — key
+ * matching always uses the raw lowercase spec (`matchesKey` lowercases ids),
+ * so never feed the result back into it.
+ */
+export function formatKeySpecForDisplay(spec: CollapseKeySpec): string {
+	return spec
+		.split("+")
+		.map(
+			(part) =>
+				COMPOUND_KEY_DISPLAY[part] ??
+				(part.length <= 1 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1)),
+		)
+		.join("+");
+}
+
 export function loadConfig(): AskUserQuestionConfig {
 	return loadJsonConfigWithLegacyFallback<AskUserQuestionConfig>("rpiv-ask-user-question");
 }

package/node_modules/@juicesharp/rpiv-ask-user-question/docs/configuration.md

@@ -19,6 +19,7 @@ A complete example:
 {
   "collapseKey": "alt+o",
   "guidance": {
+    "description": "Ask the user structured questions whenever requirements are ambiguous.",
     "promptSnippet": "Ask me before guessing on anything ambiguous",
     "promptGuidelines": [
       "Batch every clarifying question into one ask_user_question call.",
@@ -58,6 +59,7 @@ type are likewise dropped back to their default without a warning.
 | Setting | What it does | Default |
 | --- | --- | --- |
 | `collapseKey` | Key that collapses and expands the dialog overlay. | `"ctrl+]"` |
+| `guidance.description` | Full text of the tool description the model sees. Replaces the built-in default entirely — no merging. | built-in description |
 | `guidance.promptSnippet` | One-line snippet describing the tool in the system prompt. | built-in snippet |
 | `guidance.promptGuidelines` | List of usage guidelines given to the model. | 4 built-in guidelines |
 
@@ -83,11 +85,18 @@ strict on purpose: Pi's parser takes the last `+`-separated part as the key and
 unknown parts, so a typo like `"ctr+]"` would otherwise silently capture every bare `]`
 keypress at the terminal level.
 
-One known rough edge: the footer hint line inside the dialog always reads `Ctrl+] to
-collapse` and does not interpolate a custom `collapseKey`. The one-shot notification you
-get when the dialog first collapses *does* name your configured key.
+The footer hint inside the dialog names whatever key you configure (`Alt+O to collapse`
+for `"alt+o"`), as do the collapsed one-line footer and the one-shot notification shown
+when the dialog is first hidden. With `"off"` the collapse hint is dropped from the
+footer entirely, since no shortcut can fire.
 
-### `guidance.promptSnippet` and `guidance.promptGuidelines`
+### `guidance.description`, `guidance.promptSnippet` and `guidance.promptGuidelines`
+
+`guidance.description` replaces the entire built-in description Pi registers for the
+`ask_user_question` tool — the text the model reads when deciding how to use it. There is
+no merging: a valid value wins wholesale. It is used only when it is a non-empty string;
+anything else falls back to the built-in default. Like the other guidance fields it is read
+once, when the extension registers the tool, so changes take effect on the next Pi restart.
 
 These replace the text Pi puts in the system prompt about when to reach for
 `ask_user_question`. Use them to make the model ask more or less often, or to enforce a