pi-ask-user 0.11.2 → 0.13.0

package/README.md

@@ -61,10 +61,10 @@ The registered tool name is:
 |-----------|------|---------|-------------|
 | `question` | `string` | *required* | The question to ask the user |
 | `context` | `string?` | — | Relevant context summary shown before the question |
-| `options` | `(string \| {title, description?})[]?` | `[]` | Multiple-choice options |
+| `options` | `{title, description?}[]?` | `[]` | Multiple-choice options. The schema is a flat object shape (no `anyOf`, which some provider proxies strip or reject); plain strings and common alias keys (`label`, `text`, `value`, `name`, `option`) are still accepted at runtime |
 | `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
 | `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
-| `allowComment` | `boolean?` | `false` | Expose a user-toggleable extra-context option in the custom UI (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
+| `allowComment` | `boolean?` | env var or `false` | Expose a user-toggleable extra-context option in the custom UI (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
 | `displayMode` | `"overlay" \| "inline"?` | env var or `"overlay"` | Controls custom UI rendering: `overlay` shows the centered modal (current behavior), `inline` renders without overlay framing |
 | `overlayToggleKey` | `string?` | env var or `"alt+o"` | Shortcut for hiding/showing the overlay popup (overlay mode only). Pi-TUI key spec, e.g. `"alt+o"`, `"ctrl+shift+h"`. Pass `"off"` to disable. |
 | `commentToggleKey` | `string?` | env var or `"ctrl+g"` | Shortcut for toggling the optional comment/extra-context row when `allowComment: true`. Pass `"off"` to disable. |
@@ -77,7 +77,7 @@ The registered tool name is:
   "question": "Which option should we use?",
   "context": "We are choosing a deploy target.",
   "options": [
-    "staging",
+    { "title": "staging" },
     { "title": "production", "description": "Customer-facing" }
   ],
   "allowMultiple": false,
@@ -95,10 +95,13 @@ Configure your defaults globally by setting these in your shell profile (`~/.zsh
 
 ```bash
 export PI_ASK_USER_DISPLAY_MODE=inline
+export PI_ASK_USER_ALLOW_COMMENT=true
 export PI_ASK_USER_OVERLAY_TOGGLE_KEY=alt+h
 export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 ```
 
+Environment variables must be present in the process that launches Pi. If Pi is launched from a desktop app or a different shell, changes in `~/.zshrc` may not be inherited; launch Pi from a terminal where `echo $PI_ASK_USER_DISPLAY_MODE` shows the expected value.
+
 ### Display mode
 
 Effective order:
@@ -109,6 +112,14 @@ Effective order:
 
 Unrecognised values are silently ignored and fall back to `"overlay"`.
 
+### Optional comments
+
+Effective order:
+
+1. Per-call `allowComment` parameter (if provided)
+2. `PI_ASK_USER_ALLOW_COMMENT` (`true`, `1`, `yes`, or `on`; corresponding false values are also accepted)
+3. Fallback default: `false`
+
 ### Shortcuts
 
 Effective order for both `overlayToggleKey` and `commentToggleKey`:
@@ -133,6 +144,10 @@ While an `ask_user` prompt is open:
 
 If you prefer never to see the overlay, set `displayMode: "inline"` per call or `PI_ASK_USER_DISPLAY_MODE=inline` globally.
 
+## Known limitations
+
+- **Overlays cannot draw over inline images** ([#8](https://github.com/edlsh/pi-ask-user/issues/8)). Pi-TUI's overlay compositor skips rows occupied by terminal images (Kitty/iTerm2 graphics), so an `ask_user` overlay that intersects an image is partially or fully invisible. This must be fixed upstream in pi-tui (`compositeLineAt` returns image rows unchanged). Until then, `displayMode: "inline"` (or `PI_ASK_USER_DISPLAY_MODE=inline`) sidesteps the overlay compositor entirely and should keep the prompt visible.
+
 ## Result details
 
 All tool results include a structured `details` object for rendering and session state reconstruction:
@@ -153,4 +168,4 @@ interface AskToolDetails {
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md).
+See [CHANGELOG.md](./CHANGELOG.md).

package/index.ts

@@ -11,6 +11,7 @@ import { Type, type TUnsafe } from "@sinclair/typebox";
 import {
    Container,
    type Component,
+   CURSOR_MARKER,
    decodeKittyPrintable,
    Editor,
    type EditorTheme,
@@ -22,13 +23,14 @@ import {
    type MarkdownTheme,
    matchesKey,
    type OverlayHandle,
+   type OverlayOptions,
    Spacer,
    Text,
    type TUI,
    truncateToWidth,
    wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
-import { renderSingleSelectRows } from "./single-select-layout";
+import { renderSingleSelectRows, type QuestionOption } from "./single-select-layout";
 
 import { createRequire } from "node:module";
 const _require = createRequire(import.meta.url);
@@ -120,18 +122,28 @@ interface AskToolDetails {
 
 type AskUIResult = AskResponse;
 
-function normalizeOptions(options: AskOptionInput[]): QuestionOption[] {
-   return options
-      .map((option) => {
-         if (typeof option === "string") {
-            return { title: option };
-         }
-         if (option && typeof option === "object" && typeof option.title === "string") {
-            return { title: option.title, description: option.description };
+// Key aliases models fall back to when a schema-mangling proxy (Google
+// function calling, Codex-style backends, cmux) strips the option shape and
+// the model has to guess. See issue #22.
+const OPTION_TITLE_KEYS = ["title", "label", "text", "value", "name", "option"] as const;
+
+function coerceOption(option: unknown): QuestionOption | null {
+   if (typeof option === "string" || typeof option === "number" || typeof option === "boolean") {
+      const title = String(option).trim();
+      return title ? { title } : null;
+   }
+   if (option && typeof option === "object") {
+      const record = option as Record<string, unknown>;
+      for (const key of OPTION_TITLE_KEYS) {
+         const value = record[key];
+         if (typeof value === "string" && value.trim()) {
+            const description =
+               typeof record.description === "string" && record.description.trim() ? record.description : undefined;
+            return description ? { title: value.trim(), description } : { title: value.trim() };
          }
-         return null;
-      })
-      .filter((option): option is QuestionOption => option !== null);
+      }
+   }
+   return null;
 }
 
 function formatOptionsForMessage(options: QuestionOption[]): string {
@@ -148,6 +160,24 @@ function normalizeOptionalComment(text: string | null | undefined): string | und
    return trimmed ? trimmed : undefined;
 }
 
+function parseBooleanPreference(value: string | undefined): boolean | undefined {
+   if (value === undefined) return undefined;
+   switch (value.trim().toLowerCase()) {
+      case "1":
+      case "true":
+      case "yes":
+      case "on":
+         return true;
+      case "0":
+      case "false":
+      case "no":
+      case "off":
+         return false;
+      default:
+         return undefined;
+   }
+}
+
 function createFreeformResponse(text: string | null | undefined): AskResponse | null {
    const trimmed = text?.trim();
    return trimmed ? { kind: "freeform", text: trimmed } : null;
@@ -339,6 +369,7 @@ function resolveShortcut(
 type AskMode = "select" | "freeform" | "comment";
 
 const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
+const ASK_OVERLAY_MIN_RENDER_LINES = 8;
 const ASK_OVERLAY_WIDTH = "92%";
 const ASK_OVERLAY_MIN_WIDTH = 40;
 const SINGLE_SELECT_SPLIT_PANE_MIN_WIDTH = 84;
@@ -354,6 +385,20 @@ const DEFAULT_COMMENT_TOGGLE_KEY = "ctrl+g";
 // searchable single-select because they don't collide with fuzzy-search input.
 const VIM_SELECT_UP_KEY = Key.ctrl("k");
 const VIM_SELECT_DOWN_KEY = Key.ctrl("j");
+const PROMPT_SCROLL_PAGE_UP_KEY = Key.pageUp;
+const PROMPT_SCROLL_PAGE_DOWN_KEY = Key.pageDown;
+const PROMPT_SCROLL_HOME_KEY = Key.home;
+const PROMPT_SCROLL_END_KEY = Key.end;
+const PROMPT_SCROLL_HALF_PAGE_UP_KEY = Key.ctrl("u");
+const PROMPT_SCROLL_HALF_PAGE_DOWN_KEY = Key.ctrl("d");
+
+function getOverlayMaxRenderLinesForRows(rows: number): number {
+   const normalizedRows = Number.isFinite(rows) ? Math.max(1, Math.floor(rows)) : 24;
+   const availableRows = Math.max(1, normalizedRows - 2);
+   const ratioRows = Math.max(1, Math.floor(normalizedRows * ASK_OVERLAY_MAX_HEIGHT_RATIO));
+   const minimumRows = Math.min(ASK_OVERLAY_MIN_RENDER_LINES, availableRows);
+   return Math.min(availableRows, Math.max(minimumRows, ratioRows));
+}
 
 function matchesSelectUp(data: string, keybindings: KeybindingsManager): boolean {
    return (
@@ -374,7 +419,7 @@ function matchesSelectDown(data: string, keybindings: KeybindingsManager): boole
 function buildCustomUIOptions(
    displayMode: AskDisplayMode,
    onHandle?: (handle: OverlayHandle) => void,
-) {
+): { overlay?: boolean; overlayOptions?: OverlayOptions; onHandle?: (handle: OverlayHandle) => void } | undefined {
    switch (displayMode) {
       case "inline":
          return undefined;
@@ -998,6 +1043,9 @@ class AskComponent extends Container {
    private pendingSelections: string[] = [];
    private freeformDraft = "";
    private commentDraft = "";
+   private promptScrollOffset = 0;
+   private promptMaxScrollOffset = 0;
+   private promptViewportRows = 0;
 
    // Static layout components
    private titleText: Text;
@@ -1107,43 +1155,290 @@ class AskComponent extends Container {
    override render(width: number): string[] {
       const innerWidth = Math.max(1, width - BOX_BORDER_OVERHEAD);
 
+      if (this.displayMode === "overlay") {
+         return this.renderOverlayLayout(width, innerWidth);
+      }
+
       if (this.mode === "select" && !this.allowMultiple) {
-         const overlayMaxHeight = Math.max(12, Math.floor(this.tui.terminal.rows * ASK_OVERLAY_MAX_HEIGHT_RATIO));
-         const staticLines = this.countStaticLines(innerWidth);
-         const availableOptionRows = Math.max(4, overlayMaxHeight - staticLines);
-         this.ensureSingleSelectList().setMaxVisibleRows(availableOptionRows);
+         this.ensureSingleSelectList().setMaxVisibleRows(12);
       }
 
-      // Render children at the inner width (excluding side border characters)
-      const rawLines = super.render(innerWidth);
+      return this.frameRawLines(super.render(innerWidth), width, innerWidth);
+   }
 
-      // First and last lines are the top/bottom box borders — pass through at full width.
-      // All inner lines get wrapped with side borders.
-      const borderColor = (s: string) => this.theme.fg("accent", s);
-      const titleColor = (s: string) => this.theme.fg("dim", this.theme.bold(s));
-      return rawLines.map((line, index) => {
-         if (index === 0 || index === rawLines.length - 1) {
-            // Box top/bottom borders already rendered at innerWidth — re-render at full width
-            if (index === 0) return new BoxBorderTop(borderColor, "ask_user", titleColor).render(width)[0];
-            return new BoxBorderBottom(borderColor, `v${ASK_USER_VERSION}`, (s: string) => this.theme.fg("dim", s)).render(width)[0];
+   private getOverlayMaxRenderLines(): number {
+      const rows = Number.isFinite(this.tui.terminal.rows) ? Math.floor(this.tui.terminal.rows) : 24;
+      return getOverlayMaxRenderLinesForRows(rows);
+   }
+
+   private renderOverlayLayout(width: number, innerWidth: number): string[] {
+      const maxLines = this.getOverlayMaxRenderLines();
+      if (maxLines <= 1) return [this.renderTopBorder(width)];
+      if (maxLines === 2) return [this.renderTopBorder(width), this.renderBottomBorder(width)];
+
+      const bodyCapacity = Math.max(0, maxLines - 2);
+      const promptLines = this.buildPromptLines(innerWidth);
+      const helpFullLines = this.helpText.render(innerWidth);
+      const helpBudget = this.getOverlayHelpBudget(bodyCapacity, helpFullLines.length);
+      const contentRows = Math.max(0, bodyCapacity - helpBudget);
+
+      let promptBudget = 0;
+      let modeBudget = 0;
+      let separatorRows = 0;
+
+      if (this.mode === "select") {
+         separatorRows = contentRows >= 4 ? 1 : 0;
+         const promptAndModeRows = Math.max(0, contentRows - separatorRows);
+         promptBudget = promptAndModeRows;
+
+         if (promptAndModeRows > 0) {
+            const promptMinRows = promptLines.length > 0 ? 1 : 0;
+            const maximumModeRows = Math.max(0, promptAndModeRows - promptMinRows);
+            const modeMinRows = Math.min(this.getMinimumModeRows(), maximumModeRows);
+            modeBudget = Math.min(this.getPreferredModeRows(), maximumModeRows);
+            modeBudget = Math.max(modeMinRows, modeBudget);
+            promptBudget = promptAndModeRows - modeBudget;
+
+            const usefulPromptRows = Math.min(
+               promptLines.length,
+               promptAndModeRows >= modeMinRows + 2 ? 2 : promptMinRows,
+            );
+            if (promptBudget < usefulPromptRows && modeBudget > modeMinRows) {
+               const shiftedRows = Math.min(usefulPromptRows - promptBudget, modeBudget - modeMinRows);
+               modeBudget -= shiftedRows;
+               promptBudget += shiftedRows;
+            }
          }
-         const padded = truncateToWidth(line, innerWidth, "", true);
-         return `${borderColor(BOX_BORDER_LEFT)}${padded}${borderColor(BOX_BORDER_RIGHT)}`;
-      });
+      } else {
+         modeBudget = Math.min(this.getPreferredModeRows(), contentRows);
+         modeBudget = Math.max(Math.min(this.getMinimumModeRows(), contentRows), modeBudget);
+         promptBudget = Math.max(0, contentRows - modeBudget);
+         if (promptBudget > 0 && modeBudget > 0) {
+            separatorRows = 1;
+            promptBudget = Math.max(0, promptBudget - separatorRows);
+         }
+      }
+
+      const modeLines = this.renderModeLines(innerWidth, modeBudget);
+      if (modeLines.length < modeBudget) {
+         promptBudget += modeBudget - modeLines.length;
+      }
+
+      const promptPaneLines = this.renderPromptPane(promptLines, promptBudget, innerWidth);
+      const helpLines = this.limitLines(helpFullLines, helpBudget, innerWidth, false);
+      const bodyLines = [
+         ...promptPaneLines,
+         ...(separatorRows > 0 && promptPaneLines.length > 0 && modeLines.length > 0 ? [""] : []),
+         ...modeLines,
+         ...helpLines,
+      ];
+
+      return this.frameBodyLines(bodyLines.slice(0, bodyCapacity), width, innerWidth);
+   }
+
+   private buildPromptLines(width: number): string[] {
+      return [
+         ...this.titleText.render(width),
+         ...this.questionText.render(width),
+         ...(this.contextComponent ? ["", ...this.contextComponent.render(width)] : []),
+      ];
+   }
+
+   private getOverlayHelpBudget(bodyCapacity: number, renderedHelpRows: number): number {
+      if (renderedHelpRows <= 0 || bodyCapacity <= 0) return 0;
+      if (bodyCapacity >= 12) return Math.min(2, renderedHelpRows);
+      return 1;
+   }
+
+   private getMinimumModeRows(): number {
+      if (this.mode === "freeform") return 5;
+      if (this.mode === "comment") return 6;
+      return this.allowMultiple ? 3 : 4;
+   }
+
+   private getPreferredModeRows(): number {
+      if (this.mode === "freeform") return 10;
+      if (this.mode === "comment") return 11;
+      return 8;
+   }
+
+   private renderModeLines(width: number, budget: number): string[] {
+      const safeBudget = Math.max(0, Math.floor(budget));
+      if (safeBudget <= 0) return [];
+
+      if (this.mode === "select") {
+         if (!this.allowMultiple) {
+            this.ensureSingleSelectList().setMaxVisibleRows(Math.max(1, safeBudget));
+         }
+         return this.limitLines(this.modeContainer.render(width), safeBudget, width, true);
+      }
+
+      return this.renderEditorModeLines(width, safeBudget);
    }
 
-   private countWrappedLines(text: string, width: number): number {
-      return Math.max(1, wrapTextWithAnsi(text, Math.max(10, width - 2)).length);
+   private renderEditorModeLines(width: number, budget: number): string[] {
+      const headerLines = this.buildEditorModeHeaderLines(width);
+      const minimumEditorRows = Math.min(3, budget);
+      const headerBudget = Math.max(0, budget - minimumEditorRows);
+      const visibleHeaderLines = this.limitLines(headerLines, headerBudget, width, true);
+      const editorBudget = Math.max(0, budget - visibleHeaderLines.length);
+
+      return [
+         ...visibleHeaderLines,
+         ...this.limitEditorLines(this.ensureEditor().render(width), editorBudget, width),
+      ];
    }
 
-   private countStaticLines(width: number): number {
-      const titleLines = 1;
-      const questionLines = this.countWrappedLines(this.question, width);
-      const contextLines = this.context ? 1 + this.countWrappedLines(this.context, width) : 0;
-      const helpLines = 1;
-      const borderLines = 2;
-      const spacerLines = this.context ? 6 : 5;
-      return borderLines + spacerLines + titleLines + questionLines + contextLines + helpLines;
+   private buildEditorModeHeaderLines(width: number): string[] {
+      if (this.mode === "comment") {
+         const selectedLabel = this.pendingSelections.length === 1 ? "Selected option:" : "Selected options:";
+         return [
+            ...new Text(this.theme.fg("accent", this.theme.bold(selectedLabel)), 1, 0).render(width),
+            ...new Text(this.theme.fg("text", this.pendingSelections.join(", ")), 1, 0).render(width),
+            "",
+         ];
+      }
+
+      return [
+         ...new Text(this.theme.fg("accent", this.theme.bold("Custom response")), 1, 0).render(width),
+         "",
+      ];
+   }
+
+   private limitEditorLines(lines: string[], budget: number, width: number): string[] {
+      const safeBudget = Math.max(0, Math.floor(budget));
+      if (safeBudget <= 0) return [];
+      if (lines.length <= safeBudget) {
+         return lines.map((line) => truncateToWidth(line, width, "", true));
+      }
+      if (safeBudget === 1) return [this.theme.fg("dim", "…")];
+
+      const topBorder = truncateToWidth(lines[0] ?? "", width, "", true);
+      const bottomBorder = truncateToWidth(lines[lines.length - 1] ?? "", width, "", true);
+      if (safeBudget === 2) return [topBorder, bottomBorder];
+
+      const contentLines = lines.slice(1, -1);
+      const contentBudget = safeBudget - 2;
+      // Locate the cursor row: prefer the zero-width CURSOR_MARKER the editor
+      // emits while focused (the same mechanism pi-tui core uses for hardware
+      // cursor placement), falling back to the inverse-video fake cursor.
+      const cursorLineIndex = contentLines.findIndex(
+         (line) => line.includes(CURSOR_MARKER) || line.includes("\x1b[7m"),
+      );
+      const maxStart = Math.max(0, contentLines.length - contentBudget);
+      const start = cursorLineIndex >= 0
+         ? Math.max(0, Math.min(cursorLineIndex - contentBudget + 1, maxStart))
+         : maxStart;
+      const visibleContentLines = contentLines.slice(start, start + contentBudget);
+      const markedContentLines = this.applyPromptOverflowMarkers(
+         visibleContentLines,
+         width,
+         start > 0,
+         start + contentBudget < contentLines.length,
+      );
+
+      return [topBorder, ...markedContentLines, bottomBorder];
+   }
+
+   private renderPromptPane(promptLines: string[], budget: number, width: number): string[] {
+      const viewportRows = Math.max(0, Math.floor(budget));
+      this.promptViewportRows = viewportRows;
+
+      if (viewportRows <= 0 || promptLines.length === 0) {
+         this.promptMaxScrollOffset = 0;
+         this.promptScrollOffset = 0;
+         return [];
+      }
+
+      this.promptMaxScrollOffset = Math.max(0, promptLines.length - viewportRows);
+      this.promptScrollOffset = Math.max(0, Math.min(this.promptScrollOffset, this.promptMaxScrollOffset));
+
+      const visibleLines = promptLines.slice(this.promptScrollOffset, this.promptScrollOffset + viewportRows);
+      const hasHiddenAbove = this.promptScrollOffset > 0;
+      const hasHiddenBelow = this.promptScrollOffset + viewportRows < promptLines.length;
+      return this.applyPromptOverflowMarkers(visibleLines, width, hasHiddenAbove, hasHiddenBelow);
+   }
+
+   private applyPromptOverflowMarkers(
+      lines: string[],
+      width: number,
+      hasHiddenAbove: boolean,
+      hasHiddenBelow: boolean,
+   ): string[] {
+      if (lines.length === 0) return lines;
+
+      const marked = [...lines];
+      if (hasHiddenAbove && hasHiddenBelow && marked.length === 1) {
+         marked[0] = this.addPromptOverflowMarker(marked[0] ?? "", "↕", width);
+         return marked;
+      }
+
+      if (hasHiddenAbove) {
+         marked[0] = this.addPromptOverflowMarker(marked[0] ?? "", "↑", width);
+      }
+      if (hasHiddenBelow) {
+         const lastIndex = marked.length - 1;
+         marked[lastIndex] = this.addPromptOverflowMarker(marked[lastIndex] ?? "", "↓", width);
+      }
+      return marked;
+   }
+
+   private addPromptOverflowMarker(line: string, marker: string, width: number): string {
+      return truncateToWidth(`${this.theme.fg("dim", marker)} ${line}`, width, "", true);
+   }
+
+   private limitLines(lines: string[], budget: number, width: number, showOverflowMarker: boolean): string[] {
+      const safeBudget = Math.max(0, Math.floor(budget));
+      if (safeBudget <= 0) return [];
+      if (lines.length <= safeBudget) {
+         return lines.map((line) => truncateToWidth(line, width, "", true));
+      }
+      if (!showOverflowMarker) {
+         return lines.slice(0, safeBudget).map((line) => truncateToWidth(line, width, "", true));
+      }
+      if (safeBudget === 1) return [this.theme.fg("dim", "…")];
+      return [
+         ...lines.slice(0, safeBudget - 1).map((line) => truncateToWidth(line, width, "", true)),
+         this.theme.fg("dim", "…"),
+      ];
+   }
+
+   private renderTopBorder(width: number): string {
+      return new BoxBorderTop(
+         (s: string) => this.theme.fg("accent", s),
+         "ask_user",
+         (s: string) => this.theme.fg("dim", this.theme.bold(s)),
+      ).render(width)[0] ?? "";
+   }
+
+   private renderBottomBorder(width: number): string {
+      return new BoxBorderBottom(
+         (s: string) => this.theme.fg("accent", s),
+         `v${ASK_USER_VERSION}`,
+         (s: string) => this.theme.fg("dim", s),
+      ).render(width)[0] ?? "";
+   }
+
+   private frameBodyLines(bodyLines: string[], width: number, innerWidth: number): string[] {
+      const borderColor = (s: string) => this.theme.fg("accent", s);
+      return [
+         this.renderTopBorder(width),
+         ...bodyLines.map((line) => {
+            const padded = truncateToWidth(line, innerWidth, "", true);
+            return `${borderColor(BOX_BORDER_LEFT)}${padded}${borderColor(BOX_BORDER_RIGHT)}`;
+         }),
+         this.renderBottomBorder(width),
+      ];
+   }
+
+   private frameRawLines(rawLines: string[], width: number, innerWidth: number): string[] {
+      const borderColor = (s: string) => this.theme.fg("accent", s);
+      return rawLines.map((line, index) => {
+         if (index === 0) return this.renderTopBorder(width);
+         if (index === rawLines.length - 1) return this.renderBottomBorder(width);
+         const padded = truncateToWidth(line, innerWidth, "", true);
+         return `${borderColor(BOX_BORDER_LEFT)}${padded}${borderColor(BOX_BORDER_RIGHT)}`;
+      });
    }
 
    private updateStaticText(): void {
@@ -1169,6 +1464,9 @@ class AskComponent extends Container {
       const overlayHint = this.displayMode === "overlay" && !this.shortcuts.overlayToggle.disabled
          ? literalHint(theme, this.shortcuts.overlayToggle.spec, "hide")
          : null;
+      const promptScrollHint = this.displayMode === "overlay"
+         ? literalHint(theme, "PgUp/PgDn", "prompt")
+         : null;
       const commentHint = this.allowComment && !this.shortcuts.commentToggle.disabled
          ? literalHint(theme, this.shortcuts.commentToggle.spec, "toggle context")
          : null;
@@ -1194,6 +1492,7 @@ class AskComponent extends Container {
             literalHint(theme, "↑↓", "navigate"),
             literalHint(theme, "space", "toggle"),
             commentHint,
+            promptScrollHint,
             overlayHint,
             keybindingHint(theme, this.keybindings, "tui.select.confirm", "submit"),
             keybindingHint(theme, this.keybindings, "tui.select.cancel", "cancel"),
@@ -1207,9 +1506,10 @@ class AskComponent extends Container {
             .filter((key) => key !== "escape" && key !== "esc");
          const hints = [
             literalHint(theme, "type", "filter"),
+            commentHint,
+            promptScrollHint,
             keybindingHint(theme, this.keybindings, "tui.editor.deleteCharBackward", "erase"),
             literalHint(theme, "↑↓", "navigate"),
-            commentHint,
             overlayHint,
             keybindingHint(theme, this.keybindings, "tui.select.confirm", "select"),
             literalHint(theme, "esc", "clear/cancel"),
@@ -1380,7 +1680,53 @@ class AskComponent extends Container {
       this.tui.requestRender();
    }
 
+   private setPromptScrollOffset(nextOffset: number): boolean {
+      if (this.displayMode !== "overlay" || this.promptMaxScrollOffset <= 0) return false;
+      const clamped = Math.max(0, Math.min(Math.floor(nextOffset), this.promptMaxScrollOffset));
+      const changed = clamped !== this.promptScrollOffset;
+      this.promptScrollOffset = clamped;
+      return changed;
+   }
+
+   private handlePromptScrollInput(data: string): boolean {
+      if (this.displayMode !== "overlay" || this.promptMaxScrollOffset <= 0) return false;
+      // Prompt scrolling is select-mode only: in freeform/comment modes the
+      // editor owns PageUp/PageDown (tui.editor.pageUp/pageDown) for paging
+      // through long input, so intercepting them here would steal editor keys.
+      if (this.mode !== "select") return false;
+
+      const pageRows = Math.max(1, this.promptViewportRows - 1);
+      const halfPageRows = Math.max(1, Math.floor(this.promptViewportRows / 2));
+      let handled = false;
+
+      if (matchesKey(data, PROMPT_SCROLL_PAGE_UP_KEY)) {
+         handled = true;
+         this.setPromptScrollOffset(this.promptScrollOffset - pageRows);
+      } else if (matchesKey(data, PROMPT_SCROLL_PAGE_DOWN_KEY)) {
+         handled = true;
+         this.setPromptScrollOffset(this.promptScrollOffset + pageRows);
+      } else if (matchesKey(data, PROMPT_SCROLL_HOME_KEY)) {
+         handled = true;
+         this.setPromptScrollOffset(0);
+      } else if (matchesKey(data, PROMPT_SCROLL_END_KEY)) {
+         handled = true;
+         this.setPromptScrollOffset(this.promptMaxScrollOffset);
+      } else if (matchesKey(data, PROMPT_SCROLL_HALF_PAGE_UP_KEY)) {
+         handled = true;
+         this.setPromptScrollOffset(this.promptScrollOffset - halfPageRows);
+      } else if (matchesKey(data, PROMPT_SCROLL_HALF_PAGE_DOWN_KEY)) {
+         handled = true;
+         this.setPromptScrollOffset(this.promptScrollOffset + halfPageRows);
+      }
+
+      return handled;
+   }
+
    handleInput(data: string): void {
+      if (this.handlePromptScrollInput(data)) {
+         this.tui.requestRender();
+         return;
+      }
       if (this.mode === "freeform" || this.mode === "comment") {
          if (matchesKey(data, Key.escape)) {
             this.showSelectMode();
@@ -1500,15 +1846,17 @@ export default function(pi: ExtensionAPI) {
          ),
          options: Type.Optional(
             Type.Array(
-               Type.Union([
-                  Type.String({ description: "Short title for this option" }),
-                  Type.Object({
-                     title: Type.String({ description: "Short title for this option" }),
-                     description: Type.Optional(
-                        Type.String({ description: "Longer description explaining this option" }),
-                     ),
-                  }),
-               ]),
+               // Flat object shape: union item schemas get stripped or rejected
+               // by several providers/proxies (Google function calling,
+               // Codex-style backends, cmux), leaving the model to guess the shape
+               // and produce empty options. Plain strings are still accepted at
+               // runtime for older transcripts. See issue #22.
+               Type.Object({
+                  title: Type.String({ description: "Short title for this option" }),
+                  description: Type.Optional(
+                     Type.String({ description: "Longer description explaining this option" }),
+                  ),
+               }),
                { description: "List of options for the user to choose from" },
             ),
          ),
@@ -1519,7 +1867,7 @@ export default function(pi: ExtensionAPI) {
             Type.Boolean({ description: "Add a freeform text option. Default: true" }),
          ),
          allowComment: Type.Optional(
-            Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: false" }),
+            Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: PI_ASK_USER_ALLOW_COMMENT env var if set, otherwise false." }),
          ),
          displayMode: Type.Optional(
             StringEnum(["overlay", "inline"] as const, {
@@ -1557,16 +1905,19 @@ export default function(pi: ExtensionAPI) {
             options: rawOptions = [],
             allowMultiple = false,
             allowFreeform = true,
-            allowComment = false,
+            allowComment: requestedAllowComment,
             displayMode,
             overlayToggleKey,
             commentToggleKey,
             timeout,
          } = params as AskParams;
-         const envMode = process.env.PI_ASK_USER_DISPLAY_MODE;
+         const envMode = process.env.PI_ASK_USER_DISPLAY_MODE?.trim().toLowerCase();
          const envDisplayMode: AskDisplayMode | undefined =
             envMode === "overlay" || envMode === "inline" ? envMode : undefined;
          const effectiveDisplayMode: AskDisplayMode = displayMode ?? envDisplayMode ?? "overlay";
+         const allowComment = requestedAllowComment
+            ?? parseBooleanPreference(process.env.PI_ASK_USER_ALLOW_COMMENT)
+            ?? false;
          const shortcuts: ResolvedAskShortcuts = {
             overlayToggle: resolveShortcut(
                overlayToggleKey,
@@ -1579,9 +1930,25 @@ export default function(pi: ExtensionAPI) {
                DEFAULT_COMMENT_TOGGLE_KEY,
             ),
          };
-         const options = normalizeOptions(rawOptions);
+         const options = rawOptions.map(coerceOption).filter((option): option is QuestionOption => option !== null);
          const normalizedContext = context?.trim() || undefined;
 
+         if (rawOptions.length > 0 && options.length === 0) {
+            return {
+               content: [
+                  {
+                     type: "text",
+                     text:
+                        `All ${rawOptions.length} option(s) were malformed, so nothing could be shown to the user. `
+                        + `Each option must be a plain string or an object like { "title": "Short label", "description": "Optional detail" }. `
+                        + `Call ask_user again with corrected options.`,
+                  },
+               ],
+               isError: true,
+               details: { error: "Malformed options: no entry had a usable title" },
+            };
+         }
+
          if (!ctx.hasUI || !ctx.ui) {
             const optionText = options.length > 0 ? `\n\nOptions:\n${formatOptionsForMessage(options)}` : "";
             const freeformHint = allowFreeform ? "\n\nYou can also answer freely." : "";
@@ -1732,9 +2099,7 @@ export default function(pi: ExtensionAPI) {
          let text = theme.fg("toolTitle", theme.bold("ask_user "));
          text += theme.fg("muted", question);
          if (rawOptions.length > 0) {
-            const labels = rawOptions.map((o: unknown) =>
-               typeof o === "string" ? o : (o as QuestionOption)?.title ?? "",
-            );
+            const labels = rawOptions.map((o: unknown) => coerceOption(o)?.title ?? "<invalid>");
             text += "\n" + theme.fg("dim", `  ${rawOptions.length} option(s): ${labels.join(", ")}`);
          }
          if (args.allowMultiple) {
@@ -1755,8 +2120,7 @@ export default function(pi: ExtensionAPI) {
 
          if (options.isPartial) {
             const waitingText = result.content
-               ?.filter((part: { type?: string; text?: string }) => part?.type === "text")
-               .map((part: { text?: string }) => part.text ?? "")
+               ?.map((part) => part.type === "text" ? part.text : "")
                .join("\n")
                .trim() || "Waiting for user input...";
             return new Text(theme.fg("muted", waitingText), 0, 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input",
   "type": "module",
   "keywords": [