pi-ask-user

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

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 via env var or ask-user.json) 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 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:@yandy0725/pi-ask-user

Tool name

The registered tool name is:

• ask_user

Parameters

Appearance options (displayMode, overlayToggleKey, commentToggleKey) are not model-visible parameters. They are user preferences resolved from env vars and ask-user.json — see Display mode and Shortcuts. They remain accepted by the internal AskParams type for SDK/direct callers, but an LLM tool call cannot set them.

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
}

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. PI_ASK_USER_DISPLAY_MODE (if set to "overlay" or "inline")
2. Project config file .pi/ask-user.json displayMode field (if exists)
3. User config file ~/.pi/agent/ask-user.json displayMode field (if exists)
4. Fallback default: "overlay"

(A per-call displayMode still wins over all of the above for SDK/direct callers, but the field is no longer part of the model-visible tool schema.)

Unrecognised values are silently ignored and fall back to "overlay".

Personal preferences via config files

In addition to environment variables, you can use JSON config files:

Locations:

• User-level (global): ~/.pi/agent/ask-user.json
• Project-level: .pi/ask-user.json

Fields in the project-level file override same-named fields in the user-level file. Priority: env var > project config > user config > default.

Example ~/.pi/agent/ask-user.json:

{
  "displayMode": "inline",
  "overlayToggleKey": "alt+h",
  "commentToggleKey": "alt+c"
}

All fields are optional. Missing files or malformed JSON are silently ignored, equivalent to no configuration.

Shortcuts

Effective order for both overlayToggleKey and commentToggleKey:

1. Matching env var (PI_ASK_USER_OVERLAY_TOGGLE_KEY / PI_ASK_USER_COMMENT_TOGGLE_KEY)
2. Project config file .pi/ask-user.json (if exists)
3. User config file ~/.pi/agent/ask-user.json (if exists)
4. Built-in defaults: alt+o and ctrl+g

(A per-call parameter still wins for SDK/direct callers, but these fields are no longer part of the model-visible tool schema.)

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 PI_ASK_USER_DISPLAY_MODE=inline globally or "displayMode": "inline" in ask-user.json.

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;
}

Credits

This project is based on pi-ask-user by Enzo Lucchesi. Thank you to the original author for the excellent work.

License

MIT