@timmyjl12/pi-ask-user
Structured multiple-choice questions for the pi coding agent — ask the user up to 4 questions with options, descriptions, markdown previews, multi-select, per-selection notes, and free-text answers.
Package details
Install @timmyjl12/pi-ask-user from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@timmyjl12/pi-ask-user- Package
@timmyjl12/pi-ask-user- Version
0.5.0- Published
- Nov 19, 2026
- Downloads
- 493/mo · 221/wk
- Author
- timmyjl12
- License
- MIT
- Types
- extension
- Size
- 182.3 KB
- Dependencies
- 0 dependencies · 4 peers
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@timmyjl12/pi-ask-user
Structured multiple-choice questions for the pi coding agent — ask the user up to 4 questions in one tool call, with options, descriptions, markdown previews, multi-select, per-selection notes, and a free-text row. Opt-in session auto mode answers from the working agent's evidence-backed recommendations — without interrupting you, and without ever opening a dialog.
──────────────────────────────────────────────────────────────
← ■ Database □ Region ✓ Submit →
Which database should the service use?
> 1. PostgreSQL ✎ needs Redis
Battle-tested relational
2. SQLite
Embedded, zero-config
3. Type something.
Tab/←→ switch questions • ↑↓ move • n adds a note • Enter selects • Esc cancels
──────────────────────────────────────────────────────────────
What it does
Registers one tool, ask_user, that the model calls when it needs your decisions instead of guessing or stopping to ask in plain text:
- 1–4 questions per call — batched, with a tab bar and answered/unanswered markers.
- 2–4 options per question — each with a label (≤60 chars), optional description, and optional markdown
previewshown for the focused option (single-select only; beside the list on wide terminals, below it on narrow ones). multiSelect— Space toggles, Enter submits the question with the whole toggled set.- Per-selection notes —
non any option opens a note editor bound to that choice; Enter saves (empty clears), Escape keeps the prior note. Each note rides its selection into the model's answer aslabel (note: text)— on single-select, multi-select, and RPC hosts alike. - Reserved
Type something.row — appended to every question automatically; the model cannot author it orOther, and supplying those labels fails closed with an exact constraint message. - Short
headerchips (≤16 chars) identify each question in the tab bar and the result. - Session auto mode — answers from the main agent's best-fit recommendation, with rationale and explicit automatic-answer attribution, and never opens a dialog so unattended runs always finish. An opt-in model fallback picks the best option from the session's code and data evidence when no recommendation is given. No dependency on pi-todo.
- Tab marker while a question waits — the terminal title gets a leading
?and the tab spinner stops, so a pending question never looks like work in progress.
Auto mode
Manual is the default. Use the extension's own controls:
/ask-user Open the grouped settings menu
/ask-user mode Jump straight to the mode section
/ask-user auto on Enable automatic answers (agent's recommendation)
/ask-user auto model Enable automatic answers with model fallback
/ask-user auto off Return to manual questioning
/ask-user model Open the chooser-model section
/ask-user model session <provider/id[:level]> Pin the chooser model for this session
/ask-user model user <provider/id[:level]> Save a default to pi-ask-user.json
/ask-user model main Pin "follow the main model" for this session
/ask-user model clear Clear the session override (inherit pi-ask-user.json)
/ask-user status Show the current mode and chooser model
/ask-user history Browse this session's ask_user answers
/ask-user config Show the config path and its current values
The footer shows Ask: auto (or Ask: auto +model) while enabled. Mode and chooser model survive reload/resume in the same session and follow their active branch; new/forked sessions start manual, even if they copy history. Cancelling any menu changes nothing.
Settings menu
/ask-user opens a grouped menu, one section deep:
| Section | What it controls |
|---|---|
| Mode | Manual / Auto / Auto + model fallback |
| Chooser model | Follow the main model · Set for this session… · Set as my default… · Clear the session override |
| Status & history | Current mode + chooser model, and the answer history |
| Config file | The pi-ask-user.json path and its current values |
Auto mode never opens a dialog — on TUI, RPC, and headless hosts alike — so an unattended run always finishes. Every ordinary call is answered immediately from the agent's best-fit choice and a short reason, based on your instructions, approved scope, and project constraints. It does not blindly choose the first option.
Selection policy
Two policies, chosen in the menu or with the commands above:
| Policy | Command | When a question has no recommendation |
|---|---|---|
| Strict (default) | /ask-user auto on |
Returns repair guidance to the agent. No model call, no guess. |
| Model fallback | /ask-user auto model |
The extension asks a model to pick the best option from the session's code and data evidence. |
A present recommendation always wins — it comes from the model that already read your code and data. The fallback only ever fills a gap, and its choice is validated with the same fail-closed rules as the agent's. Chooser requests are bounded three ways — the run's cancel signal, a per-attempt deadline (chooserTimeoutMs, 60s by default), and a whole-call budget — and each attempt is raced against its deadline as well as signalled, so a provider or transport that ignores the abort signal still cannot hang the run. Fallback answers are marked [auto·model: …] so you can see which model picked them.
Chooser model
The chooser tries models in a fixed order and uses the first that answers:
- The configured model — a session pin, else your
pi-ask-user.jsondefault. - The session's main model — the "fall to the main model" default.
- Your
pi-fallback-chainswalk — the same glob-keyed chains you already configured, applied to each model that was tried, deduplicated and capped by that file'smaxFailoversPerRequest. - The terminal fallback —
openrouterTim/openrouter/fusion:xxs, one reserved attempt after everything else is exhausted.
Defaults follow pi-fallback-chains, including when no config file exists at all: terminalFallback is on and maxFailoversPerRequest is 4. Set "terminalFallback": false in pi-fallback-chains.json to turn the reserved Fusion attempt off. The terminal model is never used as an ordinary chain target — if a chain names it, it is hoisted into this final slot only. That reservation applies to the fallback walk: if you pin Fusion yourself or make it your session's main model it will of course run earlier, and it is not expanded into further chain routes.
Models outside the session's model scope (--models / enabledModels) are skipped. When every candidate fails the question returns fail-closed guidance — never a dialog — and the error names each attempt with its real cause (a provider failure that resolves rather than rejects is read from errorMessage, so a chain diagnosis shows 429 rate limit, invalid api key, and so on rather than a useless "returned no selection").
Session pin vs global default. Three states, kept distinct:
| State | How to set it | Meaning |
|---|---|---|
| Inherit | /ask-user model clear |
Use pi-ask-user.json (which may itself pin nothing) |
| Follow main | /ask-user model main |
Always use the session's main model, even if the config pins one |
| Pinned | /ask-user model session <provider/id[:level]> |
Use this model first, for this session only |
The global default lives at ~/.pi/agent/pi-ask-user.json (or $PI_CODING_AGENT_DIR/pi-ask-user.json) — the same <agentDir>/<package>.json convention as pi-advisor, pi-statusline and pi-fallback-chains:
{
"chooserModel": "agy/gemini-4-hydrogen",
"chooserTimeoutMs": 60000
}
chooserModel accepts provider/id, optionally provider/id:<thinkingLevel>; unset or null means follow the main model. The file is parsed tolerantly and unknown keys are preserved when /ask-user model user writes to it, so this extension cannot drop another tool's settings.
Thinking levels are honoured from both the pin (:max) and chain targets ("thinking_level": "max"). The one gap: "off" is recognised while parsing, so provider/id:off correctly strips the suffix, but it is not forwarded to the provider — pi-ai's provider-neutral reasoning option has no "off" value.
pi-fallback-chains is not imported. It is a separate pi package and, more importantly, it only recovers whole agent turns (agent_end/agent_settled → setModel() → re-send) — it never intercepts a model call, so an extension's own completion gets no failover from it. This extension therefore reads the same pi-fallback-chains.json (via PI_FALLBACK_CHAINS_CONFIG, then <cwd>/.pi/, then <agentDir>/) and walks the same chains itself, including its no-file defaults.
The mirror is a deliberate duplication, and it is tested — but it is still a copy.
- covered by tests in
test/model-choice.test.ts: anchored globs where*spans/and?is one character (literal., no regex), exact-key-beats-glob then most-literal ranking,:<level>stripped only for real levels, both chain authoring shapes (bare arrays and{ thinking_level, targets }/{ models }), the level-field-beats-suffix rule,defaultChainas a catch-all tail and as the no-match plan, empty chain keys skipped so they cannot shadow it,enabled:falsedisabling the whole mechanism including the terminal fallback,maxFailoversPerRequest(with 0 falling back to 4 and omp'sretry.maxRetrieshonoured), wildcard targets expanded over the catalogue and ranked by family affinity, cascading into a chain target's own chain (including chains reached through the defaultChain tail), the terminal fallback as one reserved final attempt, config lookup order (PI_FALLBACK_CHAINS_CONFIG, then<cwd>/.pi/, then<agentDir>/) with the project-scoped file winning, and the parse-error rule (a malformed file disables rather than falling through; a missing env override is a misconfiguration, not an absence). What is asserted less directly: a read failure other thanENOENTis handled the same way as a parse failure, but the suite does not induce one.
What is not the same, and is not a bug:
"off"is recognised while parsing soprovider/id:offstrips the suffix correctly, but it is not forwarded to the provider — pi-ai's provider-neutralreasoningoption has no "off" value.- Candidate ordering and coverage within the walk is planned up front rather than
incrementally. Upstream re-plans on each real failure and hoists fresh exact-key targets ahead of
wildcard leftovers from earlier hops; here the whole list is built before the first attempt.
defaultChainis still a tail and the same first-choice routes are tried, but because the failover budget is spent on a pre-planned list, a deep cascade can reach a different set of routes than upstream would after several real failures. The budget changes which routes run, not only their order.
Everything else matches, including the matcher's semantics against a literal * in a model key and
the fact that * and ? cannot cross a line terminator (regex .). And because this is a copy
rather than an import, it will drift if upstream changes its rules; the tests are the canary.
For ordinary questions, the main agent supplies its best-fit choice and a short reason, based on your instructions and project constraints. Auto mode validates and returns that choice immediately, without TUI/RPC dialogs — even on headless hosts.
Example tool parameters (recommendation indices are zero-based, unlike the RPC manual input's 1-based indices):
{
"questions": [{
"question": "Which database should the local tool use?",
"header": "Database",
"options": [{ "label": "PostgreSQL" }, { "label": "SQLite" }],
"recommendation": {
"optionIndices": [1],
"reason": "Embedded storage matches the approved single-user scope."
}
}]
}
Each recommendation needs unique integer indices within the supplied options and a nonblank reason of at most 500 characters. Single-select needs exactly one index; multi-select may recommend multiple options. Invalid metadata fails closed. Under the default policy, missing recommendations return guidance for the main agent to repair the call — not a dialog, an arbitrary default, or a user decline.
Human boundaries — read this before enabling auto mode. requiresHuman: true does not open a prompt while auto mode is on: the call is answered from the evidence-backed recommendation, marked [auto], and flagged in the result. That is deliberate — a call that blocks on a dialog is exactly how a run stalls for hours — but it does mean an approval-style question may be answered differently from what you would have picked. The transcript always shows [auto: …] and names the override. When a person must really decide, run /ask-user auto off first; requiresHuman keeps the existing manual UI/no-UI behaviour in manual mode.
Auto mode does not invent secrets, user notes, or human approval, and other extensions' confirmation/approval gates remain unaffected — this extension is not an authorization system. A cancelled automatic call is not automatically retried.
Automatic results say the agent selected the answers and include the reason. details.source is "auto", each answer includes autoReason and autoSource ("agent" or "chooser"), and transcript lines show [auto: …] (or [auto·model: …]). A call that asked for a human carries details.autoAnsweredRequiresHuman. Old/manual results retain their user attribution and optional notes.
pi-todo is unchanged: Pi continues naturally after an answer is returned. This extension adds no task runner, continuation loop, or timer.
History
/ask-user history lists the ask_user calls on the current session branch, newest first (latest 20): time, [user]/[auto]/[declined]/[partial], answers and notes. Pick one to see the full questions and auto reasons. It reads the session log on demand — the details already stored on each tool result — so it keeps no in-memory state, writes no new entries, and adds nothing to the model's context. Other sessions and abandoned branches are not shown.
Behavior
| Input | Result |
|---|---|
| Enter on an option | Selects it and advances (single-question runs submit immediately) |
Enter on Type something. |
Opens an inline editor; Enter submits, empty returns to the list |
| Space (multiSelect) | Toggles the focused option |
n on an option |
Opens that option's note editor; Enter saves (empty clears), Esc keeps the prior note. Notes travel with their selection; a note on an unselected option is dropped |
| Tab / Shift+Tab / ← / → | Switch questions (multi-question runs); answers and notes persist |
| Escape in the editor | Returns to the options |
| Escape on the options | Cancels the whole questionnaire — the model sees a decline, not an error |
Result envelopes are structured (details.questions, details.answers with parallel selected/wasCustom/notes arrays, details.cancelled) so the transcript renders ✓ header: answer lines, (wrote) markers for typed answers, and (note: …) for noted selections. Answers persisted before notes existed (v0.1.0 sessions) still render.
Host support
Manual calls degrade by host capability. Auto-mode calls bypass this ladder entirely and answer without any UI:
- Interactive (TUI) — the full questionnaire above. While it waits, the tab title carries a leading
?and pi's terminal progress spinner (terminal.showTerminalProgress) is paused; answering restores both, and the spinner only returns while the run is still live. - RPC hosts (e.g. editor integrations) — each question is asked through the host's native select/input dialogs via the extension UI sub-protocol: single-select via select dialog, multi-select via one typed input (comma-separated labels or 1-based indices; unmatched entries are kept as custom selections), and an optional note prompt after each matched selection (Enter to skip; skipping or dismissing a note never cancels the questionnaire).
- Headless (print/JSON) — a structured error telling the model the user never saw the questions, so it falls back to plain text instead of misreading a decline.
Install
pi install npm:@timmyjl12/pi-ask-user
Or try it for one run without installing: pi -e npm:@timmyjl12/pi-ask-user. Restart pi (or run /reload) after installing. Requires pi 1.0 or newer.
Design provenance
Built for stability alongside the @timmyjl12/pi-* extension family, synthesizing four reference implementations — rpiv-ask-user-question (limits, reserved labels, fail-closed validation, RPC walker, n-key notes), edlsh/pi-ask-user (flat schema shapes, Esc ladder, typed-selections RPC multi-select), UniPi ask-user (width-crash regression discipline, per-option custom text), picc-tasks (tool description style) — plus the official pi question.ts/questionnaire.ts examples. Configuration follows the family convention: a session-scoped override plus a global pi-ask-user.json, matching pi-advisor. Fuzzy search and task-continuation scheduling remain out of scope. Auto mode uses session lifecycle hooks only; the model fallback additionally uses the session's model registry, bounded by the turn's cancel signal and a deadline.
Development
npm install
npm run check # typecheck + full vitest suite (incl. widths 1-200 regression)
License: MIT