pi-ask-user 0.6.1 → 0.8.0

package/README.md

@@ -16,7 +16,8 @@ High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
 - Optional freeform responses
 - User-toggleable extra context on structured selections
 - Context display support
-- Overlay mode — dialog floats over conversation, preserving context
+- Configurable display mode: `overlay` (modal, default) or `inline` (rendered directly in the flow)
+- Runtime overlay toggle: press `alt+o` while the prompt is open to temporarily hide/show the popup so you can read prior agent output, then press `alt+o` again to bring it back
 - Pi-TUI-aligned keybinding and editor behavior
 - Custom TUI rendering for tool calls and results
 - System prompt integration via `promptSnippet` and `promptGuidelines`
@@ -63,7 +64,8 @@ The registered tool name is:
 | `options` | `(string \| {title, description?})[]?` | `[]` | Multiple-choice options |
 | `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 overlay (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
+| `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 |
+| `displayMode` | `"overlay" \| "inline"?` | env var or `"overlay"` | Controls custom UI rendering: `overlay` shows the centered modal (current behavior), `inline` renders without overlay framing |
 | `timeout` | `number?` | — | Auto-dismiss after N ms and return `null` if the prompt times out |
 
 ## Example usage shape
@@ -78,10 +80,43 @@ The registered tool name is:
   ],
   "allowMultiple": false,
   "allowFreeform": true,
-  "allowComment": true
+  "allowComment": true,
+  "displayMode": "inline"
 }
 ```
 
+`displayMode: "inline"` uses the same interaction logic but skips overlay mode when calling `ctx.ui.custom(...)`. RPC/headless fallback behavior is unchanged.
+
+## Personal display mode preference
+
+Set the `PI_ASK_USER_DISPLAY_MODE` environment variable to configure your preferred default globally. Add it to your shell profile (`~/.zshrc`, `~/.bash_profile`, etc.):
+
+```bash
+export PI_ASK_USER_DISPLAY_MODE=inline
+```
+
+Effective behavior order:
+
+1. Per-call `displayMode` parameter (if provided)
+2. `PI_ASK_USER_DISPLAY_MODE` environment variable (if set to `"overlay"` or `"inline"`)
+3. Fallback default: `"overlay"`
+
+Unrecognised values are silently ignored and fall back to `"overlay"`.
+
+## Controls
+
+While an `ask_user` prompt is open:
+
+| Key | Action |
+|-----|--------|
+| `alt+o` | Hide/show the overlay popup so you can read the agent's prior output. Available in `overlay` mode only. The first time you hide it, a notification reminds you that `alt+o` brings it back. |
+| `ctrl+g` | Toggle the optional comment/extra-context row (when `allowComment: true`). |
+| `enter` | Confirm the focused option, submit a freeform response, or submit/skip an optional comment. |
+| `esc` | Clear the search filter, exit freeform/comment mode, or cancel the prompt. |
+| `↑` / `↓` | Navigate options. |
+
+If you prefer never to see the overlay, set `displayMode: "inline"` per call or `PI_ASK_USER_DISPLAY_MODE=inline` globally.
+
 ## Result details
 
 All tool results include a structured `details` object for rendering and session state reconstruction:

package/index.ts

@@ -7,7 +7,7 @@
 
 import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
 import { getMarkdownTheme } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { Type, type TUnsafe } from "@sinclair/typebox";
 import {
    Container,
    type Component,
@@ -21,6 +21,7 @@ import {
    Markdown,
    type MarkdownTheme,
    matchesKey,
+   type OverlayHandle,
    Spacer,
    Text,
    type TUI,
@@ -33,8 +34,28 @@ import { createRequire } from "node:module";
 const _require = createRequire(import.meta.url);
 const ASK_USER_VERSION: string = (_require("./package.json") as { version: string }).version;
 
+/**
+ * Emit a flat `{ type: "string", enum: [...] }` JSON Schema instead of the
+ * `anyOf`/`oneOf` shape that `Type.Union([Type.Literal()])` produces. Google's
+ * function-calling API rejects the union form. Local copy of pi-ai's StringEnum
+ * to avoid a peer dependency for one helper.
+ */
+function StringEnum<const T extends readonly string[]>(
+   values: T,
+   options?: { description?: string; default?: T[number] },
+): TUnsafe<T[number]> {
+   return Type.Unsafe<T[number]>({
+      type: "string",
+      enum: [...values],
+      ...(options?.description ? { description: options.description } : {}),
+      ...(options?.default !== undefined ? { default: options.default } : {}),
+   });
+}
+
 type AskOptionInput = QuestionOption | string;
 
+type AskDisplayMode = "overlay" | "inline";
+
 interface AskParams {
    question: string;
    context?: string;
@@ -42,6 +63,7 @@ interface AskParams {
    allowMultiple?: boolean;
    allowFreeform?: boolean;
    allowComment?: boolean;
+   displayMode?: AskDisplayMode;
    timeout?: number;
 }
 
@@ -227,6 +249,10 @@ function isCommentToggleKey(data: string): boolean {
    return matchesKey(data, Key.ctrl("g"));
 }
 
+function isOverlayHideToggleKey(data: string): boolean {
+   return matchesKey(data, Key.alt("o"));
+}
+
 type AskMode = "select" | "freeform" | "comment";
 
 const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
@@ -238,6 +264,44 @@ const SINGLE_SELECT_SPLIT_PANE_RIGHT_MIN_WIDTH = 28;
 const SINGLE_SELECT_SPLIT_PANE_SEPARATOR = " │ ";
 const FREEFORM_SENTINEL = "\u270f\ufe0f Type custom response...";
 const COMMENT_TOGGLE_LABEL = "Add extra context after selection";
+const OVERLAY_HIDE_TOGGLE_LABEL = "alt+o";
+
+function buildCustomUIOptions(
+   displayMode: AskDisplayMode,
+   onHandle?: (handle: OverlayHandle) => void,
+) {
+   switch (displayMode) {
+      case "inline":
+         return undefined;
+      case "overlay":
+         return {
+            overlay: true,
+            overlayOptions: {
+               anchor: "center" as const,
+               width: ASK_OVERLAY_WIDTH,
+               minWidth: ASK_OVERLAY_MIN_WIDTH,
+               maxHeight: "85%",
+               margin: 1,
+            },
+            ...(onHandle ? { onHandle } : {}),
+         };
+      default: {
+         const _exhaustive: never = displayMode;
+         void _exhaustive;
+         return {
+            overlay: true,
+            overlayOptions: {
+               anchor: "center" as const,
+               width: ASK_OVERLAY_WIDTH,
+               minWidth: ASK_OVERLAY_MIN_WIDTH,
+               maxHeight: "85%",
+               margin: 1,
+            },
+            ...(onHandle ? { onHandle } : {}),
+         };
+      }
+   }
+}
 
 class MultiSelectList implements Component {
    private options: QuestionOption[];
@@ -815,6 +879,7 @@ class AskComponent extends Container {
    private allowMultiple: boolean;
    private allowFreeform: boolean;
    private allowComment: boolean;
+   private displayMode: AskDisplayMode;
    private tui: TUI;
    private theme: Theme;
    private keybindings: KeybindingsManager;
@@ -856,6 +921,7 @@ class AskComponent extends Container {
       allowMultiple: boolean,
       allowFreeform: boolean,
       allowComment: boolean,
+      displayMode: AskDisplayMode,
       tui: TUI,
       theme: Theme,
       keybindings: KeybindingsManager,
@@ -869,6 +935,7 @@ class AskComponent extends Container {
       this.allowMultiple = allowMultiple;
       this.allowFreeform = allowFreeform;
       this.allowComment = allowComment;
+      this.displayMode = displayMode;
       this.tui = tui;
       this.theme = theme;
       this.keybindings = keybindings;
@@ -991,6 +1058,9 @@ class AskComponent extends Container {
 
    private updateHelpText(): void {
       const theme = this.theme;
+      const overlayHint = this.displayMode === "overlay"
+         ? literalHint(theme, OVERLAY_HIDE_TOGGLE_LABEL, "hide")
+         : null;
       if (this.mode === "freeform" || this.mode === "comment") {
          const alternateCancelKeys = this.keybindings
             .getKeys("tui.select.cancel")
@@ -999,6 +1069,7 @@ class AskComponent extends Container {
             keybindingHint(theme, this.keybindings, "tui.input.submit", this.mode === "comment" ? "submit/skip" : "submit"),
             keybindingHint(theme, this.keybindings, "tui.input.newLine", "newline"),
             literalHint(theme, "esc", "back"),
+            overlayHint,
             alternateCancelKeys.length > 0 ? literalHint(theme, formatKeyList(alternateCancelKeys), "cancel") : null,
          ]
             .filter((hint): hint is string => !!hint)
@@ -1012,6 +1083,7 @@ class AskComponent extends Container {
             literalHint(theme, "↑↓", "navigate"),
             literalHint(theme, "space", "toggle"),
             this.allowComment ? literalHint(theme, "ctrl+g", "toggle context") : null,
+            overlayHint,
             keybindingHint(theme, this.keybindings, "tui.select.confirm", "submit"),
             keybindingHint(theme, this.keybindings, "tui.select.cancel", "cancel"),
          ]
@@ -1027,6 +1099,7 @@ class AskComponent extends Container {
             keybindingHint(theme, this.keybindings, "tui.editor.deleteCharBackward", "erase"),
             literalHint(theme, "↑↓", "navigate"),
             this.allowComment ? literalHint(theme, "ctrl+g", "toggle context") : null,
+            overlayHint,
             keybindingHint(theme, this.keybindings, "tui.select.confirm", "select"),
             literalHint(theme, "esc", "clear/cancel"),
             alternateCancelKeys.length > 0
@@ -1331,6 +1404,11 @@ export default function(pi: ExtensionAPI) {
          allowComment: Type.Optional(
             Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: false" }),
          ),
+         displayMode: Type.Optional(
+            StringEnum(["overlay", "inline"] as const, {
+               description: "UI rendering mode. 'overlay' shows a centered modal, 'inline' renders in-place. Default: PI_ASK_USER_DISPLAY_MODE env var if set, otherwise 'overlay'. Omit to respect the user's configured preference.",
+            }),
+         ),
          timeout: Type.Optional(
             Type.Number({ description: "Auto-dismiss after N milliseconds. Returns null (cancelled) when expired." }),
          ),
@@ -1351,8 +1429,13 @@ export default function(pi: ExtensionAPI) {
             allowMultiple = false,
             allowFreeform = true,
             allowComment = false,
+            displayMode,
             timeout,
          } = params as AskParams;
+         const envMode = process.env.PI_ASK_USER_DISPLAY_MODE;
+         const envDisplayMode: AskDisplayMode | undefined =
+            envMode === "overlay" || envMode === "inline" ? envMode : undefined;
+         const effectiveDisplayMode: AskDisplayMode = displayMode ?? envDisplayMode ?? "overlay";
          const options = normalizeOptions(rawOptions);
          const normalizedContext = context?.trim() || undefined;
 
@@ -1398,41 +1481,56 @@ export default function(pi: ExtensionAPI) {
          });
 
          let result: AskUIResult | null;
+         let overlayHandle: OverlayHandle | undefined;
+         let removeOverlayInputListener: (() => void) | undefined;
+         let hasAnnouncedHide = false;
          try {
-            const customResult = await ctx.ui.custom<AskUIResult | null>(
-               (tui, theme, keybindings, done) => {
-                  if (signal) {
-                     const onAbort = () => done(null);
-                     signal.addEventListener("abort", onAbort, { once: true });
-                  }
+            const customFactory = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: AskUIResult | null) => void) => {
+               if (signal) {
+                  const onAbort = () => done(null);
+                  signal.addEventListener("abort", onAbort, { once: true });
+               }
 
-                  if (timeout && timeout > 0) {
-                     setTimeout(() => done(null), timeout);
+               if (timeout && timeout > 0) {
+                  setTimeout(() => done(null), timeout);
+               }
+
+               return new AskComponent(
+                  question,
+                  normalizedContext,
+                  options,
+                  allowMultiple,
+                  allowFreeform,
+                  allowComment,
+                  effectiveDisplayMode,
+                  tui,
+                  theme,
+                  keybindings,
+                  done,
+               );
+            };
+
+            // Register a raw terminal input listener for alt+o so the overlay can be
+            // toggled even while it is hidden (hidden overlays do not receive input).
+            // Inline mode does not need this because the prompt is already non-modal.
+            if (effectiveDisplayMode === "overlay" && typeof ctx.ui.onTerminalInput === "function") {
+               removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
+                  if (!isOverlayHideToggleKey(data) || !overlayHandle) return undefined;
+                  const nextHidden = !overlayHandle.isHidden();
+                  overlayHandle.setHidden(nextHidden);
+                  if (nextHidden && !hasAnnouncedHide) {
+                     hasAnnouncedHide = true;
+                     ctx.ui.notify?.(`ask_user hidden — press ${OVERLAY_HIDE_TOGGLE_LABEL} to reopen`, "info");
                   }
+                  return { consume: true };
+               });
+            }
 
-                  return new AskComponent(
-                     question,
-                     normalizedContext,
-                     options,
-                     allowMultiple,
-                     allowFreeform,
-                     allowComment,
-                     tui,
-                     theme,
-                     keybindings,
-                     done,
-                  );
-               },
-               {
-                  overlay: true,
-                  overlayOptions: {
-                     anchor: "center",
-                     width: ASK_OVERLAY_WIDTH,
-                     minWidth: ASK_OVERLAY_MIN_WIDTH,
-                     maxHeight: "85%",
-                     margin: 1,
-                  },
-               },
+            const customResult = await ctx.ui.custom<AskUIResult | null>(
+               customFactory,
+               buildCustomUIOptions(effectiveDisplayMode, (handle) => {
+                  overlayHandle = handle;
+               }),
             );
 
             if (customResult !== undefined) {
@@ -1449,6 +1547,8 @@ export default function(pi: ExtensionAPI) {
                isError: true,
                details: { error: message },
             };
+         } finally {
+            removeOverlayInputListener?.();
          }
 
          if (result === null) {

package/package.json

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

package/skills/ask-user/SKILL.md

@@ -54,7 +54,7 @@ Call `ask_user` with one decision at a time:
 - `options`: 2-5 clear choices when possible
 - `allowMultiple`: `false` unless independent selections are genuinely needed
 - `allowFreeform`: usually `true`
-
+- `displayMode` *(optional)*: `"overlay"` (default) or `"inline"`. Use `"inline"` when preceding assistant context (summary, trade-offs, recommendation) is essential to the decision and should remain visible — overlays cover the conversation underneath. The user may set a personal default via the `PI_ASK_USER_DISPLAY_MODE` environment variable; only pass this when you intentionally want to override it for one call.
 ### 5) Commit the decision
 After response:
 - restate the decision in plain language

package/skills/ask-user/references/ask-user-skill-extension-spec.md

@@ -66,6 +66,19 @@ Use this protocol whenever the trigger matrix says to ask.
 }
 ```
 
+### Display mode (optional)
+
+The `ask_user` tool accepts an optional `displayMode` parameter:
+
+- `"overlay"` *(default)*: centered modal; covers the conversation underneath.
+- `"inline"`: rendered in the conversation flow; preceding messages stay visible.
+
+Guidance:
+
+- Omit `displayMode` to respect the user's configured preference (`PI_ASK_USER_DISPLAY_MODE` environment variable).
+- Pass `"inline"` only when the immediately preceding assistant message (summary, trade-offs, recommendation) is the primary context for the decision and must remain visible.
+- Pass `"overlay"` only to explicitly force the modal style (rare).
+
 ### Requirement-priority decision
 
 ```json