@hank-warren/pi-ask-user-question 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @hank-warren/pi-ask-user-question
 
+## 0.5.0
+
+### Minor Changes
+
+- 385212b: add `multiSelect` questions
+
+  A question with `multiSelect: true` renders as checkboxes for the cases where
+  several answers hold at once ("which of these packages should change", "which
+  checks to run before merging"). Space or a digit toggles a row, Enter submits
+  the checked options, and the answer comes back as the chosen labels joined with
+  `", "` — `answer` stays a plain string, so the envelope and every consumer of
+  `details.answers` are unchanged. The parts are also available as
+  `answers[].selected`.
+
+  Multi-select questions may carry 2-6 options instead of 2-4; the
+  `bad_option_count` message now names the mode and its range. Previews work on
+  multi-select options (the pane keys off the highlighted row), though
+  multi-select answers carry no `preview` into the envelope.
+
+  Checking the appended `Type something.` row opens the free-text field with the
+  other ticks preserved, and the typed value is **appended** to them rather than
+  replacing them, so `pi-stats, pi-plan-mode, and also the docs site` is one
+  answer. Such an answer records `custom: true`.
+
+  `hank:ask-user:prompt` payloads gain an optional `multiSelect` field, emitted
+  only when true — append-only, no new channel.
+
+### Patch Changes
+
+- e05dfb5: render the questionnaire in the editor area instead of as an overlay
+
+  An overlay is composited over the bottom rows of the viewport, so the transcript
+  underneath the dialog was unreachable: you are already scrolled to the bottom of
+  the session and there is nothing left to scroll. Several lines of chat sat
+  behind the box with no way to read them while answering.
+
+  The dialog now mounts in the editor area — where `ctx.ui.select` renders pi's
+  own selectors, and where `pi-auto-permissions` already puts its approval prompt.
+  In the normal document flow the transcript is pushed up rather than covered, so
+  every line stays readable in the terminal's own scrollback.
+
+  Nothing else changes: same box, same keys, same width behavior. The input dock
+  is replaced for the duration of the questionnaire and restored when it closes.
+
+- Updated dependencies [385212b]
+  - @hank-warren/pi-permission-selector@1.1.0
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -4,8 +4,8 @@ A structured questionnaire the model can put to you when it would otherwise
 guess. Instead of a free-form "which do you prefer?" in chat, you get a dialog
 with numbered options, digit hotkeys, a typed-answer escape, and Tab-to-comment.
 
-> **v0.3** ships 1-4 questions per call as cycleable tabs, single-select, with
-> an optional preview pane. See
+> **v0.5** ships 1-4 questions per call as cycleable tabs, single- or
+> multi-select, with an optional preview pane. See
 > [the spec](../../docs/specs/pi-ask-user-question.md) §14.
 
 ## Install
@@ -21,9 +21,10 @@ register a tool named `ask_user_question`.
 
 | Key | Action |
 |---|---|
-| `1`–`9` | Select that option immediately |
+| `1`–`9` | Select that option immediately (toggle it, on a multi-select question) |
+| `Space` | Toggle the highlighted option (multi-select only) |
 | `↑` / `↓` | Move the highlight |
-| `Enter` | Confirm the highlighted option |
+| `Enter` | Confirm the highlighted option, or submit the checked ones |
 | `n` | Attach a note to your choice, then `Enter` to send both |
 | `Tab` / `→` | Next question |
 | `Shift+Tab` / `←` | Previous question |
@@ -34,6 +35,33 @@ answering one jumps to the next unanswered question, and the call returns once
 every question has an answer. Cycling back and re-answering replaces that
 question's answer rather than recording a second one.
 
+## Multi-select
+
+A question with `multiSelect: true` renders as checkboxes, for the cases where
+several answers hold at once — "which of these packages should change", "which
+checks to run before merging":
+
+```
+→ [x] 1. pi-stats
+  [ ] 2. pi-statusline
+  [x] 3. pi-plan-mode
+  [ ] 4. Type something.
+  space/1-9 toggle · ↑↓ move · enter confirm (2) · n add note · esc cancel
+```
+
+- Space and the digit hotkeys both toggle; a digit no longer commits, so one
+  keystroke cannot end the question early.
+- Enter submits the checked options in list order and is inert until at least
+  one is checked — the count in the hint is the tell.
+- The answer comes back as the chosen labels joined with `, `.
+- Multi-select questions may carry 2-6 options; single-select stays at 2-4.
+- Checking **`Type something.`** alongside other options opens the free-text
+  field with those ticks preserved, and the typed value is **appended** to them
+  rather than replacing them, so `pi-stats, pi-plan-mode, and also the docs
+  site` is a single answer.
+
+Mutually exclusive choices stay single-select; that is still the default.
+
 ## Previews
 
 An option may carry a `preview` field — markdown shown in a pane below the
@@ -51,6 +79,17 @@ Every question gets an appended **`Type something.`** row for a free-text
 answer. The model is not allowed to author that row itself — reserved labels
 are rejected at runtime.
 
+## Where the dialog renders
+
+The questionnaire renders **in the editor area**, exactly where `ctx.ui.select`
+puts pi's own selectors — not as an overlay floating over the transcript.
+
+An overlay is composited over the bottom rows of the viewport, so the chat lines
+underneath it are unreachable: you are already scrolled to the bottom and there
+is nothing left to scroll. Rendering in the document flow pushes the transcript
+up instead of covering it, so every line stays readable in the terminal's own
+scrollback while you answer.
+
 ## No monkey patching
 
 Numbered options and Tab-to-comment come from `OptionSelector`, imported from
@@ -77,7 +116,7 @@ pi.events.on("hank:ask-user:blocked", ({ active }) => {
   // active === true while a human is being asked
 });
 pi.events.on("hank:ask-user:prompt", ({ questions }) => {
-  // questions[].question / .header / .options[].label
+  // questions[].question / .header / .multiSelect / .options[].label
 });
 ```
 

package/ask-user-question.ts

@@ -44,16 +44,21 @@ const DESCRIPTION = `Ask the user one or more structured questions during execut
 Preview feature:
 Use the optional \`preview\` field on an option when presenting a concrete artifact the user needs to compare visually: an ASCII mockup, a code snippet, a diagram or configuration variation. It renders as markdown in a pane below the options while that option is highlighted. Do not use it for simple preference questions where the label and description already say enough.
 
+Multi-select:
+Set \`multiSelect: true\` on a question when several answers can hold at once — "which of these packages should change", "which checks to run before merging". Keep mutually exclusive choices single-select; that is still the default and the common case. A multi-select question may have 2-6 options instead of 2-4, renders as checkboxes, and the user toggles rows with Space or a digit and confirms with Enter. The answer comes back as the chosen labels joined with ", ", and the user may add a typed value to the checked ones through the "Type something." row. \`preview\` works on multi-select options too.
+
 Usage notes:
 - The user can pick an option with the number keys, type a custom answer via the automatically appended "Type something." row, attach a note to their choice by pressing n, or press Esc to decline. Do NOT author "Other" or "Type something." labels yourself — reserved labels are rejected at runtime.
 - If you recommend a specific option, make it the first option and add "(Recommended)" at the end of the label.
-- Ask 1-4 questions per call, each with 2-4 options. Multiple questions render as tabs the user cycles with Tab; every question must be answered before the call returns. Group questions that belong to one decision rather than asking them in separate calls, but do not pad a single decision into several questions.`;
+- Ask 1-4 questions per call, each with 2-4 options (2-6 when \`multiSelect\` is true). Multiple questions render as tabs the user cycles with Tab; every question must be answered before the call returns. Group questions that belong to one decision rather than asking them in separate calls, but do not pad a single decision into several questions.`;
 
 function emitPrompt(pi: ExtensionAPI, params: AskUserParams): void {
 	const payload: AskUserPromptEventPayload = {
 		questions: params.questions.map((q) => ({
 			question: q.question,
 			header: q.header,
+			// Emitted only when true — append-only payload policy (events.ts).
+			...(q.multiSelect ? { multiSelect: true } : {}),
 			options: q.options.map((o) => ({ label: o.label, description: o.description })),
 		})),
 	};
@@ -94,6 +99,16 @@ export function registerTool(pi: ExtensionAPI): void {
 			emitPrompt(pi, typed);
 			emitBlocked(pi, true);
 			try {
+				// NOT an overlay. An overlay is composited over the bottom rows of the
+				// viewport, so the transcript underneath it is unreachable: the user is
+				// already scrolled to the bottom and there is nothing left to scroll.
+				// Rendering in the editor area instead puts the dialog in the normal
+				// document flow — the transcript is pushed up rather than covered, and
+				// every line of it stays reachable in the terminal's own scrollback.
+				//
+				// This is also where `ctx.ui.select` renders, and where
+				// pi-auto-permissions' approval prompt already puts `OptionSelector`.
+				// pi restores the input editor when `done` fires.
 				const result = await ctx.ui.custom<QuestionnaireResult | null>(
 					(tui, theme, _keybindings, done) =>
 						new QuestionnaireDialog({
@@ -105,24 +120,6 @@ export function registerTool(pi: ExtensionAPI): void {
 							done,
 							requestRender: () => tui.requestRender(),
 						}),
-					{
-						overlay: true,
-						// Bottom-anchored and full width, so the questionnaire sits
-						// directly above the input dock instead of floating over the
-						// middle of the transcript. Mirrors the geometry
-						// @juicesharp/rpiv-ask-user-question used.
-						//
-						// width MUST stay "100%" in step with the dialog rendering full
-						// width: pi composites only the columns the component emits, so
-						// a narrower box inside a full-width overlay region would let
-						// the transcript show through beside it.
-						overlayOptions: {
-							anchor: "bottom-center",
-							width: "100%",
-							maxHeight: "100%",
-							margin: { left: 0, right: 0, bottom: 0 },
-						},
-					},
 				);
 
 				// `custom()` resolving undefined means the host reported hasUI but

package/events.ts

@@ -29,6 +29,12 @@ export interface AskUserPromptOption {
 export interface AskUserPromptQuestion {
 	question: string;
 	header: string;
+	/**
+	 * True when the question renders as checkboxes. Emitted only when true, so
+	 * existing listeners see the payload they already knew (policy rule 2:
+	 * append-only, new fields optional).
+	 */
+	multiSelect?: boolean;
 	options: ReadonlyArray<AskUserPromptOption>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-ask-user-question",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Structured questionnaire tool for Pi with numbered options, digit hotkeys and Tab-to-comment, composed from the shared permission-selector component.",
   "type": "module",
   "keywords": [
@@ -46,7 +46,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@hank-warren/pi-permission-selector": "^1.0.1"
+    "@hank-warren/pi-permission-selector": "^1.1.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/questionnaire.ts

@@ -20,6 +20,7 @@ import {
 	type AskUserParams,
 	CUSTOM_ANSWER_LABEL,
 	CUSTOM_ANSWER_VALUE,
+	MULTI_SELECT_JOIN,
 	type QuestionAnswer,
 	type QuestionnaireResult,
 } from "./tool/schema.ts";
@@ -122,6 +123,35 @@ export class QuestionnaireSession {
 		return value === CUSTOM_ANSWER_VALUE;
 	}
 
+	/** True when the current question renders as checkboxes. */
+	isMultiSelect(): boolean {
+		return this.current?.multiSelect === true;
+	}
+
+	/**
+	 * Record (or replace) a multi-select answer.
+	 *
+	 * `answer` is the labels joined with `", "` — spec §5.4 — so `tool/envelope.ts`
+	 * and every consumer of `details.answers` stay unchanged; `selected` carries
+	 * the parts for anyone who wants them structured. `custom` means "a typed
+	 * value is among the parts", not "the whole answer is free text".
+	 *
+	 * No preview is attached even when checked options declare one: concatenating
+	 * several previews into one answer string is noise the model authored itself.
+	 */
+	recordMultiAnswer(labels: string[], opts: { custom?: boolean; notes?: string } = {}): void {
+		const question = this.current;
+		if (!question || labels.length === 0) return;
+		this.answers[this.index] = {
+			questionIndex: this.index,
+			question: question.question,
+			answer: labels.join(MULTI_SELECT_JOIN),
+			custom: opts.custom === true,
+			selected: [...labels],
+			...(opts.notes ? { notes: opts.notes } : {}),
+		};
+	}
+
 	/**
 	 * Record (or replace) the answer for the current question. Replacement is
 	 * the point: cycling back to a question and picking again must not leave

package/tool/schema.ts

@@ -2,8 +2,8 @@
  * Tool parameter schema and shared types for `ask_user_question`.
  *
  * v0.2 scope (docs/specs/pi-ask-user-question.md §14): up to four questions,
- * single-select, no preview. Questions render as tabs the user cycles with
- * Tab / Shift+Tab.
+ * single- or multi-select, optional per-option preview. Questions render as
+ * tabs the user cycles with Tab / Shift+Tab.
  */
 
 import { Type } from "typebox";
@@ -13,9 +13,19 @@ export const TOOL_NAME = "ask_user_question";
 
 export const MIN_OPTIONS = 2;
 export const MAX_OPTIONS = 4;
+/**
+ * Multi-select questions get a larger cap. Checkboxes are a shortlist UI, not a
+ * pick-one UI, so six is where a list stops fitting comfortably above the input
+ * dock — not where it stops being a decision.
+ */
+export const MAX_MULTI_OPTIONS = 6;
 export const MIN_QUESTIONS = 1;
 export const MAX_QUESTIONS = 4;
 
+/** Upper bound on authored options for a question, by mode. */
+export const maxOptionsFor = (multiSelect?: boolean): number =>
+	multiSelect ? MAX_MULTI_OPTIONS : MAX_OPTIONS;
+
 export const MAX_HEADER_LENGTH = 16;
 export const MAX_LABEL_LENGTH = 60;
 
@@ -30,6 +40,9 @@ export const CUSTOM_ANSWER_LABEL = "Type something.";
 /** Sentinel `value` for that row; never collides with a real option value. */
 export const CUSTOM_ANSWER_VALUE = "\u0000custom-answer";
 
+/** Separator joining a multi-select answer's labels into `answer` (spec §5.4). */
+export const MULTI_SELECT_JOIN = ", ";
+
 export const OptionSchema = Type.Object({
 	label: Type.String({
 		description:
@@ -56,11 +69,17 @@ export const QuestionSchema = Type.Object({
 		description:
 			'MAX 16 CHARACTERS — hard limit, requests over the limit are rejected. Very short chip/tag shown next to the question. Examples: "Auth method", "Library", "Approach".',
 	}),
+	multiSelect: Type.Optional(
+		Type.Boolean({
+			description:
+				"Render this question as checkboxes so the user can pick more than one option. Use it when several answers can hold at once (\"which of these should change\", \"which checks to run before merging\"); keep mutually exclusive choices single-select. Multi-select questions may have 2-6 options instead of 2-4. The user toggles rows with Space or a digit and confirms with Enter, and the answer comes back as the chosen labels joined with \", \".",
+		}),
+	),
 	options: Type.Array(OptionSchema, {
 		description:
-			"The available choices for this question. Must have 2-4 options, each a distinct, mutually exclusive choice. The 'Type something.' row is appended automatically — do NOT author it.",
+			"The available choices for this question. Must have 2-4 options (2-6 when multiSelect is true), each a distinct choice; without multiSelect they must also be mutually exclusive. The 'Type something.' row is appended automatically — do NOT author it.",
 		minItems: MIN_OPTIONS,
-		maxItems: MAX_OPTIONS,
+		maxItems: MAX_MULTI_OPTIONS,
 	}),
 });
 
@@ -82,6 +101,8 @@ export interface OptionParams {
 export interface QuestionParams {
 	question: string;
 	header: string;
+	/** Checkbox mode: the user may check several options. Default false. */
+	multiSelect?: boolean;
 	options: OptionParams[];
 }
 
@@ -99,6 +120,12 @@ export interface QuestionAnswer {
 	notes?: string;
 	/** Preview text of the chosen option, when it carried one. */
 	preview?: string;
+	/**
+	 * The individual chosen labels, present only on multi-select answers.
+	 * `answer` holds the same list joined with `", "`, so every existing
+	 * consumer of `answer` — including the envelope — is unchanged.
+	 */
+	selected?: string[];
 }
 
 export interface QuestionnaireResult {

package/tool/validate.ts

@@ -14,8 +14,8 @@ import {
 	type AskUserParams,
 	MAX_HEADER_LENGTH,
 	MAX_LABEL_LENGTH,
-	MAX_OPTIONS,
 	MAX_QUESTIONS,
+	maxOptionsFor,
 	MIN_OPTIONS,
 	MIN_QUESTIONS,
 	RESERVED_LABELS,
@@ -69,10 +69,14 @@ export function validateParams(params: AskUserParams): ValidationError | undefin
 				message: `${where}.header is ${q.header.length} characters; the hard limit is ${MAX_HEADER_LENGTH}. Shorten it to a chip-sized tag.`,
 			};
 		}
-		if (!Array.isArray(q.options) || q.options.length < MIN_OPTIONS || q.options.length > MAX_OPTIONS) {
+		// The cap is mode-aware: checkboxes are a shortlist UI and get six, a
+		// pick-one question still gets four.
+		const maxOptions = maxOptionsFor(q.multiSelect);
+		if (!Array.isArray(q.options) || q.options.length < MIN_OPTIONS || q.options.length > maxOptions) {
+			const mode = q.multiSelect ? "multi-select" : "single-select";
 			return {
 				code: "bad_option_count",
-				message: `${where}.options must contain ${MIN_OPTIONS}-${MAX_OPTIONS} entries; received ${q.options?.length ?? 0}.`,
+				message: `${where}.options must contain ${MIN_OPTIONS}-${maxOptions} entries for a ${mode} question; received ${q.options?.length ?? 0}.`,
 			};
 		}
 

package/view/dialog.ts

@@ -10,9 +10,10 @@
  *
  * KEY MAP (matches @juicesharp/rpiv-ask-user-question):
  *
- *   1-9         select an option
+ *   1-9         select an option (toggle it, on a multiSelect question)
+ *   space       toggle the highlighted option    (multiSelect only)
  *   ↑ / ↓       move the highlight
- *   enter       confirm the highlight
+ *   enter       confirm the highlight, or submit the checked options
  *   n           open the note editor for the highlighted option
  *   tab / →     next question      shift+tab / ←   previous question
  *   esc         decline the questionnaire
@@ -28,9 +29,10 @@
  *    shared predicates in `.../keys.ts`. Under the Kitty keyboard protocol
  *    (Ghostty's default) Esc is `\x1b[27u`, not `\x1b`, so raw comparisons
  *    trapped the user in the custom-answer field with no way out.
- * 2. ALWAYS pad rendered lines to the full overlay width. pi composites an
- *    overlay onto the chat line by line and only overwrites the columns the
- *    overlay actually emits; short lines let chat text show through.
+ * 2. ALWAYS pad rendered lines to the full width. The dialog is a rectangle,
+ *    and a short line leaves whatever the renderer last drew in those columns
+ *    visible inside the box — which is exactly how it looked when this was an
+ *    overlay composited onto the chat.
  * 3. ALWAYS clamp lines to the inner width. A single over-long line breaks the
  *    right border and spills into the transcript, so `render` truncates as a
  *    last-resort invariant no matter what any content source produces.
@@ -71,9 +73,8 @@ export interface DialogOptions {
 	done(result: QuestionnaireResult): void;
 	requestRender?(): void;
 	/**
-	 * Optional width cap. Unset means fill the overlay, which is what the
-	 * bottom-anchored `width: "100%"` overlay wants: a narrower box would let
-	 * the transcript show through to its right.
+	 * Optional width cap. Unset means fill the width the host gives us, which is
+	 * what the full-width editor area wants.
 	 */
 	maxWidth?: number;
 	/**
@@ -99,6 +100,13 @@ interface TabState {
 	selector: OptionSelector;
 	customText?: string;
 	pendingNotes?: string;
+	/**
+	 * Labels checked alongside the sentinel row on a multi-select question, held
+	 * while the free-text field is open. Committed text is APPENDED to these
+	 * rather than replacing them (amends spec §5.3), so "A, B, and also …" is
+	 * one answer. Undefined means the field belongs to a single-select question.
+	 */
+	pendingSelected?: string[];
 }
 
 export class QuestionnaireDialog {
@@ -137,6 +145,8 @@ export class QuestionnaireDialog {
 			label: row.label,
 			description: row.description,
 		}));
+		// Read the mode while the cursor is still parked on this tab's question.
+		const multiSelect = session.isMultiSelect();
 		previous(restore);
 
 		return new OptionSelector({
@@ -146,6 +156,21 @@ export class QuestionnaireDialog {
 			// left unconsumed by the selector so this dialog can intercept it.
 			commentTrigger: isNoteKey,
 			commentKeyHint: NOTE_KEY,
+			multiSelect,
+			onSubmit: (checked, comment) => {
+				session.goTo(index);
+				const labels = checked.filter((o) => !session.isCustomRow(o.value)).map((o) => o.label);
+				if (checked.some((o) => session.isCustomRow(o.value))) {
+					// Free-text mode with the other ticks held; Esc restores them.
+					this.tabs[index].pendingNotes = comment;
+					this.tabs[index].pendingSelected = labels;
+					this.tabs[index].customText = "";
+					this.repaint();
+					return;
+				}
+				session.recordMultiAnswer(labels, { notes: comment });
+				this.afterAnswer();
+			},
 			onSelect: (option, comment) => {
 				session.goTo(index);
 				if (session.isCustomRow(option.value)) {
@@ -309,8 +334,8 @@ export class QuestionnaireDialog {
 			// Invariant (3): never let a line break the right border, whatever
 			// produced it.
 			const line = visibleWidth(raw) > inner ? truncateToWidth(raw, inner) : raw;
-			// Invariant (2): pad to the full inner width, or pi's overlay
-			// compositing leaves chat text visible to the right of each line.
+			// Invariant (2): pad to the full inner width, so every row of the box is
+			// the same rectangle and nothing shows through beside a short line.
 			const pad = Math.max(0, inner - visibleWidth(line));
 			out.push(`${border("│")} ${line}${" ".repeat(pad)} ${border("│")}`);
 		}
@@ -347,17 +372,30 @@ export class QuestionnaireDialog {
 		// rule 1. Esc unwinds to the option list rather than cancelling the
 		// dialog: one Esc never discards more than one layer.
 		if (isEscapeKey(keyData)) {
+			// Back to the option list. The selector still holds every tick, so a
+			// multi-select question is exactly as the user left it.
 			tab.customText = undefined;
 			tab.pendingNotes = undefined;
+			tab.pendingSelected = undefined;
 			this.repaint();
 			return;
 		}
 		if (isEnterKey(keyData)) {
 			const text = tab.customText.trim();
 			if (text.length === 0) return; // Empty custom answers are not submittable.
-			this.session.recordAnswer(text, { custom: true, notes: tab.pendingNotes });
+			if (tab.pendingSelected !== undefined) {
+				// Append, never replace: the ticks the user left standing are part of
+				// the answer, and the typed value goes last.
+				this.session.recordMultiAnswer([...tab.pendingSelected, text], {
+					custom: true,
+					notes: tab.pendingNotes,
+				});
+			} else {
+				this.session.recordAnswer(text, { custom: true, notes: tab.pendingNotes });
+			}
 			tab.customText = undefined;
 			tab.pendingNotes = undefined;
+			tab.pendingSelected = undefined;
 			this.afterAnswer();
 			return;
 		}