@probabl/pi-ask-user-question

A fork of @juicesharp/rpiv-ask-user-question (v2.12.0, MIT) that scales past four questions and four options:

• Configurable question cap — default raised from 4 to 12, adjustable with maxQuestions (1–50) in the config file. The cap flows into the tool schema (maxItems), the prompt snippet/guidelines the model sees, and the runtime validator.

• Configurable option cap — default raised from 4 to 12 options per question, adjustable with maxOptions (2–50). Same plumbing as maxQuestions: schema, prompt copy and validator agree on one value.

• Scrolling option lists — long lists (single- and multi-select, with or without previews) scroll inside a fixed 20-row budget around the focused option, with ↑ N more / ↓ N more · 7/13 indicators, so the dialog height stays stable however unevenly descriptions wrap.

• Scroll the transcript without leaving the dialog — the dialog docks in place of the chat editor, so the conversation stays visible above it; PgUp / PgDn and the mouse wheel scroll it while arrows / Enter / typing keep editing the dialog, so the context you need to answer stays one page away.

• Windowed tab strip — with many questions the tab strip no longer clips at the right edge. It keeps the focused tab visible, pins Submit on the right, shows a [7/13] position counter, and ‹5 / 3› markers that count hidden tabs (warning-colored while any hidden tab is still unanswered):

   ← [7/13] ‹5  ■ Approach  [ □ Storage ]  □ Caching   □ Logging  3›  ✓ Submit  →
  

Everything else (keys, notes, previews, RPC fallback, i18n) behaves exactly like upstream.

Do not install both this package and the upstream one — both register the ask_user_question tool.

Let the model ask you instead of guessing. This extension gives Pi Agent one tool — ask_user_question — that opens a terminal dialog of up to twelve questions (configurable) with written-out options, and hands your choices back as structured data. Install it if you would rather spend fifteen seconds picking than an hour undoing a wrong assumption.

Install

pi install npm:@probabl/pi-ask-user-question
pi install ./pi-ask-user-question          # local checkout

Restart your Pi session.

Quick start

Nothing to set up — the tool is live as soon as Pi restarts. Hand the model a task with a real decision buried in it:

Add caching to the API client.

Rather than picking a strategy on your behalf, the model calls ask_user_question and a dialog takes over the bottom of your terminal. Move with ↑/↓, choose with Enter, press n to attach a note to a question — or a global note to the whole questionnaire from the Submit tab — or land on the Type something. row to answer in your own words. While typing, Shift+Enter adds a line, Ctrl+G opens Pi's configured external editor, and Ctrl+U clears the draft; browsing another option and returning keeps what you wrote. Esc abandons the questionnaire entirely.

When the questionnaire begins waiting in an interactive TTY, it emits one standard terminal BEL (\x07). Your terminal configuration determines whether that appears as an audible alert, a visual alert, or nothing; redirected and non-TTY output is untouched.

When the model asks several things at once, Tab moves between them and a Submit tab reviews everything before it goes back:

What you get

• Typed options instead of a wall of prose — each question carries 2-12 authored choices (configurable), and every choice comes with a description of what it means or what it costs you.
• You can always answer in your own words — a Type something. row is appended to every question, single- or multi-select, widens to the full pane while you type, keeps its multiline draft visible in that row while you browse, and supports Pi's Shift+Enter newline and Ctrl+G external-editor flows.
• Compare real artifacts, not just labels — an option can carry a markdown preview (ASCII mockup, code, diagram, config) that renders in a bordered box beside the option list.
• One interruption, not five — up to 12 questions (configurable) arrive in a single tabbed dialog, and the Submit tab lists your answers and names anything still blank before you commit.
• Notes on any answer — or on all of them — n opens a multiline note editor on any question tab, and on the Submit tab it opens one global note for the whole questionnaire. Per-question notes reach the model as user notes: <text>, the global note as global note: <text>; neither marks a question answered.
• Read the transcript above the dialog — PgUp / PgDn and the mouse wheel scroll the conversation, down to its very last line, while the dialog stays focused and editable; Ctrl+] collapses the dialog to a single row, then brings it back with your answers intact.
• Works outside the terminal too — in RPC and ACP hosts such as the VS Code pendant or Zed the questionnaire walks through the host's native dialogs (notes are terminal-only and do not carry over), and in non-interactive runs the tool is removed from the model's tool list instead of failing every call.

Configuration

Optional. Settings live in ~/.config/pi-ask-user-question/config.json; the file is read, never written.

Setting	What it does	Default
collapseKey	Key that collapses and expands the dialog. Accepts Pi keybinding ids such as alt+o; "off" disables the shortcut.	"ctrl+]"
maxQuestions	Maximum questions per call (integer 1–50). Updates the schema, the built-in prompt text and the validator together.	12
maxOptions	Maximum authored options per question (integer 2–50). Updates the schema, the built-in prompt text and the validator together.	12
guidance.description	Full replacement for the tool description the model sees. A non-empty string replaces the built-in text entirely — no merging.	built-in description
guidance.promptSnippet	One-line description of the tool in the system prompt — tune how eagerly the model asks.	built-in snippet
guidance.promptGuidelines	Usage guidelines given to the model, as a list of strings.	4 built-in guidelines

{ "collapseKey": "alt+o", "maxQuestions": 20, "maxOptions": 20 }

Malformed JSON falls back to the defaults with a warning; an individual unusable value is silently dropped back to its default. Never an error.

Reference

• Tool schema — parameters, limits, reserved labels, validation errors, the result envelope, and the rpiv:ask-user:prompt event.
• Keyboard and layout — every key, the rows the dialog appends, notes, collapse mode, and how previews and overflow adapt to terminal size.
• Configuration — file lookup and XDG_CONFIG_HOME, the collapseKey grammar, the guidance.* prompt overrides, and how invalid values are handled.
• Hosts and runtime behavior — terminal vs RPC vs non-interactive, what degrades in each, and the load-failure envelopes.
• Localization — the nine shipped languages, how the locale is chosen, and how to add one.

Requirements

• Node.js 22 or newer.
• Pi Agent, with an interactive terminal or an RPC/ACP host. Non-interactive runs never see the tool.
• A terminal at least 100 columns wide for side-by-side previews; narrower terminals stack the preview under the options.

No native dependencies, no compiler, no API keys — the extension makes no model calls of its own.

Troubleshooting

The model says the questionnaire UI failed to load and asks its questions as chat text. The dialog's modules were replaced on disk while Pi was running, usually by a package-manager install touching the store. Repair the install if it is broken, then restart Pi; the failure is not recoverable inside the running process.

Ctrl+] does nothing. On keyboard layouts where ] sits on the shifted layer (Latin American among them) the default is unreachable. Set collapseKey to something you can type, for example "alt+o".

Related

• @juicesharp/rpiv-i18n — optional; installing it renders the dialog chrome in your language and adds /languages.
• @juicesharp/rpiv-pi — the umbrella package whose workflow skills use ask_user_question as their developer checkpoint. /rpiv-setup offers to install the upstream extension (not this fork).

License

MIT — see LICENSE. Original work © juicesharp.

Development

npm install
npm test          # vitest
npm run typecheck # tsc --noEmit

The upstream test suite is included; test/utils/ vendors the parts of rpiv-mono's private test helpers it needs.