pi-ask-user
Interactive decision-gating extension for pi — lets AI agents ask users questions with multiple-choice and freeform answers
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/edlsh/pi-ask-user with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/edlsh/pi-ask-user'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/edlsh--pi-ask-user)HTML
<a href="/listings/edlsh--pi-ask-user"><img src="/api/listings/edlsh--pi-ask-user/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
pi install npm:pi-ask-user
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 314 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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](https://github.com/edlsh/pi-ask-user/blob/main/media/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
- ```bash
- pi install npm:pi-ask-user
- ```
- ## Tool name
- The registered tool name is:
- - `ask_user`
- ## Parameters
- | Parameter | Type | Default | Description |
- |-----------|------|---------|-------------|
- | `question` | `string?` | — | The question to ask the user. Each call needs `question` or `questions`; when both are sent, `question` is only shown as the batch heading |
- | `questions` | `{question, context?, options?, allowMultiple?, allowFreeform?}[]?` | — | 2-4 independent questions shown together, used instead of `question`. Set `context`, `options`, `allowMultiple`, and `allowFreeform` on each entry; top-level values for them are ignored. The remaining parameters apply to the whole batch. See [Asking several questions at once](#asking-several-questions-at-once) |
- | `context` | `string?` | — | Relevant context summary shown before the question |
- | `options` | `{title, description?}[]?` | `[]` | Multiple-choice options. The schema is a flat object shape (no `anyOf`, which some provider proxies strip or reject); plain strings and common alias keys (`label`, `text`, `value`, `name`, `option`) are still accepted at runtime |
- | `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
- | `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
- | `allowComment` | `boolean?` | env var, settings file, or `false` | Expose a user-toggleable extra-context option in the custom UI (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
- | `displayMode` | `"overlay" \| "inline"?` | env var, settings file, or `"overlay"` | Controls custom UI rendering: `overlay` shows the centered modal (current behavior), `inline` renders without overlay framing |
- | `singleSelectLayout` | `"auto" \| "list"?` | env var, settings file, or `"auto"` | Use the responsive details pane automatically or always render descriptions below their options |
- | `contextExpanded` | `boolean?` | env var, settings file, or `false` | Start with oversized context expanded. Per-call value overrides `PI_ASK_USER_CONTEXT_EXPANDED` |
- | `overlayToggleKey` | `string?` | env var, settings file, or `"alt+o"` | Shortcut for hiding/showing the overlay popup (overlay mode only). Pi-TUI key spec, e.g. `"alt+o"`, `"ctrl+shift+h"`. Pass `"off"` to disable. |
- | `commentToggleKey` | `string?` | env var, settings file, or `"ctrl+g"` | Shortcut for toggling the optional comment/extra-context row when `allowComment: true`. Pass `"off"` to disable. |
- | `timeout` | `number?` | — | Auto-dismiss after N ms and return `null` if the prompt times out |
- ## Example usage shape
- ```json
- {
- "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.
- ```json
- {
- "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):
- ```jsonc
- {
- "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](#events) and [#51](https://github.com/edlsh/pi-ask-user/issues/51).
- ### Environment variables
- Configure per-launch defaults by setting these in your shell profile (`~/.zshrc`, `~/.bash_profile`, etc.):
- ```bash
- 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 values are also accepted)
- 3. `allowComment` in `ask-user.json`
- 4. Fallback default: `false`
- ### Context expansion
- Oversized context collapses behind a one-line summary so the question and choices stay visible. To start expanded instead:
- 1. Per-call `contextExpanded` parameter (if provided)
- 2. `PI_ASK_USER_CONTEXT_EXPANDED` (`true`, `1`, `yes`, or `on`; corresponding false values are also accepted)
- 3. `contextExpanded` in `ask-user.json`
- 4. Fallback default: `false`
- `ctrl+e` still toggles from whichever state the prompt opened in.
- ### 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. Matching key in `ask-user.json` (`overlayToggleKey` / `commentToggleKey`)
- 4. 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`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) 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:
- | Key | Action |
- |-----|--------|
- | `alt+o` (configurable via `overlayToggleKey`) | Hide/show the overlay popup so you can read the agent's prior output. Available in `overlay` mode only. The first time you hide it, a notification reminds you which key brings it back. |
- | `ctrl+g` (configurable via `commentToggleKey`) | Toggle the optional comment/extra-context row (when `allowComment: true`). |
- | `ctrl+e` | Expand or collapse oversized context while choosing an option. If another configured ask shortcut owns it, the prompt shows `ctrl+x` or `ctrl+y` instead. |
- | `enter` | Confirm the focused option, submit a freeform response, or submit/skip an optional comment. In a batch, confirming records the answer; on the review page it submits. |
- | `esc` | Clear the search filter, exit freeform/comment mode, or cancel the prompt. In a batch, cancelling cancels every question. |
- | `↑` / `↓`, `ctrl+k` / `ctrl+j` | Navigate options. `ctrl+k` / `ctrl+j` (vim-style) work while typing in searchable prompts without disturbing the filter. On a batch's review page they scroll the answers. |
- | `tab` / `shift+tab` | Single question: move down/up through the options. Batch: switch to the next/previous question or the review page. |
- | `1`-`4` | Batch review page: jump back to that question. |
- If you prefer never to see the overlay, set `displayMode: "inline"` per call or `PI_ASK_USER_DISPLAY_MODE=inline` globally.
- ### Cancellation
- Aborting a tool call dismisses its active prompt, including freeform and RPC dialogs. Cancelling or timing out an optional RPC comment cancels the whole answer; press Enter with an empty comment to submit the selection without a comment.
- The custom UI uses one timeout for the prompt. In the dialog fallback, the configured timeout applies separately to each dialog stage of a single question. A batch has one deadline for all of its questions, in the custom UI and in the dialog fallback.
- ### 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.
- ### Tern
- With [pi-tern](https://github.com/edlsh/pi-tern) in a [Tern](https://stencil.so) pane, the prompt takes the composer's place, laid out like omp's ask dialog: question tabs for a batch, the question and context as markdown, the options as a clickable list, a native editor for custom responses and comments, a review page and an action bar. Keys still go to `ask_user` as in any terminal. The tool card shows each question over all of its options, with a check on the chosen ones. Both hooks use pi-tern's global symbols, so nothing changes when pi-tern isn't installed.
- ### Events
- 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.
- When a displayed prompt resolves with an answer or cancellation, it emits `ask:answered` or `ask:cancelled`. Calls aborted before a prompt opens emit neither outcome event. Every installed extension receives these, so by default they carry only what is needed to correlate the prompt with its outcome:
- ```typescript
- // ask:answered
- { question: string; response: { kind: "selection" | "freeform" } }
- // ask:cancelled
- { question: string }
- ```
- A batch publishes nothing until the user submits it. Then each answered question emits `ask:answered` and skipped questions emit nothing; a cancelled batch emits `ask:cancelled` for every question. Batch events carry the same payload plus the question's position:
- ```typescript
- { ...payload, batch: { index: number; total: number } }
- ```
- Set `PI_ASK_USER_EMIT_FULL_EVENTS=true` (or `1`, `yes`, `on`), or `"emitFullEvents": true` in `ask-user.json`, to restore the full payloads — `context`, the offered `options` on cancel, and the complete `response` including selections, comment, and freeform text. Leave it unset unless another extension you trust needs the answer itself; the full response is always available to the agent through the tool result's `details`.
- ## Known limitations
- - **Overlays cannot draw over inline images** ([#8](https://github.com/edlsh/pi-ask-user/issues/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
- Answers and cancellations include structured prompt `details` for rendering and session state reconstruction:
- ```typescript
- 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;
- }
- ```
- A `questions` batch returns separate details; the single-question shape above is unchanged:
- ```typescript
- interface AskBatchDetails {
- kind: "batch";
- questions: Array<{ question: string; context?: string; options: QuestionOption[] }>;
- // Index-aligned with questions; empty when the batch was cancelled.
- answers: Array<{ status: "answered"; response: AskResponse } | { status: "skipped" }>;
- cancelled: boolean;
- }
- ```
- Malformed options, invalid `questions` batches, unavailable interactive UI, and UI failures throw so Pi records a failed tool call rather than a successful answer. These host-created error results do not guarantee either details shape. Error rendering also accepts older stored results with `details: { error: string }`.
- ## Contributing
- See [CONTRIBUTING.md](https://github.com/edlsh/pi-ask-user/blob/main/CONTRIBUTING.md) for development setup and checks.
- ## Changelog
- See [CHANGELOG.md](https://github.com/edlsh/pi-ask-user/blob/main/CHANGELOG.md).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.