pi-ask-user 0.6.0 → 0.7.0

package/README.md

@@ -16,7 +16,7 @@ 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)
 - Pi-TUI-aligned keybinding and editor behavior
 - Custom TUI rendering for tool calls and results
 - System prompt integration via `promptSnippet` and `promptGuidelines`
@@ -63,7 +63,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 +79,29 @@ 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"`.
+
 ## 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,
@@ -33,8 +33,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 +62,7 @@ interface AskParams {
    allowMultiple?: boolean;
    allowFreeform?: boolean;
    allowComment?: boolean;
+   displayMode?: AskDisplayMode;
    timeout?: number;
 }
 
@@ -239,6 +260,38 @@ const SINGLE_SELECT_SPLIT_PANE_SEPARATOR = " │ ";
 const FREEFORM_SENTINEL = "\u270f\ufe0f Type custom response...";
 const COMMENT_TOGGLE_LABEL = "Add extra context after selection";
 
+function buildCustomUIOptions(displayMode: AskDisplayMode) {
+   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,
+            },
+         };
+      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,
+            },
+         };
+      }
+   }
+}
+
 class MultiSelectList implements Component {
    private options: QuestionOption[];
    private allowFreeform: boolean;
@@ -1292,12 +1345,14 @@ export default function(pi: ExtensionAPI) {
       name: "ask_user",
       label: "Ask User",
       description:
-         "Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Before calling, gather context with tools (read/web/ref) and pass a short summary via the context field.",
+         "Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Ask exactly one focused question per call. Before calling, gather context with tools (read/web/ref) and pass a short summary via the context field.",
       promptSnippet:
-         "Ask the user a question with optional multiple-choice answers to gather information interactively",
+         "Ask the user one focused question with optional multiple-choice answers to gather information interactively",
       promptGuidelines: [
          "Before calling ask_user, gather context with tools (read/web/ref) and pass a short summary via the context field.",
          "Use ask_user when the user's intent is ambiguous, when a decision requires explicit user input, or when multiple valid options exist.",
+         "Ask exactly one focused question per ask_user call.",
+         "Do not combine multiple numbered, multipart, or unrelated questions into one ask_user prompt.",
       ],
       parameters: Type.Object({
          question: Type.String({ description: "The question to ask the user" }),
@@ -1329,6 +1384,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." }),
          ),
@@ -1349,8 +1409,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;
 
@@ -1397,41 +1462,31 @@ export default function(pi: ExtensionAPI) {
 
          let result: AskUIResult | null;
          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 });
-                  }
-
-                  if (timeout && timeout > 0) {
-                     setTimeout(() => done(null), timeout);
-                  }
-
-                  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 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);
+               }
+
+               return new AskComponent(
+                  question,
+                  normalizedContext,
+                  options,
+                  allowMultiple,
+                  allowFreeform,
+                  allowComment,
+                  tui,
+                  theme,
+                  keybindings,
+                  done,
+               );
+            };
+
+            const customResult = await ctx.ui.custom<AskUIResult | null>(customFactory, buildCustomUIOptions(effectiveDisplayMode));
 
             if (customResult !== undefined) {
                result = customResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-user",
-  "version": "0.6.0",
+  "version": "0.7.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