Each question provides 2–4 options and may allow multiple selections.
Optional question IDs provide stable answer keys.
Free-form answers are always available.
Commands: none.
Hooks: none.
Settings: none.
Behavior
Questions are presented sequentially.
TUI: one overlay per question with the supplied options plus Other….
Questions, options, answers, notes, and tool call/result text wrap to the available width.
Enter selects, Tab opens an optional notes field, Esc cancels the whole call and terminates the turn.
Multi-select questions toggle options with Space.
Fullscreen TUI mode also supports clicking options, clicking to position the answer or notes cursor, and wheel navigation.
Regular TUI mode leaves mouse input to the terminal.
RPC: uses Pi dialogs (select, input, and confirm).
Other (free text) is always offered.
Dismissing any dialog cancels the whole call.
Print and JSON modes (hasUI === false): returns {"status":"unavailable"} immediately instead of blocking.
Model-supplied options whose labels begin with Other are removed.
Missing headers are derived from the question ID or text and truncated to 12 characters.
Duplicate answer keys receive numeric suffixes such as -2.
Result contract
{"status":"answered","answers":{"<id or question>":{"answers":["Postgres (Recommended)"]}}}
Answers are keyed by id when provided, otherwise by the full question text.
Free-form answers appear in the same answers array as option labels.
notes contains optional TUI commentary and is omitted when empty.
Debug
Opt in through debug logging.
Safe events: session.start, session.shutdown, ask.flow.start, ask.flow.finish, ask.flow.error.
# ask
Structured multiple-choice questions from the model to the human, similar to Claude Code's `AskUserQuestion` and Codex's `request_user_input`.
## Install / load
Loaded through the root [`pi-ext` package](../../README.md).
## Commands / tools / settings
- Tool: `ask_user_question`
- Accepts 1–4 questions.
- Each question provides 2–4 options and may allow multiple selections.
- Optional question IDs provide stable answer keys.
- Free-form answers are always available.
- Commands: none.
- Hooks: none.
- Settings: none.
## Behavior
- Questions are presented sequentially.
- TUI: one overlay per question with the supplied options plus `Other…`.
Questions, options, answers, notes, and tool call/result text wrap to the available width.
Enter selects, Tab opens an optional notes field, Esc cancels the whole call and terminates the turn.
Multi-select questions toggle options with Space.
Fullscreen TUI mode also supports clicking options, clicking to position the answer or notes cursor, and wheel navigation.
Regular TUI mode leaves mouse input to the terminal.
- RPC: uses Pi dialogs (`select`, `input`, and `confirm`).
`Other (free text)` is always offered.
Dismissing any dialog cancels the whole call.
- Print and JSON modes (`hasUI === false`): returns `{"status":"unavailable"}` immediately instead of blocking.
- Model-supplied options whose labels begin with `Other` are removed.
- Missing headers are derived from the question ID or text and truncated to 12 characters.
- Duplicate answer keys receive numeric suffixes such as `-2`.
## Result contract
```json
{"status":"answered","answers":{"<id or question>":{"answers":["Postgres (Recommended)"]}}}
```
Answers are keyed by `id` when provided, otherwise by the full question text.
Free-form answers appear in the same `answers` array as option labels.
`notes` contains optional TUI commentary and is omitted when empty.
## Debug
Opt in through [debug logging](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `ask.flow.start`, `ask.flow.finish`, `ask.flow.error`.