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
• Batches of 2-4 independent questions in one prompt, with a review page before submitting
• 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, via env var, or in 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
• herdr:blocked lifecycle events while waiting for interactive input
• Structured response and cancellation details 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.

Asking several questions at once

Use questions for 2-4 decisions that are independent of each other and whose prerequisites are already settled. Anything that depends on another answer belongs in a later ask_user call.

{
  "questions": [
    {
      "question": "Which database should the service use?",
      "context": "Both are supported by the ORM; the service is single-region.",
      "options": [
        { "title": "Postgres", "description": "Managed, JSONB support" },
        { "title": "SQLite", "description": "No extra infrastructure" }
      ]
    },
    {
      "question": "Which deploy target?",
      "options": [{ "title": "Fly.io" }, { "title": "Cloudflare" }],
      "allowFreeform": false
    },
    { "question": "Anything else we should know before starting?" }
  ],
  "timeout": 300000
}

The prompt shows one page per question plus a review page. Confirming a page records its answer and moves to the next unanswered question, then to the review page. tab / shift+tab switch pages without losing filters, drafts, or checked options, and number keys on the review page jump back to a question. Only the review page submits. If questions are still unanswered, the first press warns and a second press submits them as skipped. Questions without options open straight in a text editor.

In RPC/headless mode the questions are asked one after another with the fallback dialogs. There is no review page there, so cancelling any question cancels the whole batch.

Personal preferences

Defaults can be configured in a settings file or through environment variables. Per-call tool parameters override both.

Settings file

Create ~/.pi/agent/ask-user.json (or <agent-dir>/ask-user.json when PI_CODING_AGENT_DIR is set):

{
  "displayMode": "inline",
  "singleSelectLayout": "list",
  "allowComment": false,
  "contextExpanded": false,
  "overlayToggleKey": "alt+o",
  "commentToggleKey": "ctrl+g",
  "emitFullEvents": false
}

All keys are optional; unknown keys and wrong-typed values are ignored, matching the env-var behavior. Shortcut keys accept the same "off" / "none" / "disabled" disables and Pi-TUI key specs as the tool parameters. The file is read on every ask_user call, so edits apply without restarting Pi. A file that exists but is not valid JSON fails the call with the path in the error, so a configuration mistake is visible instead of silently ignored.

Privacy: Setting "emitFullEvents": true in this file shares answers and prompt context with other installed extensions through lifecycle events, including selections, comments, freeform text, and offered options on cancellation. Keep it false (the default) unless an extension you trust needs that data. See Events and #51.

Environment variables

Configure per-launch defaults 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
export PI_ASK_USER_CONTEXT_EXPANDED=true

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. Environment variables win over ask-user.json, so one-off launches such as PI_ASK_USER_DISPLAY_MODE=inline pi still work while the settings file holds the persistent defaults.

Display mode

Effective order:

1. Per-call displayMode parameter (if provided)
2. PI_ASK_USER_DISPLAY_MODE (if set to "overlay" or "inline")
3. displayMode in ask-user.json
4. 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 or auto)
3. singleSelectLayout in ask-user.json
4. 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 value