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 a persistent single-column preference
• Multi-select option lists
• Optional freeform responses
• User-toggleable extra context on structured selections
• Context display support
• Responsive context collapse that keeps the question and choices visible on small terminals without discarding full context
• 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
• herdr:blocked lifecycle events while waiting for interactive input
• 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

Example usage shape

{
  "question": "Which option should we use?",
  "context": "We are choosing a deploy target.",
  "options": [
    { "title": "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_SINGLE_SELECT_LAYOUT=list
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:

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".

Single-select layout

Effective order:

1. Per-call singleSelectLayout parameter (if provided)
2. PI_ASK_USER_SINGLE_SELECT_LAYOUT (when set to list)
3. Fallback default: auto

auto shows the details pane on wide terminals. list keeps descriptions below their options at every width.

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:

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:

If you prefer never to see the overlay, set displayMode: "inline" per call or PI_ASK_USER_DISPLAY_MODE=inline globally.

Mobile-sized terminals

If context wraps beyond the available decision area, ask_user collapses it into a one-line summary so the question and at least one choice remain visible. Press the context key shown in the prompt (ctrl+e by default) to expand or collapse the complete context; expanded context remains bounded and scrollable with the existing prompt-scroll keys in both display modes.

Waiting lifecycle event

While an interactive prompt is open, the extension emits herdr:blocked with { active: true, label: "Waiting for user response" }. It emits { active: false } in finally, including cancellation and error paths. Hosts without a listener are unaffected.

Known limitations

• Overlays cannot draw over inline images (#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:

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.