# Ask tool contract `ask_user` is a pi-native clarification tool for cases where implementation depends on user preference or missing requirements. This document defines the stable external behavior. It does not explain internal helper-by-helper implementation. ## Input ```ts { title?: string; questions: Array<{ id: string; label?: string; prompt: string; type?: "single" | "multi" | "preview"; required?: boolean; options: Array<{ value: string; label: string; description?: string; preview?: string; }>; }>; } ``` ## Input rules - at least one question is required - every question must have non-empty trimmed `id` and `prompt` - every question must have at least one option - question ids must be unique within one tool call - option `value`s must be unique within a question - optional `label`, `description`, and `preview` fields must not be blank when provided - `label` falls back to `Q1`, `Q2`, ... - `type` defaults to `single` - `required` defaults to `false` - `required` is metadata only; it never blocks submission - preview questions require preview text for every declared option; option descriptions do not satisfy this requirement, and invalid preview payloads report a fix hint to add preview text or switch to `type: "single"` - all questions get an internal `Type your own` option ## Output ```ts { content: [{ type: "text"; text: string }]; details: { title?: string; cancelled: boolean; error?: { kind: "invalid_input"; issues: Array<{ path: string; message: string; }>; }; mode: "submit" | "elaborate"; questions: Array<{ id: string; label: string; prompt: string; type: "single" | "multi" | "preview"; presentedType?: "single" | "multi" | "preview"; }>; answers: Record< string, { values: string[]; labels: string[]; indices: number[]; customText?: string; note?: string; optionNotes?: Record; } >; continuation?: { strategy: "refine_only" | "resume"; affectedQuestionIds: string[]; preservedAnswers: Record; }>; questionStates: Record; }; elaboration?: { instruction: string; nextAction: "clarify" | "clarify_then_reask"; items: Array< | { target: { kind: "question" }; question: { id: string; label: string; prompt: string; type: "single" | "multi" | "preview"; presentedType?: "single" | "multi" | "preview"; options: Array<{ value: string; label: string; description?: string; preview?: string; }>; }; answered: boolean; answer?: { values: string[]; labels: string[]; indices: number[]; customText?: string; note?: string; optionNotes?: Record; }; note: string; } | { target: { kind: "option"; optionValue: string }; question: { id: string; label: string; prompt: string; type: "single" | "multi" | "preview"; presentedType?: "single" | "multi" | "preview"; options: Array<{ value: string; label: string; description?: string; preview?: string; }>; }; option: { value: string; label: string; description?: string; preview?: string; }; selected: boolean; answered: boolean; answer?: { values: string[]; labels: string[]; indices: number[]; customText?: string; note?: string; optionNotes?: Record; }; note: string; } >; }; }; } ``` ## Output rules - `cancelled: true` means the user dismissed the flow, UI was unavailable, or the payload was invalid before UI opened - invalid payloads return `error.kind === "invalid_input"` with structured `issues` and a transcript-friendly `Invalid ask_user payload:` message - `mode: "submit"` is normal completion; `mode: "elaborate"` means the user asked the agent to continue with follow-up clarification based on notes - unanswered questions are omitted from `answers` - in `mode: "elaborate"`, `answers` contains only committed answers; note-only entries move to `elaboration.items` - `continuation.strategy === "refine_only"` means the next ask should refine the current flow rather than restart it - `continuation.preservedAnswers` contains previously committed answers that should be kept as context and not re-asked - `continuation.affectedQuestionIds` lists the only questions that should be revisited - `continuation.questionStates` marks each question as `answered`, `needs_clarification`, or `unanswered` - single-select answers still use arrays - when `behaviour.presentSingleAsMulti` is enabled, requested single-select questions are presented and handled as multi-select in future/replayed ask flows; result question metadata keeps the requested `type`, adds `presentedType` when final presentation differs, and result text uses one compact note when any answered questions were presented differently - `indices` are 1-based rendered option positions - `customText` stores the free-form answer - on single-select questions, saving free-form text clears selected options for that question - on multi-select questions, `values` and `labels` include both selected options and `customText` when both are present - on multi-select questions, selected options keep their original order and `customText` is appended last - submitting free-form text on a multi-select question stays on the same question tab and marks the custom row selected - on multi-select questions, toggling an empty custom row opens the free-form editor, while toggling a custom row with saved free-form text selects or deselects it without opening the editor or clearing the text - saving or clearing free-form text on a multi-select question does not clear other selected options - `note` stores a question-level note - `optionNotes` includes only notes for selected options - question notes may exist without a selected answer - `elaboration.items` includes all question notes and all option notes, even for unselected options - every elaboration item includes the full normalized question and option list for that question so referential notes like `above` remain understandable to the agent - option-targeted elaboration items include the specific noted option plus whether it is currently selected - question-targeted elaboration items include whether the question already has a committed answer - `elaboration.instruction` tells the agent to answer the clarification directly first, then re-ask only the affected questions if a choice is still needed - after clarification, agents should prefer another structured follow-up over plain-text multiple choice when a decision is still unresolved - once prior answers narrow the branch, agents should bundle the next 2-3 related unresolved questions into one follow-up ask when possible, instead of using a long sequence of single-question asks - `elaboration` is only present when `mode === "elaborate"` - elaborate `content` text and transcript rendering describe each note directly using the full question prompt and option label, and include the current committed answer text when available, instead of a generic elaboration banner - when the user selects `Elaborate` without adding notes, elaborate `content` text and transcript rendering still include the committed answer text so the agent can elaborate on that answer directly ## Supported UX - tabbed multi-question flow - single-select, multi-select, and preview questions - active question type changes via configurable `main.changeQuestionType` hotkey, default `t`; non-preview questions toggle `single <-> multi`; preview questions toggle `preview <-> multi` - inline free-form answers for all question types - native pi-style `@` file path autocomplete inside free-form answer and note editors - question notes via `Shift+N` - option notes via `n` - number-key quick selection - submit/elaborate/cancel review tab - on the review tab, `Submit` and `Cancel` preview notes only for answered questions - on the review tab, `Elaborate` preview expands to all question notes and all option notes, including notes on unselected options - transcript-friendly call and result rendering - `/answer` command to extract a raw-JSON `AskParams` form from the latest completed assistant message and open the ask UI - `/answer` extraction may use an internal `freeform: true` option for open-ended questions with no explicit choices; these render as user-input-only questions with the label `Type your answer:`, no numbered option row, and no selection caret; this marker is not part of the public `ask_user` tool contract - `/answer:again` command to replay the latest `/answer`-extracted form on the current branch - `/ask:replay` command to replay the latest real `ask_user` form on the current branch - ask settings list with binary behaviour/notification toggles and a guarded reset-to-defaults action - `?` in the ask flow and `/ask-settings` in pi open the same lightweight ask settings overlay - settings attempt to persist immediately when changed: `Auto-submit when answered without notes`, `Confirm dismiss when dirty`, `Double-press review shortcuts`, `Notifications`, and `Show footer hints`; `Present single-select as multi-select` persists immediately when saving succeeds but applies only to new/replayed ask flows; save failures revert the setting and show a manual-edit message; resetting config to defaults requires pressing the reset action twice within a short confirmation window - `Keymaps` is a persisted, context-aware config section for global, main-flow, editor, note-editor, and settings-modal actions - the settings list shows the absolute config file path for customizing keymaps, notifications, and extraction settings - if the flow is already on the review tab, all questions are answered, and no notes exist, enabling auto-submit can complete the current ask flow immediately - elaborate results are phrased as direct follow-up instructions, for example: `User asked to elaborate on question "Which option would you like to select?" option "Option A" with note "why this one?"` ## Keyboard behavior Main flow: - `global.settings` opens ask settings; default: `?` - `global.dismiss` dismisses the active ask surface; default: `Ctrl+C` - `main.nextTab` / `main.previousTab` move between tabs; defaults: `Tab`/`Right`, `Shift+Tab`/`Left` - `main.nextOption` / `main.previousOption` move between options or review actions; defaults: `Down`, `Up` - `main.confirm`, `main.cancel`, and `main.toggle` confirm, cancel, or toggle; defaults: `Enter`, `Esc`, `Space` - `main.changeQuestionType` changes the active question type (non-preview: `single <-> multi`; preview: `preview <-> multi`); default: `t`; destructive `multi -> single` changes require pressing the type hotkey again, with no timeout, and the pending confirmation clears on other navigation/actions - `main.optionNote` and `main.questionNote` open option/question notes; defaults: `n`, `Shift+N` - `1..9` is fixed and selects or toggles the matching option; on the review tab, `1`, `2`, and `3` trigger `Submit`, `Elaborate`, and `Cancel` - when `Double-press review shortcuts` is enabled, review-tab `1`, `2`, and `3` require the same key twice without a timeout, and the review screen shows an inline hint for the pending action Editing flow: - `editor.submit` submits the current custom-answer editor input and closes the editor; default: `Enter` - `noteEditor.save` saves the current note editor and keeps the ask flow open; default: `Enter` - `editor.close` / `noteEditor.close` save draft and close the editor; default: `Esc` - `global.dismiss` dismisses the entire flow immediately without saving the current editor draft when no dirty-dismiss confirmation is pending - `global.settings` opens ask settings when the editor is empty; otherwise the key is delegated to the editor as text/input - when editor has text, arrow keys and `Tab` stay in the editor so the cursor can move while typing - when editor is empty, editor-context `*WhenEmpty` navigation actions move options or tabs without requiring the editor close binding first - `@` remains a fixed file-reference affordance in editors Settings modal: - `settingsModal.close` closes settings; defaults: `Esc`, `Ctrl+C`, `?` - `settingsModal.nextOption` / `settingsModal.previousOption` move between settings; defaults: `Down`, `Up` - `settingsModal.toggle` toggles the highlighted setting and attempts to save immediately; if saving fails, the setting reverts and an error is shown; on the reset action, the same binding must be pressed twice within a short confirmation window; defaults: `Enter`, `Space` Dirty dismiss: - when `Confirm dismiss when dirty` is enabled, cancelling or dismissing a dirty ask flow requires the same action a second time - the dirty-dismiss warning stays visible until the user changes tabs in the ask flow ## Non-TUI and non-interactive modes The rich ask flow uses `ctx.ui.custom()` and opens only in TUI mode. In print, JSON, RPC, or any other non-TUI mode, the tool returns a `Needs user input: ask_user requires interactive TUI mode.` message in `content` and a cancelled result in `details` instead of opening custom UI. Validation is handled inside the tool so malformed calls produce the same structured error shape as other invalid payloads instead of relying on pre-execution schema failures. The ask flow subscribes to runtime settings updates while open. In practice, this means changing `Auto-submit when answered without notes`, `Confirm dismiss when dirty`, `Double-press review shortcuts`, `Notifications`, `Show footer hints`, resetting config to defaults, or reloading config-backed keymaps can affect the in-progress ask flow immediately instead of only future asks when the change is saved or otherwise applied in memory. Load-time migrations and invalid config handling do not rewrite, rename, or back up the config file; invalid files load defaults for the session and show a notice. `Present single-select as multi-select` is applied when an ask flow is created and does not rewrite question semantics for an already-open flow; use `main.changeQuestionType` for live per-question changes. ## Notifications When enabled, pi-ask emits one best-effort external notification per ask session after the ask UI opens and waits for input. The default title is `pi ask`; the message is `Question waiting: