@herbertgao/pi-extensions 2026.8.5 → 2026.8.7

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
@@ -134,11 +154,15 @@ export function cleanupWorktree(
       // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
       const safeDesc = agentDescription.slice(0, 200)
       const commitMsg = `pi-agent: ${safeDesc}`
-      execFileSync("git", ["commit", "--no-verify", "-m", commitMsg], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 10000,
-      })
+      execFileSync(
+        "git",
+        ["commit", "--no-verify", "--no-gpg-sign", "-m", commitMsg],
+        {
+          cwd: worktree.path,
+          stdio: "pipe",
+          timeout: 10000,
+        },
+      )
     } else {
       const currentSha = execFileSync("git", ["rev-parse", "HEAD"], {
         cwd: worktree.path,

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

@@ -27,6 +27,8 @@ Nothing to set up — the tool is live as soon as Pi restarts. Hand the model a
 
 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.
 
+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.
+
 ![Single question in the dialog: the tab strip reads Feature Type, Design Tab, Testing, Release, Submit; the question Which real development task are we planning right now? sits above four numbered options — Bug fix (Recommended), New feature, Refactor, Perf tuning — each with a one-line description, followed by the appended Type something. row](https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/single-question.jpg)
 
 When the model asks several things at once, `Tab` moves between them and a Submit tab reviews everything before it goes back:
@@ -50,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 {
+	COLLAPSE_KEY_OFF,
+	formatKeySpecForDisplay,
+	loadConfig,
+	resolveCollapseKey,
+	validateGuidanceFields,
+} from "./config.js";
 import {
 	ASK_USER_BLOCKED_EVENT,
 	ASK_USER_PROMPT_EVENT,
@@ -61,6 +67,24 @@ const ERROR_SESSION_LOAD_FAILED =
 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.";
 
+/** Standard terminal bell — same byte rpiv-warp exports as OSC_TERMINATOR. */
+export const BEL = "\x07";
+
+/**
+ * Emit one portable terminal attention signal without touching redirected output.
+ * Writes to stdout rather than rpiv-warp's `/dev/tty` transport: the `isTTY` gate
+ * both proves an interactive terminal owns the coming wait and keeps the byte out
+ * of piped RPC transports (VS Code pendant, Zed) — a `/dev/tty` write would ring
+ * even when the questionnaire renders in a remote host's own UI.
+ */
+function emitTerminalAttention(): void {
+	try {
+		if (process.stdout.isTTY) process.stdout.write(BEL);
+	} catch {
+		// Terminal attention is best effort; the questionnaire must still proceed.
+	}
+}
+
 /** Delay before the background session-graph pre-warm; mirrors rpiv-workflow's /wf prewarm. */
 export const PREWARM_DELAY_MS = 2000;
 
@@ -120,12 +144,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
@@ -143,7 +162,14 @@ 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,
@@ -173,6 +199,7 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 			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);
@@ -207,7 +234,7 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 			let hasAnnouncedHide = false;
 			let removeOverlayInputListener: (() => void) | undefined;
 
-			if (collapseKey !== "off" && typeof ctx.ui.onTerminalInput === "function") {
+			if (collapseKey !== COLLAPSE_KEY_OFF && typeof ctx.ui.onTerminalInput === "function") {
 				removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
 					const handle = overlayHandleRef.current;
 					if (!handle) return undefined;
@@ -224,14 +251,22 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 					sessionRef.current?.toggleCollapsedExternal();
 					if (handle.isHidden() && !hasAnnouncedHide) {
 						hasAnnouncedHide = true;
-						ctx.ui.notify?.(`ask_user_question hidden — press ${collapseKey} to reopen`, "info");
+						ctx.ui.notify?.(
+							`ask_user_question hidden — press ${formatKeySpecForDisplay(collapseKey)} to reopen`,
+							"info",
+						);
 					}
 					return { consume: true };
 				});
 			}
+			// 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({
@@ -259,6 +294,7 @@ Preview content is rendered as markdown in a monospace box. Multi-line text with
 								}
 							},
 							collapseKey,
+							canReopenWhileHidden,
 						});
 						sessionRef.current = session;
 						return session.component;

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

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

@@ -11,6 +11,12 @@ render at all.
 | RPC / ACP host (VS Code pendant, Zed, Paseo) | `ask_user_question` in its tool list | A sequence of the host's own native select and input dialogs |
 | Non-interactive run (no UI) | Nothing — the tool is removed | Nothing |
 
+### Terminal attention
+
+After UI availability and questionnaire validation succeed, the package emits exactly one standard terminal BEL (`\x07`) immediately before the interactive wait begins. The signal is sent to `stdout` only when `process.stdout.isTTY` is true, so redirected output and non-TTY RPC streams stay untouched. A TTY-backed RPC dialog walker receives the same signal as the TUI path.
+
+The BEL is best effort: if the synchronous terminal write fails, the questionnaire continues and its existing prompt/blocked lifecycle and result envelope are unchanged. The terminal configuration decides whether the BEL is audible, visual, or ignored. No BEL is emitted for missing UI, invalid questionnaires, or a failed TUI session load.
+
 ### Non-interactive runs
 
 A `before_agent_start` hook reconciles the active tool set against `ctx.hasUI` before every
@@ -58,7 +64,8 @@ Some parts of the dialog exist only under the right conditions:
 | `Type something.` row | Always |
 | Side-by-side preview | An option carries a `preview`, and terminal and pane are both ≥ 100 columns |
 | Preview pane at all | Single-select questions only |
-| Collapse shortcut | `collapseKey` is not `"off"` and the host exposes raw terminal input |
+| Collapse shortcut | `collapseKey` is not `"off"` |
+| Full overlay hide on collapse | The host also exposes raw terminal input (the only path that can reopen a hidden overlay); without it, collapsing shrinks the dialog to a visible one-line row instead |
 | Localized chrome | `@juicesharp/rpiv-i18n` is installed |
 
 ## Loading and startup cost

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

@@ -71,7 +71,9 @@ No code change is required.
 1. Copy `locales/en.json` to `locales/<code>.json`, where `<code>` is a locale the SDK
    supports.
 2. Translate the values. Keep every key, and keep the placeholders and leading symbols
-   (`↑/↓`, `⚠`) intact.
+   (`↑/↓`, `⚠`) intact. `hint.collapse` and `hint.expand_line` contain a literal `{key}`
+   placeholder that is replaced at render time with the user's configured `collapseKey` —
+   keep it verbatim, positioned wherever your language's word order wants the key name.
 3. Restart Pi and select the language with `/languages`.
 
 The loader iterates the SDK's supported-locale list over this directory at startup, so a

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/en.json

@@ -12,8 +12,8 @@
   "hint.toggle": "Space to toggle",
   "hint.notes": "n to add notes",
   "hint.tab": "Tab to switch questions",
-  "hint.collapse": "Ctrl+] to collapse",
-  "hint.expand_line": "Ctrl+] to expand · Esc to cancel",
+  "hint.collapse": "{key} to collapse",
+  "hint.expand_line": "{key} to expand · Esc to cancel",
   "hint.cancel": "Esc to cancel",
 
   "review.heading": "Review your answers",

package/node_modules/@juicesharp/rpiv-ask-user-question/locales/zh.json

@@ -14,8 +14,8 @@
   "hint.toggle": "空格切换",
   "hint.notes": "按 n 添加备注",
   "hint.tab": "Tab 切换问题",
-  "hint.collapse": "Ctrl+] 折叠",
-  "hint.expand_line": "Ctrl+] 展开 · Esc 取消",
+  "hint.collapse": "{key} 折叠",
+  "hint.expand_line": "{key} 展开 · Esc 取消",
   "hint.cancel": "Esc 取消",
 
   "review.heading": "检查你的答案",

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

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-ask-user-question",
-	"version": "2.5.2",
+	"version": "2.6.4",
 	"description": "Pi extension. A structured questionnaire the model can put to you when it would otherwise guess, with typed options instead of free-form replies.",
 	"keywords": [
 		"pi-package",
@@ -78,6 +78,7 @@
 		"view/tab-content-strategy.ts"
 	],
 	"pi": {
+		"image": "https://raw.githubusercontent.com/juicesharp/rpiv-mono/main/packages/rpiv-ask-user-question/docs/cover.png",
 		"extensions": [
 			"./index.ts"
 		]
@@ -93,7 +94,7 @@
 		}
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^2.5.2",
+		"@juicesharp/rpiv-config": "^2.6.4",
 		"typebox": "^1.1.24"
 	}
 }

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

@@ -40,6 +40,13 @@ export interface QuestionnaireBuildConfig {
 	isMulti: boolean;
 	initialState: QuestionnaireState;
 	getCurrentTab: () => number;
+	/**
+	 * Resolved collapse key spec (`"ctrl+]"`, `"alt+o"`, or `"off"`). Threaded to
+	 * `DialogConfig` as construction-time config so the footer hint can name the
+	 * real key — deliberately NOT part of `QuestionnaireState`, which stays free
+	 * of runtime context.
+	 */
+	collapseKey: string;
 }
 
 export interface QuestionnaireBuilt {
@@ -109,6 +116,7 @@ class QuestionnaireBuilder {
 	private readonly isMulti: boolean;
 	private readonly initialState: QuestionnaireState;
 	private readonly getCurrentTab: () => number;
+	private readonly collapseKey: string;
 
 	private readonly selectTheme: WrappingSelectTheme;
 	private readonly markdownTheme = getMarkdownTheme();
@@ -125,6 +133,7 @@ class QuestionnaireBuilder {
 		this.isMulti = config.isMulti;
 		this.initialState = config.initialState;
 		this.getCurrentTab = config.getCurrentTab;
+		this.collapseKey = config.collapseKey;
 
 		this.selectTheme = this.makeSelectTheme();
 		const textEditorTheme = editorTheme(this.theme);
@@ -258,6 +267,7 @@ class QuestionnaireBuilder {
 				getBodyHeight: heights.global,
 				getCurrentBodyHeight: heights.current,
 				getTerminalRows: this.getTerminalRows,
+				collapseKey: this.collapseKey,
 			},
 			{ state: this.initialState, activePreviewPane: this.pickInitialActivePreview(tabs) },
 		);

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

@@ -174,7 +174,9 @@ export function routeKey(data: string, state: QuestionnaireState, runtime: Quest
 	// replaces the lazily imported QuestionnaireSession graph on disk. Passing
 	// undefined into matchesKey reaches parseKeyId().toLowerCase() and crashes the
 	// entire host process, so keep the runtime boundary defensive even though the
-	// TypeScript contract requires a string.
+	// TypeScript contract requires a string. The "off" literal is deliberate:
+	// importing COLLAPSE_KEY_OFF would pull ../config.js (and its rpiv-config
+	// loader graph) into this pure module for a string that cannot change.
 	if (
 		typeof runtime.collapseKey === "string" &&
 		runtime.collapseKey !== "off" &&

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

@@ -1,8 +1,9 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Editor, OverlayHandle, TUI } from "@earendil-works/pi-tui";
+import { COLLAPSE_KEY_OFF, formatKeySpecForDisplay } from "../config.js";
 import type { QuestionData, QuestionnaireResult, QuestionParams } from "../tool/types.js";
 import type { WrappingSelectItem } from "../view/components/wrapping-select.js";
-import { COLLAPSED_HINT } from "../view/dialog-builder.js";
+import { COLLAPSED_HINT_TEMPLATE, HINT_PART_CANCEL, KEY_PLACEHOLDER } from "../view/dialog-builder.js";
 import type { QuestionnairePropsAdapter } from "../view/props-adapter.js";
 import { buildQuestionnaire } from "./build-questionnaire.js";
 import { t } from "./i18n-bridge.js";
@@ -21,6 +22,14 @@ export interface QuestionnaireSessionConfig {
 	editInput: (value: string) => Promise<string | undefined>;
 	/** Key spec for the collapse/expand shortcut, e.g. `"ctrl+]"` or `"alt+o"`. */
 	collapseKey: string;
+	/**
+	 * True iff `execute()` registered the raw `ctx.ui.onTerminalInput` listener — the only
+	 * path that can reach a hidden overlay. Gates the `set_overlay_hidden` effect: a host
+	 * that delivers an `OverlayHandle` but no raw terminal input must fall back to the
+	 * visible one-line collapsed row (which keeps focus and input routing), or collapsing
+	 * would hide the overlay into a state nothing can reopen.
+	 */
+	canReopenWhileHidden: boolean;
 }
 
 export interface QuestionnaireSessionComponent {
@@ -64,6 +73,7 @@ export class QuestionnaireSession {
 	private readonly keybindings: QuestionnaireRuntime["keybindings"];
 	private readonly editInput: QuestionnaireSessionConfig["editInput"];
 	private readonly collapseKey: string;
+	private readonly canReopenWhileHidden: boolean;
 	private inputEditorOpen = false;
 
 	/**
@@ -86,6 +96,7 @@ export class QuestionnaireSession {
 		this.keybindings = config.keybindings;
 		this.editInput = config.editInput;
 		this.collapseKey = config.collapseKey;
+		this.canReopenWhileHidden = config.canReopenWhileHidden;
 
 		const built = buildQuestionnaire({
 			tui: this.tui,
@@ -95,6 +106,7 @@ export class QuestionnaireSession {
 			isMulti: this.isMulti,
 			initialState: this.state,
 			getCurrentTab: () => this.state.currentTab,
+			collapseKey: this.collapseKey,
 		});
 
 		this.notesInput = built.notesInput;
@@ -106,10 +118,18 @@ export class QuestionnaireSession {
 		// the overlay to `min(lines.length, maxHeight)`, so returning one line shrinks
 		// the bottom-anchored overlay from full-height to one row and the transcript
 		// behind it becomes readable (#47). The overlay stays focused and in the
-		// stack, so Ctrl+] still routes here to expand.
-		const collapsedRender = (_width: number): string[] => [
-			theme.fg("dim", ` ${t("hint.expand_line", COLLAPSED_HINT)} `),
-		];
+		// stack, so the collapse key still routes here to expand. `t` stays inside the
+		// closure (live locale updates); the key display is static per session.
+		//
+		// With collapseKey "off" the router and raw listener never toggle `collapsed`,
+		// but `toggleCollapsedExternal()` is a public ungated entry — fall back to the
+		// cancel-only line rather than rendering a literal "Off to expand".
+		const collapseKeyDisplay = formatKeySpecForDisplay(this.collapseKey);
+		const collapsedHintLine = (): string =>
+			this.collapseKey === COLLAPSE_KEY_OFF
+				? t("hint.cancel", HINT_PART_CANCEL)
+				: t("hint.expand_line", COLLAPSED_HINT_TEMPLATE).replace(KEY_PLACEHOLDER, collapseKeyDisplay);
+		const collapsedRender = (_width: number): string[] => [theme.fg("dim", ` ${collapsedHintLine()} `)];
 
 		this.component = {
 			render: (width) => (this.state.collapsed ? collapsedRender(width) : built.render(width)),
@@ -178,8 +198,11 @@ export class QuestionnaireSession {
 				return;
 			case "set_overlay_hidden":
 				// No-op until `setOverlayHandle` has been called (the handle arrives via
-				// `ctx.ui.custom`'s `onHandle` right after the overlay is shown).
-				this.overlayHandle?.setHidden(effect.hidden);
+				// `ctx.ui.custom`'s `onHandle` right after the overlay is shown), and
+				// suppressed entirely when no raw terminal listener exists — hiding would
+				// then be irreversible (pi-tui routes no input to a hidden overlay), so the
+				// visible one-line collapsed row serves as the fallback rendering instead.
+				if (this.canReopenWhileHidden) this.overlayHandle?.setHidden(effect.hidden);
 				return;
 			case "done":
 				this.done(effect.result);

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

@@ -25,12 +25,20 @@ export interface QuestionnaireState {
 	/** Canonical mirror of the in-flight notes editor; runtime mirrors after `forward_notes_keystroke`. */
 	notesDraft: string;
 	/**
-	 * Collapsed mode: the questionnaire shrinks to a single hint row so the agent transcript
-	 * behind the bottom-anchored overlay becomes readable. Toggled by `Ctrl+]` from any state;
-	 * while true, every keystroke except cancel is swallowed (see `routeKey`). The overlay
-	 * stays focused so the expand key never falls through to an underlying overlay (e.g.
-	 * `/btw`) — that focus-restore property is the entire reason we render a collapsed row
-	 * instead of calling `OverlayHandle.setHidden(true)`.
+	 * Collapsed mode: the questionnaire gets out of the way so the agent transcript behind
+	 * the bottom-anchored overlay becomes readable. Toggled by the configured collapse key
+	 * from any state; while true, every keystroke except cancel is swallowed (see
+	 * `routeKey`). Two renderings, chosen by host capability:
+	 *
+	 * - Hosts with an `OverlayHandle` AND a raw `onTerminalInput` listener (real pi-tui):
+	 *   the `set_overlay_hidden` effect fully hides the overlay; the raw listener registered
+	 *   in `execute()` reopens it, because pi-tui routes no input to a hidden overlay.
+	 * - Hosts without the raw listener (or without a handle): the overlay stays visible and
+	 *   shrinks to a single hint row. The row keeps focus and input routing, so the same key
+	 *   expands it and Esc cancels, and the expand key never falls through to an underlying
+	 *   overlay (e.g. `/btw`). The session gates `set_overlay_hidden` on the listener's
+	 *   existence (`canReopenWhileHidden`) so a handle-bearing host without raw input can
+	 *   never hide the overlay into a state nothing can reopen.
 	 */
 	collapsed: boolean;
 }