@hank-warren/pi-ask-user-question 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hank Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @hank-warren/pi-ask-user-question
+
+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.1** ships one question per call, single-select, no preview pane. See
+> [the spec](../../docs/specs/pi-ask-user-question.md) §14 for the road to v0.2.
+
+## Install
+
+```bash
+pi install npm:@hank-warren/pi-ask-user-question
+```
+
+It must not be installed alongside `@juicesharp/rpiv-ask-user-question` — both
+register a tool named `ask_user_question`.
+
+## Keys
+
+| Key | Action |
+|---|---|
+| `1`–`9` | Select that option immediately |
+| `↑` / `↓` | Move the highlight |
+| `Enter` | Confirm the highlighted option |
+| `Tab` | Attach a note to your choice, then `Enter` to send both |
+| `Esc` | Decline the question (or leave note/typed-answer mode) |
+
+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.
+
+## No monkey patching
+
+Numbered options and Tab-to-comment come from `OptionSelector`, imported from
+[`@hank-warren/pi-permission-selector`](../pi-permission-selector) and rendered
+through `ctx.ui.custom()`. pi exposes no `setSelectorComponent` hook, so the
+only alternative would be patching pi's internal `ExtensionSelectorComponent` —
+which this package deliberately avoids. The trade-off: consistent behavior
+across the dialogs we own, and nothing to break when pi changes its internals.
+
+## Subagents cannot use this tool
+
+Whenever `ctx.hasUI` is false — which is every headless subagent child — the
+tool is removed from the active tool set before the agent starts. A background
+run can therefore never block waiting on a human, and a child can never route a
+question up to its supervisor. This is intentional, not a limitation; see
+[`reconcile.ts`](./reconcile.ts).
+
+## Events
+
+Other extensions can observe the questionnaire without touching this one:
+
+```ts
+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
+});
+```
+
+Channel names are immutable and payloads are append-only — see
+[`events.ts`](./events.ts) for the full stability policy.
+
+## License
+
+MIT

package/ask-user-question.ts

@@ -0,0 +1,122 @@
+/**
+ * Tool registration and execution for `ask_user_question`.
+ *
+ * The tool name is preserved verbatim from
+ * @juicesharp/rpiv-ask-user-question so session history recorded against that
+ * package replays cleanly. Only one of the two may be installed at a time.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+} from "./events.ts";
+import { QuestionnaireSession } from "./questionnaire.ts";
+import { buildResponse, buildToolResult } from "./tool/envelope.ts";
+import {
+	type AskUserParams,
+	type QuestionnaireResult,
+	QuestionParamsSchema,
+	TOOL_NAME,
+} from "./tool/schema.ts";
+import { validateParams } from "./tool/validate.ts";
+import { QuestionnaireDialog } from "./view/dialog.ts";
+
+const ERROR_NO_UI = "Error: UI not available (running in non-interactive mode)";
+
+/**
+ * Wording matters here. Without the explicit "do NOT treat this as a decline",
+ * models read a host limitation as a refusal and change course as though the
+ * user had said no. Inherited from rpiv-ask-user-question, which learned it
+ * the hard way.
+ */
+const ERROR_NO_CUSTOM_UI =
+	"Error: this client cannot render the questionnaire (custom UI is unavailable). The user never saw the questions — do NOT treat this as a decline. Ask the questions as plain chat text instead, without using this tool.";
+
+const DESCRIPTION = `Ask the user a structured question during execution. Use when you need to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take
+
+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 with Tab, 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.
+- This version accepts exactly one question per call with 2-4 options.`;
+
+function emitPrompt(pi: ExtensionAPI, params: AskUserParams): void {
+	const payload: AskUserPromptEventPayload = {
+		questions: params.questions.map((q) => ({
+			question: q.question,
+			header: q.header,
+			options: q.options.map((o) => ({ label: o.label, description: o.description })),
+		})),
+	};
+	pi.events.emit(ASK_USER_PROMPT_EVENT, payload);
+}
+
+function emitBlocked(pi: ExtensionAPI, active: boolean): void {
+	const payload: AskUserBlockedEventPayload = { active };
+	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
+}
+
+export function registerTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: TOOL_NAME,
+		label: "Ask User Question",
+		description: DESCRIPTION,
+		parameters: QuestionParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const typed = params as unknown as AskUserParams;
+
+			// Backstop only — reconcile.ts should already have stripped the tool
+			// in headless runs (subagent children must never block on a human).
+			if (!ctx.hasUI) {
+				return buildToolResult(ERROR_NO_UI, { answers: [], cancelled: true, error: "no_ui" });
+			}
+
+			const invalid = validateParams(typed);
+			if (invalid) {
+				return buildToolResult(`Error: ${invalid.message}`, {
+					answers: [],
+					cancelled: true,
+					error: "invalid_params",
+				});
+			}
+
+			const session = new QuestionnaireSession(typed);
+			emitPrompt(pi, typed);
+			emitBlocked(pi, true);
+			try {
+				const result = await ctx.ui.custom<QuestionnaireResult | null>(
+					(tui, theme, _keybindings, done) =>
+						new QuestionnaireDialog({
+							session,
+							theme,
+							done,
+							requestRender: () => tui.requestRender(),
+						}),
+					{ overlay: true },
+				);
+
+				// `custom()` resolving undefined means the host reported hasUI but
+				// cannot actually render a custom component. The user saw nothing.
+				if (result === undefined) {
+					return buildToolResult(ERROR_NO_CUSTOM_UI, {
+						answers: [],
+						cancelled: true,
+						error: "no_custom_ui",
+					});
+				}
+				return buildResponse(result, typed);
+			} finally {
+				// In `finally` so listeners are never left believing we are still
+				// blocked on a human after a throw.
+				emitBlocked(pi, false);
+			}
+		},
+	});
+}

package/events.ts

@@ -0,0 +1,49 @@
+/**
+ * Public event contract for @hank-warren/pi-ask-user-question.
+ *
+ * STABILITY POLICY — applies to every event in the `hank:*` namespace.
+ *
+ *   1. Channel names are immutable. Once shipped, never rename.
+ *   2. Payload changes are append-only. Listeners MUST tolerate unknown
+ *      fields. New fields ship as optional (`?:`).
+ *   3. Breaking changes (rename, retype, remove a field; change emission
+ *      semantics) require a NEW channel, e.g. `hank:ask-user:prompt.v2`,
+ *      with dual-emit during a deprecation window.
+ *   4. No `version` field inside payloads. Version via channel name only.
+ *   5. Payloads must be JSON-safe: primitives, arrays, plain objects. No
+ *      Set/Map/Date/class instances — payloads must survive JSON
+ *      serialization when listeners forward them across process boundaries.
+ *
+ * Intended consumers: pi-statusline (blocked-on-human indicator) and
+ * pi-auto-permissions (suppress guardian nags while a human is being asked).
+ */
+
+/** Emitted once when a questionnaire is presented. */
+export const ASK_USER_PROMPT_EVENT = "hank:ask-user:prompt" as const;
+
+export interface AskUserPromptOption {
+	label: string;
+	description: string;
+}
+
+export interface AskUserPromptQuestion {
+	question: string;
+	header: string;
+	options: ReadonlyArray<AskUserPromptOption>;
+}
+
+export interface AskUserPromptEventPayload {
+	questions: ReadonlyArray<AskUserPromptQuestion>;
+}
+
+/**
+ * Emitted while the questionnaire awaits input, and cleared with
+ * `{ active: false }` in a `finally` so listeners can always distinguish
+ * blocked-on-human from working — including when the dialog throws.
+ */
+export const ASK_USER_BLOCKED_EVENT = "hank:ask-user:blocked" as const;
+
+export interface AskUserBlockedEventPayload {
+	/** True while input is awaited; false when the wait ends (answer, cancel, or error). */
+	active: boolean;
+}

package/index.ts

@@ -0,0 +1,30 @@
+/**
+ * pi-ask-user-question — a structured questionnaire the model can put to you
+ * when it would otherwise guess.
+ *
+ * Numbered options, digit hotkeys and Tab-to-comment come from the shared
+ * `OptionSelector` in @hank-warren/pi-permission-selector, composed through
+ * `ctx.ui.custom()`. No pi internals are patched.
+ *
+ * The tool is stripped from the active tool set whenever `ctx.hasUI` is false,
+ * so headless subagent children can never block waiting on a human. See
+ * reconcile.ts.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTool } from "./ask-user-question.ts";
+import { registerReconciler } from "./reconcile.ts";
+
+export {
+	ASK_USER_BLOCKED_EVENT,
+	ASK_USER_PROMPT_EVENT,
+	type AskUserBlockedEventPayload,
+	type AskUserPromptEventPayload,
+	type AskUserPromptOption,
+	type AskUserPromptQuestion,
+} from "./events.ts";
+
+export default function askUserQuestionExtension(pi: ExtensionAPI): void {
+	registerTool(pi);
+	registerReconciler(pi);
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hank-warren/pi-ask-user-question",
+  "version": "0.2.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": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "questionnaire",
+    "prompt",
+    "tui",
+    "coding-agent"
+  ],
+  "author": "Hank Warren",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hank-warren/pi-extensions.git",
+    "directory": "packages/pi-ask-user-question"
+  },
+  "bugs": {
+    "url": "https://github.com/hank-warren/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-ask-user-question#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "ask-user-question.ts",
+    "reconcile.ts",
+    "events.ts",
+    "questionnaire.ts",
+    "tool/schema.ts",
+    "tool/validate.ts",
+    "tool/envelope.ts",
+    "view/dialog.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@hank-warren/pi-permission-selector": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}

package/questionnaire.ts

@@ -0,0 +1,111 @@
+/**
+ * Questionnaire session state — a plain mutable object, no reducer.
+ *
+ * @juicesharp/rpiv-ask-user-question spends ~1,500 lines on a Redux-style
+ * reducer plus four selector modules for this. The state here is one question
+ * index, one answer list, and a custom-answer buffer; a reducer would add
+ * indirection without adding a single testable guarantee.
+ *
+ * Pure: no pi imports, no rendering. The dialog drives it; tests drive it the
+ * same way.
+ */
+
+import {
+	type AskUserParams,
+	CUSTOM_ANSWER_LABEL,
+	CUSTOM_ANSWER_VALUE,
+	type QuestionAnswer,
+	type QuestionnaireResult,
+} from "./tool/schema.ts";
+
+export interface SelectableRow {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export class QuestionnaireSession {
+	private readonly params: AskUserParams;
+	private index = 0;
+	private readonly answers: QuestionAnswer[] = [];
+
+	constructor(params: AskUserParams) {
+		this.params = params;
+	}
+
+	get questionIndex(): number {
+		return this.index;
+	}
+
+	get total(): number {
+		return this.params.questions.length;
+	}
+
+	get current() {
+		return this.params.questions[this.index];
+	}
+
+	/** True once every question has been answered. */
+	isComplete(): boolean {
+		return this.index >= this.total;
+	}
+
+	/**
+	 * Rows for the current question: the authored options plus the appended
+	 * custom-answer sentinel. The sentinel is never an authored option — it is
+	 * added here and stripped in `recordAnswer`, which is why validation
+	 * rejects models that try to author it themselves.
+	 */
+	rows(): SelectableRow[] {
+		const question = this.current;
+		if (!question) return [];
+		const rows: SelectableRow[] = question.options.map((option) => ({
+			value: option.label,
+			label: option.label,
+			description: option.description,
+		}));
+		rows.push({ value: CUSTOM_ANSWER_VALUE, label: CUSTOM_ANSWER_LABEL });
+		return rows;
+	}
+
+	/** True when `value` is the appended custom-answer row. */
+	isCustomRow(value: string): boolean {
+		return value === CUSTOM_ANSWER_VALUE;
+	}
+
+	/**
+	 * Record an answer for the current question and advance. `custom` marks a
+	 * typed free-text answer; `notes` is the Tab-to-comment note.
+	 */
+	recordAnswer(answer: string, opts: { custom?: boolean; notes?: string } = {}): void {
+		const question = this.current;
+		if (!question) return;
+		this.answers.push({
+			questionIndex: this.index,
+			question: question.question,
+			answer,
+			custom: opts.custom === true,
+			...(opts.notes ? { notes: opts.notes } : {}),
+		});
+		this.index += 1;
+	}
+
+	/** Title line for the dialog: `Header` or `2 of 3 · Header` when multiple. */
+	title(): string {
+		const question = this.current;
+		if (!question) return "";
+		return this.total > 1
+			? `${this.index + 1} of ${this.total} · ${question.header}`
+			: question.header;
+	}
+
+	/** Successful outcome. */
+	result(): QuestionnaireResult {
+		return { answers: [...this.answers], cancelled: false };
+	}
+
+	/** Declined outcome, preserving any answers given before the cancel. */
+	cancelledResult(): QuestionnaireResult {
+		return { answers: [...this.answers], cancelled: true };
+	}
+}

package/reconcile.ts

@@ -0,0 +1,47 @@
+/**
+ * Mid-session lifecycle reconciliation for `ask_user_question`.
+ *
+ * WHY THIS EXISTS — read before changing it.
+ *
+ * Subagent children run headless (`ctx.hasUI === false`). They must never be
+ * able to block waiting on a human, and they must never route a question up to
+ * the supervisor. Stripping the tool from the active set is the mechanism that
+ * enforces that: the LLM in a headless run never sees the tool, so it cannot
+ * call it, so it cannot stall a background run forever.
+ *
+ * Do NOT "improve" this into an escalation bridge. See
+ * docs/specs/pi-ask-user-question.md §2 and §7 — no-subagent-escalation is an
+ * explicit non-goal, not an oversight.
+ *
+ * Unlike @juicesharp/rpiv-ask-user-question there is no carve-out for
+ * `ctx.mode === "rpc"`, because this package ships no RPC dialog fallback:
+ * `hasUI` is the only signal and it is honest here.
+ *
+ * The in-handler `!ctx.hasUI` guard in ask-user-question.ts stays as a
+ * one-turn backstop in case a future pi release snapshots the tool list before
+ * `before_agent_start` runs.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { TOOL_NAME } from "./tool/schema.ts";
+
+/**
+ * Strip or restore the tool to match `ctx.hasUI`. Idempotent: when the tool is
+ * already in the right state, the active set (and every sibling tool in it) is
+ * left untouched.
+ */
+export function reconcileTool(pi: ExtensionAPI, ctx: ExtensionContext): void {
+	const active = pi.getActiveTools();
+	const present = active.includes(TOOL_NAME);
+	if (!ctx.hasUI && present) {
+		pi.setActiveTools(active.filter((name) => name !== TOOL_NAME));
+	} else if (ctx.hasUI && !present) {
+		pi.setActiveTools([...active, TOOL_NAME]);
+	}
+}
+
+export function registerReconciler(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (_event, ctx) => {
+		reconcileTool(pi, ctx);
+	});
+}

package/tool/envelope.ts

@@ -0,0 +1,59 @@
+/**
+ * LLM-facing result envelope.
+ *
+ * The string shapes here are deliberately identical to
+ * @juicesharp/rpiv-ask-user-question's (`tool/response-envelope.ts`). Models
+ * have seen this format across prior sessions, and preserving it means session
+ * history replays without the assistant re-interpreting old tool results.
+ * Treat the exact wording as pinned by tests, not as incidental.
+ */
+
+import type { AskUserParams, QuestionAnswer, QuestionnaireResult } from "./schema.ts";
+
+export const DECLINE_MESSAGE = "User declined to answer questions";
+export const ENVELOPE_PREFIX = "User has answered your questions:";
+export const ENVELOPE_SUFFIX = "You can now continue with the user's answers in mind.";
+
+export interface ToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: QuestionnaireResult;
+}
+
+export function buildToolResult(text: string, details: QuestionnaireResult): ToolResult {
+	return { content: [{ type: "text" as const, text }], details };
+}
+
+/** Format a single answer as `"question"="answer"`, with an optional note. */
+export function buildAnswerSegment(a: QuestionAnswer): string {
+	const parts: string[] = [`"${a.question}"="${a.answer}"`];
+	if (a.notes && a.notes.length > 0) parts.push(`user notes: ${a.notes}`);
+	return `${parts.join(". ")}.`;
+}
+
+/**
+ * Map a questionnaire outcome to the tool envelope. Cancelled and
+ * zero-answers both collapse to DECLINE_MESSAGE so the model sees one
+ * canonical "didn't answer" signal regardless of cause.
+ */
+export function buildResponse(
+	result: QuestionnaireResult | null | undefined,
+	params: AskUserParams,
+): ToolResult {
+	if (!result || result.cancelled) {
+		return buildToolResult(DECLINE_MESSAGE, {
+			answers: result?.answers ?? [],
+			cancelled: true,
+			...(result?.error ? { error: result.error } : {}),
+		});
+	}
+
+	const segments: string[] = [];
+	for (let i = 0; i < params.questions.length; i++) {
+		const answer = result.answers.find((a) => a.questionIndex === i);
+		if (answer) segments.push(buildAnswerSegment(answer));
+	}
+	if (segments.length === 0) {
+		return buildToolResult(DECLINE_MESSAGE, { answers: result.answers, cancelled: true });
+	}
+	return buildToolResult(`${ENVELOPE_PREFIX} ${segments.join(" ")} ${ENVELOPE_SUFFIX}`, result);
+}

package/tool/schema.ts

@@ -0,0 +1,102 @@
+/**
+ * Tool parameter schema and shared types for `ask_user_question`.
+ *
+ * v0.1 scope (docs/specs/pi-ask-user-question.md §14): a SINGLE question,
+ * single-select, no preview. The schema still accepts the `questions` array
+ * shape so that v0.2 can lift the count limit without changing the wire
+ * contract the model has already learned, and so session history recorded
+ * against the array shape keeps replaying.
+ */
+
+import { Type } from "typebox";
+
+/** Canonical tool name — single source of truth, shared with reconcile.ts. */
+export const TOOL_NAME = "ask_user_question";
+
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MIN_QUESTIONS = 1;
+/** v0.1 ships single-question only; v0.2 raises this to 4. */
+export const MAX_QUESTIONS = 1;
+
+export const MAX_HEADER_LENGTH = 16;
+export const MAX_LABEL_LENGTH = 60;
+
+/**
+ * Labels the model may not author, because the dialog appends its own
+ * custom-answer row. Compared case-insensitively after trimming.
+ */
+export const RESERVED_LABELS = ["other", "type something", "type something."] as const;
+
+/** Label of the auto-appended custom-answer row. */
+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";
+
+export const OptionSchema = Type.Object({
+	label: Type.String({
+		description:
+			"MAX 60 CHARACTERS — hard limit, requests over the limit are rejected. The display text for this option that the user will see and select. Should be concise (1-5 words) and clearly describe the choice.",
+	}),
+	description: Type.String({
+		description:
+			"Explanation of what this option means or what will happen if chosen. Useful for providing context about trade-offs or implications.",
+	}),
+});
+
+export const QuestionSchema = Type.Object({
+	question: Type.String({
+		description:
+			"The complete question to ask the user. Should be clear, specific, and end with a question mark.",
+	}),
+	header: Type.String({
+		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".',
+	}),
+	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.",
+		minItems: MIN_OPTIONS,
+		maxItems: MAX_OPTIONS,
+	}),
+});
+
+export const QuestionParamsSchema = Type.Object({
+	questions: Type.Array(QuestionSchema, {
+		description: "Questions to ask the user. Exactly one question is supported in this version.",
+		minItems: MIN_QUESTIONS,
+		maxItems: MAX_QUESTIONS,
+	}),
+});
+
+export interface OptionParams {
+	label: string;
+	description: string;
+}
+
+export interface QuestionParams {
+	question: string;
+	header: string;
+	options: OptionParams[];
+}
+
+export interface AskUserParams {
+	questions: QuestionParams[];
+}
+
+/** One answered question. `custom` marks a typed free-text answer. */
+export interface QuestionAnswer {
+	questionIndex: number;
+	question: string;
+	answer: string;
+	custom: boolean;
+	/** Trimmed Tab-to-comment note, when the user attached one. */
+	notes?: string;
+}
+
+export interface QuestionnaireResult {
+	answers: QuestionAnswer[];
+	cancelled: boolean;
+	/** Set only on infrastructure failures, never on a user decline. */
+	error?: "no_ui" | "no_custom_ui" | "invalid_params";
+}

package/tool/validate.ts

@@ -0,0 +1,110 @@
+/**
+ * Parameter validation for `ask_user_question`. Pure — no pi imports, no I/O.
+ *
+ * typebox enforces structure (array bounds, required fields, types). This
+ * module enforces the semantic rules typebox cannot express: length caps that
+ * the model routinely overshoots, reserved sentinel labels, and duplicates.
+ *
+ * Violations return a structured error that becomes a normal tool error the
+ * model can read and retry against — never a thrown exception, which would
+ * surface as an opaque crash.
+ */
+
+import {
+	type AskUserParams,
+	MAX_HEADER_LENGTH,
+	MAX_LABEL_LENGTH,
+	MAX_OPTIONS,
+	MAX_QUESTIONS,
+	MIN_OPTIONS,
+	MIN_QUESTIONS,
+	RESERVED_LABELS,
+} from "./schema.ts";
+
+export type ValidationCode =
+	| "bad_question_count"
+	| "bad_option_count"
+	| "header_too_long"
+	| "label_too_long"
+	| "reserved_label"
+	| "duplicate_label"
+	| "empty_question";
+
+export interface ValidationError {
+	code: ValidationCode;
+	message: string;
+}
+
+const isReserved = (label: string): boolean =>
+	(RESERVED_LABELS as readonly string[]).includes(label.trim().toLowerCase());
+
+/**
+ * Validate a params object. Returns the first violation, or undefined when the
+ * questionnaire is well-formed. First-violation-only is deliberate: the model
+ * fixes one thing per retry, and a wall of errors invites it to rewrite the
+ * whole call rather than patch the offending field.
+ */
+export function validateParams(params: AskUserParams): ValidationError | undefined {
+	const questions = params.questions;
+	if (!Array.isArray(questions) || questions.length < MIN_QUESTIONS || questions.length > MAX_QUESTIONS) {
+		return {
+			code: "bad_question_count",
+			message:
+				MAX_QUESTIONS === 1
+					? `This version supports exactly ${MAX_QUESTIONS} question per call; received ${questions?.length ?? 0}. Ask the most important question first, then follow up.`
+					: `questions must contain ${MIN_QUESTIONS}-${MAX_QUESTIONS} entries; received ${questions?.length ?? 0}.`,
+		};
+	}
+
+	for (let i = 0; i < questions.length; i++) {
+		const q = questions[i];
+		const where = `questions[${i}]`;
+
+		if (!q.question?.trim()) {
+			return { code: "empty_question", message: `${where}.question must not be empty.` };
+		}
+		if (!q.header?.trim()) {
+			return { code: "empty_question", message: `${where}.header must not be empty.` };
+		}
+		if (q.header.length > MAX_HEADER_LENGTH) {
+			return {
+				code: "header_too_long",
+				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) {
+			return {
+				code: "bad_option_count",
+				message: `${where}.options must contain ${MIN_OPTIONS}-${MAX_OPTIONS} entries; received ${q.options?.length ?? 0}.`,
+			};
+		}
+
+		const seen = new Set<string>();
+		for (let j = 0; j < q.options.length; j++) {
+			const option = q.options[j];
+			const at = `${where}.options[${j}]`;
+			if (option.label.length > MAX_LABEL_LENGTH) {
+				return {
+					code: "label_too_long",
+					message: `${at}.label is ${option.label.length} characters; the hard limit is ${MAX_LABEL_LENGTH}.`,
+				};
+			}
+			if (isReserved(option.label)) {
+				return {
+					code: "reserved_label",
+					message: `${at}.label "${option.label}" is reserved. A "Type something." row is appended automatically — do not author it.`,
+				};
+			}
+			const key = option.label.trim().toLowerCase();
+			if (seen.has(key)) {
+				return {
+					code: "duplicate_label",
+					message: `${at}.label "${option.label}" duplicates an earlier option in the same question. Options must be distinct.`,
+				};
+			}
+			seen.add(key);
+		}
+	}
+
+	return undefined;
+}

package/view/dialog.ts

@@ -0,0 +1,176 @@
+/**
+ * The questionnaire dialog: a pi-tui component driven by QuestionnaireSession
+ * and rendered through `ctx.ui.custom()`.
+ *
+ * NO MONKEY PATCHING. The numbered options, digit hotkeys and Tab-to-comment
+ * come from `OptionSelector`, imported from the PUBLISHED sibling package
+ * `@hank-warren/pi-permission-selector` (plain `dependencies`, never
+ * `bundledDependencies` — AGENTS.md §Structure). That is the whole point of
+ * the design: shared behavior by composition, not by patching pi internals.
+ * See docs/specs/pi-ask-user-question.md §9.
+ *
+ * v0.1 renders one question. The component is written against the session
+ * rather than a single question so v0.2 can advance in place without a
+ * rewrite.
+ */
+
+import { OptionSelector, type SelectorOption } from "@hank-warren/pi-permission-selector/selector.ts";
+import type { QuestionnaireSession } from "../questionnaire.ts";
+import type { QuestionnaireResult } from "../tool/schema.ts";
+
+/** Structural subset of pi's Theme used here; keeps the view unit-testable. */
+export interface DialogTheme {
+	fg(role: string, text: string): string;
+}
+
+export interface DialogOptions {
+	session: QuestionnaireSession;
+	theme?: DialogTheme;
+	/** Called exactly once with the final outcome. */
+	done(result: QuestionnaireResult): void;
+	requestRender?(): void;
+}
+
+/**
+ * Two-mode dialog: option selection, and (after choosing "Type something.")
+ * free-text entry. Custom-answer entry is handled here rather than by mounting
+ * pi-tui's `Input`, because `Input` owns its own key handling and would fight
+ * the selector for Esc and Enter.
+ */
+export class QuestionnaireDialog {
+	private readonly opts: DialogOptions;
+	private selector: OptionSelector;
+	private customText: string | undefined;
+	private pendingNotes: string | undefined;
+	private finished = false;
+
+	constructor(opts: DialogOptions) {
+		this.opts = opts;
+		this.selector = this.buildSelector();
+	}
+
+	private get session() {
+		return this.opts.session;
+	}
+
+	private repaint(): void {
+		this.opts.requestRender?.();
+	}
+
+	private buildSelector(): OptionSelector {
+		const session = this.session;
+		const options: SelectorOption[] = session.rows().map((row) => ({
+			value: row.value,
+			label: row.label,
+			description: row.description,
+		}));
+
+		return new OptionSelector({
+			title: `${session.title()}\n\n${session.current?.question ?? ""}`,
+			options,
+			theme: this.opts.theme,
+			onSelect: (option, comment) => {
+				if (session.isCustomRow(option.value)) {
+					// Enter free-text mode. The note typed on the sentinel row is
+					// carried across so a user who commented and then chose to type
+					// a custom answer does not silently lose it.
+					this.pendingNotes = comment;
+					this.customText = "";
+					this.repaint();
+					return;
+				}
+				session.recordAnswer(option.value, { notes: comment });
+				this.advance();
+			},
+			onCancel: () => this.finish(session.cancelledResult()),
+			requestRender: () => this.repaint(),
+		});
+	}
+
+	private advance(): void {
+		if (this.session.isComplete()) {
+			this.finish(this.session.result());
+			return;
+		}
+		// v0.2: multi-question calls rebind the selector to the next question.
+		this.selector = this.buildSelector();
+		this.repaint();
+	}
+
+	private finish(result: QuestionnaireResult): void {
+		if (this.finished) return;
+		this.finished = true;
+		this.opts.done(result);
+	}
+
+	/** True while the free-text custom-answer editor is open. */
+	isTypingCustom(): boolean {
+		return this.customText !== undefined;
+	}
+
+	invalidate(): void {
+		this.selector.invalidate();
+	}
+
+	render(width: number): string[] {
+		if (this.customText !== undefined) {
+			const session = this.session;
+			return [
+				session.title(),
+				"",
+				session.current?.question ?? "",
+				"",
+				`  ${this.customText}▌`,
+				"",
+				this.dim("  enter submit · esc back to options"),
+			];
+		}
+		return this.selector.render(width);
+	}
+
+	private dim(text: string): string {
+		return this.opts.theme ? this.opts.theme.fg("dim", text) : `\x1b[2m${text}\x1b[0m`;
+	}
+
+	handleInput(keyData: string): void {
+		if (this.customText === undefined) {
+			this.selector.handleInput(keyData);
+			return;
+		}
+		// Free-text mode. Esc unwinds to the option list rather than cancelling
+		// the whole dialog — one Esc should never discard more than one layer.
+		if (keyData === "\x1b") {
+			this.customText = undefined;
+			this.pendingNotes = undefined;
+			this.repaint();
+			return;
+		}
+		if (keyData === "\r" || keyData === "\n") {
+			const text = this.customText.trim();
+			if (text.length === 0) return; // Empty custom answers are not submittable.
+			this.session.recordAnswer(text, { custom: true, notes: this.pendingNotes });
+			this.customText = undefined;
+			this.pendingNotes = undefined;
+			this.advance();
+			return;
+		}
+		if (keyData === "\x7f" || keyData === "\b") {
+			this.customText = this.customText.slice(0, -1);
+			this.repaint();
+			return;
+		}
+		if (isPrintableChunk(keyData)) {
+			this.customText += keyData;
+			this.repaint();
+		}
+	}
+}
+
+function isPrintableChunk(keyData: string): boolean {
+	if (keyData.length === 0) return false;
+	for (const char of keyData) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code < 0x20 || code === 0x7f) return false;
+	}
+	return true;
+}