pi-ask-user 0.7.0 → 0.9.0

package/README.md

@@ -17,6 +17,7 @@ High-quality video: [ask-user-demo.mp4](./media/ask-user-demo.mp4)
 - User-toggleable extra context on structured selections
 - Context display support
 - Configurable display mode: `overlay` (modal, default) or `inline` (rendered directly in the flow)
+- Runtime overlay toggle: press the configured overlay-toggle key (`alt+o` by default, configurable per call or via env var) while the prompt is open to temporarily hide/show the popup so you can read prior agent output, then press it 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`
@@ -65,6 +66,8 @@ The registered tool name is:
 | `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 |
 | `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. |
 | `timeout` | `number?` | — | Auto-dismiss after N ms and return `null` if the prompt times out |
 
 ## Example usage shape
@@ -86,22 +89,50 @@ The registered tool name is:
 
 `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
+## Personal preferences via environment variables
 
-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.):
+Configure your defaults globally by setting these in your shell profile (`~/.zshrc`, `~/.bash_profile`, etc.):
 
 ```bash
 export PI_ASK_USER_DISPLAY_MODE=inline
+export PI_ASK_USER_OVERLAY_TOGGLE_KEY=alt+h
+export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 ```
 
-Effective behavior order:
+### Display mode
+
+Effective order:
 
 1. Per-call `displayMode` parameter (if provided)
-2. `PI_ASK_USER_DISPLAY_MODE` environment variable (if set to `"overlay"` or `"inline"`)
+2. `PI_ASK_USER_DISPLAY_MODE` (if set to `"overlay"` or `"inline"`)
 3. Fallback default: `"overlay"`
 
 Unrecognised values are silently ignored and fall back to `"overlay"`.
 
+### Shortcuts
+
+Effective order for both `overlayToggleKey` and `commentToggleKey`:
+
+1. Per-call parameter (if provided)
+2. Matching env var (`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`)
+3. Built-in defaults: `alt+o` and `ctrl+g`
+
+Pass `"off"`, `"none"`, or `"disabled"` (at any level) to disable the shortcut entirely. Invalid specs are silently dropped and the next source is used. Specs follow the Pi-TUI [`KeyId`](https://github.com/badlogic/pi-mono/blob/main/packages/tui/src/keys.ts) format: `[mod+]...key` where modifiers are `ctrl`, `shift`, `alt`, `super`, in any order, joined by `+` (e.g. `ctrl+g`, `alt+shift+x`, `escape`, `tab`).
+
+## Controls
+
+While an `ask_user` prompt is open:
+
+| Key | Action |
+|-----|--------|
+| `alt+o` (configurable via `overlayToggleKey`) | 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 which key brings it back. |
+| `ctrl+g` (configurable via `commentToggleKey`) | 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

@@ -21,6 +21,7 @@ import {
    Markdown,
    type MarkdownTheme,
    matchesKey,
+   type OverlayHandle,
    Spacer,
    Text,
    type TUI,
@@ -63,6 +64,8 @@ interface AskParams {
    allowFreeform?: boolean;
    allowComment?: boolean;
    displayMode?: AskDisplayMode;
+   overlayToggleKey?: string | null;
+   commentToggleKey?: string | null;
    timeout?: number;
 }
 
@@ -244,8 +247,63 @@ function literalHint(theme: Theme, key: string, description: string): string {
    return `${theme.fg("dim", key)}${theme.fg("muted", ` ${description}`)}`;
 }
 
-function isCommentToggleKey(data: string): boolean {
-   return matchesKey(data, Key.ctrl("g"));
+type ResolvedShortcut =
+   | { disabled: false; spec: string; matches: (data: string) => boolean }
+   | { disabled: true; spec: null; matches: (data: string) => false };
+
+interface ResolvedAskShortcuts {
+   overlayToggle: ResolvedShortcut;
+   commentToggle: ResolvedShortcut;
+}
+
+const DISABLED_SHORTCUT: ResolvedShortcut = {
+   disabled: true,
+   spec: null,
+   matches: ((_data: string) => false) as (data: string) => false,
+};
+
+const SHORTCUT_DISABLE_VALUES = new Set(["off", "none", "disabled", ""]);
+
+function normalizeShortcutSpec(value: string | null | undefined): string | null | undefined {
+   if (value === undefined) return undefined;
+   if (value === null) return null;
+   const trimmed = value.trim().toLowerCase();
+   if (SHORTCUT_DISABLE_VALUES.has(trimmed)) return null;
+   return trimmed;
+}
+
+function isValidShortcutSpec(spec: string): boolean {
+   // KeyId is canonical lowercase: modifiers (`ctrl|shift|alt|super`) joined by `+`,
+   // plus a base key. We do a light syntactic sanity check; matchesKey() does the rest.
+   if (!spec) return false;
+   if (!/^[a-z0-9+_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]+$/i.test(spec)) return false;
+   if (spec.startsWith("+") || spec.endsWith("+")) return false;
+   if (spec.includes("++")) return false;
+   return true;
+}
+
+function buildShortcut(spec: string): ResolvedShortcut {
+   return {
+      disabled: false,
+      spec,
+      matches: (data: string) => matchesKey(data, spec as any),
+   };
+}
+
+function resolveShortcut(
+   paramValue: string | null | undefined,
+   envValue: string | undefined,
+   defaultSpec: string,
+): ResolvedShortcut {
+   const candidates: Array<string | null | undefined> = [paramValue, envValue, defaultSpec];
+   for (const raw of candidates) {
+      const normalized = normalizeShortcutSpec(raw);
+      if (normalized === undefined) continue; // not provided, fall through
+      if (normalized === null) return DISABLED_SHORTCUT; // explicit disable
+      if (isValidShortcutSpec(normalized)) return buildShortcut(normalized);
+      // Invalid spec: silently fall through to next candidate.
+   }
+   return DISABLED_SHORTCUT;
 }
 
 type AskMode = "select" | "freeform" | "comment";
@@ -259,8 +317,13 @@ 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 DEFAULT_OVERLAY_TOGGLE_KEY = "alt+o";
+const DEFAULT_COMMENT_TOGGLE_KEY = "ctrl+g";
 
-function buildCustomUIOptions(displayMode: AskDisplayMode) {
+function buildCustomUIOptions(
+   displayMode: AskDisplayMode,
+   onHandle?: (handle: OverlayHandle) => void,
+) {
    switch (displayMode) {
       case "inline":
          return undefined;
@@ -274,6 +337,7 @@ function buildCustomUIOptions(displayMode: AskDisplayMode) {
                maxHeight: "85%",
                margin: 1,
             },
+            ...(onHandle ? { onHandle } : {}),
          };
       default: {
          const _exhaustive: never = displayMode;
@@ -287,6 +351,7 @@ function buildCustomUIOptions(displayMode: AskDisplayMode) {
                maxHeight: "85%",
                margin: 1,
             },
+            ...(onHandle ? { onHandle } : {}),
          };
       }
    }
@@ -298,6 +363,7 @@ class MultiSelectList implements Component {
    private allowComment: boolean;
    private theme: Theme;
    private keybindings: KeybindingsManager;
+   private commentToggle: ResolvedShortcut;
    private selectedIndex = 0;
    private checked = new Set<number>();
    private commentEnabled = false;
@@ -314,12 +380,14 @@ class MultiSelectList implements Component {
       allowComment: boolean,
       theme: Theme,
       keybindings: KeybindingsManager,
+      commentToggle: ResolvedShortcut,
    ) {
       this.options = options;
       this.allowFreeform = allowFreeform;
       this.allowComment = allowComment;
       this.theme = theme;
       this.keybindings = keybindings;
+      this.commentToggle = commentToggle;
    }
 
    public isCommentEnabled(): boolean {
@@ -376,7 +444,7 @@ class MultiSelectList implements Component {
          return;
       }
 
-      if (this.allowComment && isCommentToggleKey(data)) {
+      if (this.allowComment && !this.commentToggle.disabled && this.commentToggle.matches(data)) {
          this.toggleComment();
          return;
       }
@@ -520,6 +588,7 @@ class WrappedSingleSelectList implements Component {
    private allowComment: boolean;
    private theme: Theme;
    private keybindings: KeybindingsManager;
+   private commentToggle: ResolvedShortcut;
    private selectedIndex = 0;
    private searchQuery = "";
    private commentEnabled = false;
@@ -537,12 +606,14 @@ class WrappedSingleSelectList implements Component {
       allowComment: boolean,
       theme: Theme,
       keybindings: KeybindingsManager,
+      commentToggle: ResolvedShortcut,
    ) {
       this.options = options;
       this.allowFreeform = allowFreeform;
       this.allowComment = allowComment;
       this.theme = theme;
       this.keybindings = keybindings;
+      this.commentToggle = commentToggle;
    }
 
    public isCommentEnabled(): boolean {
@@ -763,7 +834,7 @@ class WrappedSingleSelectList implements Component {
          return;
       }
 
-      if (this.allowComment && isCommentToggleKey(data)) {
+      if (this.allowComment && !this.commentToggle.disabled && this.commentToggle.matches(data)) {
          this.toggleComment();
          return;
       }
@@ -868,9 +939,11 @@ 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;
+   private shortcuts: ResolvedAskShortcuts;
    private onDone: (result: AskUIResult | null) => void;
 
    private mode: AskMode = "select";
@@ -909,9 +982,11 @@ class AskComponent extends Container {
       allowMultiple: boolean,
       allowFreeform: boolean,
       allowComment: boolean,
+      displayMode: AskDisplayMode,
       tui: TUI,
       theme: Theme,
       keybindings: KeybindingsManager,
+      shortcuts: ResolvedAskShortcuts,
       onDone: (result: AskUIResult | null) => void,
    ) {
       super();
@@ -922,9 +997,11 @@ 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;
+      this.shortcuts = shortcuts;
       this.onDone = onDone;
 
       // Layout skeleton
@@ -1044,6 +1121,12 @@ class AskComponent extends Container {
 
    private updateHelpText(): void {
       const theme = this.theme;
+      const overlayHint = this.displayMode === "overlay" && !this.shortcuts.overlayToggle.disabled
+         ? literalHint(theme, this.shortcuts.overlayToggle.spec, "hide")
+         : null;
+      const commentHint = this.allowComment && !this.shortcuts.commentToggle.disabled
+         ? literalHint(theme, this.shortcuts.commentToggle.spec, "toggle context")
+         : null;
       if (this.mode === "freeform" || this.mode === "comment") {
          const alternateCancelKeys = this.keybindings
             .getKeys("tui.select.cancel")
@@ -1052,6 +1135,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)
@@ -1064,7 +1148,8 @@ class AskComponent extends Container {
          const hints = [
             literalHint(theme, "↑↓", "navigate"),
             literalHint(theme, "space", "toggle"),
-            this.allowComment ? literalHint(theme, "ctrl+g", "toggle context") : null,
+            commentHint,
+            overlayHint,
             keybindingHint(theme, this.keybindings, "tui.select.confirm", "submit"),
             keybindingHint(theme, this.keybindings, "tui.select.cancel", "cancel"),
          ]
@@ -1079,7 +1164,8 @@ class AskComponent extends Container {
             literalHint(theme, "type", "filter"),
             keybindingHint(theme, this.keybindings, "tui.editor.deleteCharBackward", "erase"),
             literalHint(theme, "↑↓", "navigate"),
-            this.allowComment ? literalHint(theme, "ctrl+g", "toggle context") : null,
+            commentHint,
+            overlayHint,
             keybindingHint(theme, this.keybindings, "tui.select.confirm", "select"),
             literalHint(theme, "esc", "clear/cancel"),
             alternateCancelKeys.length > 0
@@ -1101,6 +1187,7 @@ class AskComponent extends Container {
          this.allowComment,
          this.theme,
          this.keybindings,
+         this.shortcuts.commentToggle,
       );
       list.onSubmit = (result) => this.handleSelectionSubmit([result], list.isCommentEnabled());
       list.onCancel = () => this.onDone(null);
@@ -1119,6 +1206,7 @@ class AskComponent extends Container {
          this.allowComment,
          this.theme,
          this.keybindings,
+         this.shortcuts.commentToggle,
       );
       list.onCancel = () => this.onDone(null);
       list.onSubmit = (result) => this.handleSelectionSubmit(result, list.isCommentEnabled());
@@ -1389,6 +1477,18 @@ export default function(pi: ExtensionAPI) {
                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.",
             }),
          ),
+         overlayToggleKey: Type.Optional(
+            Type.String({
+               description:
+                  "Shortcut for hiding/showing the overlay popup (overlay mode only), e.g. 'alt+o' or 'ctrl+shift+h'. Pass 'off' to disable. Default: PI_ASK_USER_OVERLAY_TOGGLE_KEY env var if set, otherwise 'alt+o'.",
+            }),
+         ),
+         commentToggleKey: Type.Optional(
+            Type.String({
+               description:
+                  "Shortcut for toggling the optional comment/extra-context row when allowComment is true, e.g. 'ctrl+g'. Pass 'off' to disable. Default: PI_ASK_USER_COMMENT_TOGGLE_KEY env var if set, otherwise 'ctrl+g'.",
+            }),
+         ),
          timeout: Type.Optional(
             Type.Number({ description: "Auto-dismiss after N milliseconds. Returns null (cancelled) when expired." }),
          ),
@@ -1410,12 +1510,26 @@ export default function(pi: ExtensionAPI) {
             allowFreeform = true,
             allowComment = false,
             displayMode,
+            overlayToggleKey,
+            commentToggleKey,
             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 shortcuts: ResolvedAskShortcuts = {
+            overlayToggle: resolveShortcut(
+               overlayToggleKey,
+               process.env.PI_ASK_USER_OVERLAY_TOGGLE_KEY,
+               DEFAULT_OVERLAY_TOGGLE_KEY,
+            ),
+            commentToggle: resolveShortcut(
+               commentToggleKey,
+               process.env.PI_ASK_USER_COMMENT_TOGGLE_KEY,
+               DEFAULT_COMMENT_TOGGLE_KEY,
+            ),
+         };
          const options = normalizeOptions(rawOptions);
          const normalizedContext = context?.trim() || undefined;
 
@@ -1461,6 +1575,9 @@ export default function(pi: ExtensionAPI) {
          });
 
          let result: AskUIResult | null;
+         let overlayHandle: OverlayHandle | undefined;
+         let removeOverlayInputListener: (() => void) | undefined;
+         let hasAnnouncedHide = false;
          try {
             const customFactory = (tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: AskUIResult | null) => void) => {
                if (signal) {
@@ -1479,14 +1596,43 @@ export default function(pi: ExtensionAPI) {
                   allowMultiple,
                   allowFreeform,
                   allowComment,
+                  effectiveDisplayMode,
                   tui,
                   theme,
                   keybindings,
+                  shortcuts,
                   done,
                );
             };
 
-            const customResult = await ctx.ui.custom<AskUIResult | null>(customFactory, buildCustomUIOptions(effectiveDisplayMode));
+            // Register a raw terminal input listener for the overlay-toggle key 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. Skipped entirely if the user disabled the shortcut.
+            const overlayToggle = shortcuts.overlayToggle;
+            if (
+               effectiveDisplayMode === "overlay"
+               && !overlayToggle.disabled
+               && typeof ctx.ui.onTerminalInput === "function"
+            ) {
+               removeOverlayInputListener = ctx.ui.onTerminalInput((data) => {
+                  if (!overlayToggle.matches(data) || !overlayHandle) return undefined;
+                  const nextHidden = !overlayHandle.isHidden();
+                  overlayHandle.setHidden(nextHidden);
+                  if (nextHidden && !hasAnnouncedHide) {
+                     hasAnnouncedHide = true;
+                     ctx.ui.notify?.(`ask_user hidden — press ${overlayToggle.spec} to reopen`, "info");
+                  }
+                  return { consume: true };
+               });
+            }
+
+            const customResult = await ctx.ui.custom<AskUIResult | null>(
+               customFactory,
+               buildCustomUIOptions(effectiveDisplayMode, (handle) => {
+                  overlayHandle = handle;
+               }),
+            );
 
             if (customResult !== undefined) {
                result = customResult;
@@ -1502,6 +1648,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.7.0",
+  "version": "0.9.0",
   "description": "Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input",
   "type": "module",
   "keywords": [