pi-ask-user

A Pi package that adds an interactive ask_user tool for collecting user decisions during an agent run.

Demo

High-quality video: ask-user-demo.mp4

Features

• Searchable single-select option lists with wrapped titles and descriptions
• Responsive split-pane details preview on wide terminals with single-column fallback on narrow terminals
• Multi-select option lists
• Optional freeform responses
• 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
• Optional timeout for auto-dismiss in both overlay and fallback input modes
• Structured details on all results for session state reconstruction
• Graceful fallback when interactive UI is unavailable
• Bundled ask-user skill for mandatory decision-gating in high-stakes or ambiguous tasks

Bundled skill: ask-user

This package now ships a skill at skills/ask-user/SKILL.md that nudges/mandates the agent to use ask_user when:

• architectural trade-offs are high impact
• requirements are ambiguous or conflicting
• assumptions would materially change implementation

The skill follows a "decision handshake" flow:

1. Gather evidence and summarize context
2. Ask one focused question via ask_user
3. Wait for explicit user choice
4. Confirm the decision, then proceed

See: skills/ask-user/references/ask-user-skill-extension-spec.md.

Install

pi install npm:pi-ask-user

Tool name

The registered tool name is:

• ask_user

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | 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 | | 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 | | 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

{
  "question": "Which option should we use?",
  "context": "We are choosing a deploy target.",
  "options": [
    "staging",
    { "title": "production", "description": "Customer-facing" }
  ],
  "allowMultiple": false,
  "allowFreeform": 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 preferences via environment variables

Configure your defaults globally by setting these in your shell profile (~/.zshrc, ~/.bash_profile, etc.):

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

Display mode

Effective order:

1. Per-call displayMode parameter (if provided)
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 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. | | ↑ / ↓, ctrl+k / ctrl+j | Navigate options. ctrl+k / ctrl+j (vim-style) work while typing in searchable prompts without disturbing the filter. |

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:

type AskResponse =
  | { kind: "selection"; selections: string[]; comment?: string }
  | { kind: "freeform"; text: string };

interface AskToolDetails {
  question: string;
  context?: string;
  options: QuestionOption[];
  response: AskResponse | null;
  cancelled: boolean;
}

Changelog

See CHANGELOG.md.