@black942026/pi-ask-user 0.1.2 → 0.1.3

package/README.md

@@ -1,7 +1,7 @@
 # @black942026/pi-ask-user
 
 A Pi extension for asking structured questions through interactive terminal
-or native input dialogs. Supports single-choice, multiple-choice, free-text,
+or native dialogs. Supports single-choice, multiple-choice, free-text,
 boolean, and flat typed form answers, with configurable timeouts and cancellation.
 
 Install the package to add the **`ask_user`** tool to Pi. Other extensions can
@@ -18,7 +18,7 @@ is created:
 | Route | Runs when | The user sees |
 | --- | --- | --- |
 | `custom` | the host is a real Pi TUI with a bound renderer | a tabbed terminal dialog: options, boolean controls, forms, text input, and Markdown previews |
-| `native` | `ctx.hasUI` with a callable `ctx.ui.input` (TUI, RPC/ACP) | native dialogs, one logical question at a time; form fields are sequential dialogs |
+| `native` | `ctx.hasUI` with a callable `ctx.ui.input` (TUI, RPC/ACP) | native dialogs, one logical question at a time; with `allowFreeText: false`, single/bool use `ctx.ui.select`; multi/text keep input boxes; form fields are sequential dialogs |
 
 Only these two routes exist, and the route belongs to the host: it is configured
 or probed when the host is created, never per request.
@@ -57,6 +57,7 @@ The registered tool name is exactly **`ask_user`**.
 | `fields[].default` | `(boolean \| string \| string[])?` | boolean, selected label, selected-label array, or text according to field kind |
 | `questions[].id` | `string?` | non-empty; generated as `q1`, `q2`, … when omitted |
 | `header` | `string?` | heading above the questionnaire |
+| `allowFreeText` | `boolean?` | default `true`; `false` removes supplemental/free-text answers on single/multi questions; native single/bool (including form fields) use selectors while multi/text keep input boxes |
 | `displayMode` | `"overlay" \| "inline"?` | custom route only; default `overlay`; a user-configured preference overrides it |
 | `timeoutPerQuestionMs` | `number?` | base timeout per question; default `60000`; a user-configured preference overrides it |
 
@@ -67,6 +68,37 @@ error. An explicit legacy `kind: "input"` keeps its existing behavior: supplied
 options are validated, then dropped. Duplicate option labels are de-duplicated
 and reported in `warnings`.
 
+### Disable supplemental text
+
+Set top-level `allowFreeText: false` to hide the custom UI's bottom extra input
+on single/multi questions and require option selections. Regular `input`
+questions and form text fields remain editable. Choice defaults must match an
+option label when supplemental text is disabled.
+
+```json
+{
+  "allowFreeText": false,
+  "questions": [
+    { "title": "Environment", "kind": "single", "options": [{ "label": "dev" }, { "label": "prod" }] }
+  ]
+}
+```
+
+On the native route with this flag:
+
+- Single-choice questions/fields use `ctx.ui.select`, returning option labels.
+- Boolean questions/fields use a True/False selector. We deliberately avoid
+  `ctx.ui.confirm`: Pi returns `false` both for a negative answer and dismissal,
+  so a selector is necessary to preserve cancellation semantics.
+- Multi-choice questions/fields **still use a text box**, accepting numbers such
+  as `1,3`; standalone multi questions reject prose and `| note`.
+- Text questions/fields keep their text boxes.
+- Selectors provide explicit default/skip actions where applicable. A host
+  without `ui.select` refuses requests that need it rather than falling back
+  to text input. The shared deadline and abort signal apply to every dialog.
+
+Omitting the flag (or setting `true`) preserves the native input-box behavior.
+
 Forms are flat. Field names cannot contain dots, brackets, spaces, or path-like
 syntax, and `__proto__`, `constructor`, and `prototype` are rejected. Names must
 be unique. Defaults are checked against the field kind and, for choice fields,
@@ -338,16 +370,20 @@ hidden, restore it first with its show/hide key before pressing `Alt+Q`.
 
 Legacy `single`/`multi`/`input` questions retain their controls: `Tab` and
 `Shift+Tab` switch question/review tabs, arrows move within choices, `Space`
-selects, and `Enter` confirms. A standalone `bool` shows explicit `✓ True` and
-`✗ False` controls; arrows choose, `Space` sets the value, and `Enter` sets and
-continues. A required boolean without a default begins unset, so the user must
-choose; `false` is an answered value.
+selects, and `Enter` confirms. With `allowFreeText: false`, multi-choice uses `Space` to
+toggle selections and `Enter` to continue (there is no extra text row).
+A standalone `bool` shows **one** control: `[✓] True` or `[✗] False`.
+`Space` toggles, up/left sets true, down/right sets false, and `Enter` confirms
+and continues. An unset boolean shows `[ ] True (unset)`; Enter explicitly
+accepts true. Defaults are displayed immediately, and confirming a false
+default keeps it false. `false` is an answered value, never an empty answer.
 
 A `simple-form` is one question tab with all fields in one scrollable view:
 
 - `Tab` / `Shift+Tab` cycles fields and the Continue/Submit button.
 - `Ctrl+Left` / `Ctrl+Right` switches questionnaire tabs from any question.
-- Boolean fields use arrows plus `Space`/`Enter`; single-choice fields use
+- Boolean fields use the same single toggle control (`Space` toggles, arrows set,
+  `Enter` confirms and moves on); single-choice fields use
   arrows plus `Space`/`Enter`; multi-choice fields use `Space` to toggle and
   `Enter` to move on; text fields use `Enter` to move on.
 - `Ctrl+Enter` validates and submits the questionnaire. Required missing/empty
@@ -448,7 +484,7 @@ for a refused explicit config, names the requested route.
   correlation id, route, and status.
 - **The overlay toggle is overlay-only.** Inline and native register no raw
   input listener; hiding never pauses the deadline.
-- **The native route uses single-line `input`**, one logical question at a time (not
+- **The native route defaults to single-line `input`**, one logical question at a time (not
   `editor`, which accepts no timeout/signal). The number and an optional note
   share one box: `2`, `2 | note`, or free text; a number list may be
   comma/space/`，`/`、` separated (`1,3`). Out-of-range or malformed numbers
@@ -456,11 +492,14 @@ for a refused explicit config, names the requested route.
   A form opens sequential per-field dialogs under the same questionnaire
   deadline: boolean fields accept `true`/`false`, form choices accept only
   option numbers and return labels, and optional empty fields are omitted (or
-  use their field default). Cancel/abort/timeout at any field terminates the form.
+  use their field default). With `allowFreeText: false`, single/bool use native
+  selectors (including form fields); multi stays a numbers-only text box, and
+  text fields stay editable. Cancel/abort/timeout at any field terminates the form.
 - **Tool calls run sequentially** (`executionMode: "sequential"`).
-- **Short terminals degrade in a defined order:** the pinned legacy free-input row and
+- **Short terminals degrade in a defined order:** when enabled, the pinned legacy free-input row and
   the key hints survive first, down to `MIN_USABLE_ROWS` (3); 0 rows renders
-  nothing. Forms reserve a visible row for the focused field and auto-scroll it.
+  nothing. Bool, forms, and choices without supplemental text reserve a visible
+  row for the focused control and auto-scroll it.
   `render(width)` never exceeds the requested width or `terminal.rows`.
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black942026/pi-ask-user",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Structured user questions for Pi, with interactive terminal dialogs, native input dialogs, and a reusable TypeScript API.",
   "type": "module",
   "license": "MIT",

package/src/adapters/pi.ts

@@ -59,7 +59,8 @@ export interface PiHostOptions {
  *
  *  - `customUI`      — only in `tui` mode with a callable `ctx.ui.custom()`.
  *  - `nativeDialogs` — only when `ctx.hasUI` and `ctx.ui.input` is callable,
- *    i.e. native input dialogs shown one question at a time. RPC reports
+ *    i.e. native dialogs shown one question at a time. Requests disabling extra
+ *    text additionally require `ui.select` for single/bool controls. RPC reports
  *    `hasUI: true`, so a nonresponsive RPC client is *not* pre-judged: the
  *    attempt is made and the shared deadline turns silence into an actionable
  *    `timeout`.

package/src/answers.ts

@@ -162,6 +162,7 @@ export function validateAnswer(question: NormalizedQuestion, candidate: unknown)
 		if (answer.selections.length > 0) return "input answers cannot contain selections";
 		return (answer.freeText ?? "").trim() === "" ? "input answer is empty" : undefined;
 	}
+	if (question.allowFreeText === false && answer.freeText !== undefined) return "freeText is disabled for this question";
 	if (new Set(answer.selections).size !== answer.selections.length) return "selections contain duplicate labels";
 	if (!answer.selections.every((label) => question.options.some((option) => option.label === label))) return "selection is not an option label";
 	if (question.kind === "single" && answer.selections.length > 1) return "single answer contains multiple selections";

package/src/index.ts

@@ -23,7 +23,7 @@ export * from "./types.ts";
 export { askUser, askUserNormalized } from "./core.ts";
 export { createPiHost, createPiCustomRenderer, type PiHostOptions } from "./adapters/pi.ts";
 export { createAskUser, type AskUser, type CreateAskUserOptions } from "./ask.ts";
-export { createNativeRunner, type NativeDialogUI } from "./ui/native.ts";
+export { createNativeRunner, type NativeDialogUI, type NativeDialogOptions } from "./ui/native.ts";
 export {
 	AskUserComponent,
 	MIN_USABLE_ROWS,
@@ -109,6 +109,7 @@ const PROMPT_GUIDELINES = [
 	"If the tool reports the UI could not run, ask the user the question yourself in ordinary text instead.",
 	"Never invent an answer; on aborted or timeout, report it plainly and do not re-ask.",
 	"Use kind=bool for a real boolean. Use kind=simple-form with flat uniquely named fields when several typed values belong in one logical question; forms cannot nest.",
+	"Set allowFreeText=false to require option selections without supplemental text. Native single/bool then use selectors; native multi still uses a numbers-only text box.",
 ];
 
 /**

package/src/parse.ts

@@ -66,12 +66,14 @@ export function parseNativeAnswer(question: NormalizedQuestion, raw: string): Pa
 
 	// No number in the box: the (optional) right side is the free input.
 	if (leftTrim === "") {
+		if (question.allowFreeText === false) return { ok: false, error: "Free text is disabled; enter option numbers only." };
 		return { ok: true, value: { selections: [], freeText: comment, empty: comment === "" } };
 	}
 
 	const isStrictList = DIGIT_SEPARATOR_ONLY.test(leftTrim);
 	const isListAttempt = isStrictList || NUMBER_LIST_ATTEMPT.test(leftTrim);
 	if (!isListAttempt) {
+		if (question.allowFreeText === false) return { ok: false, error: "Free text is disabled; enter option numbers only." };
 		// Free text, taken verbatim including any `|`.
 		return { ok: true, value: { selections: [], freeText: trimmed, empty: false } };
 	}
@@ -96,6 +98,9 @@ export function parseNativeAnswer(question: NormalizedQuestion, raw: string): Pa
 		return { ok: false, error: "This is a single-select question; enter only one number." };
 	}
 
+	if (question.allowFreeText === false && pipeIndex >= 0) {
+		return { ok: false, error: "Notes are disabled; enter option numbers only." };
+	}
 	const ordered = question.kind === "single" ? unique : [...unique].sort((a, b) => a - b);
 	const value: ParsedAnswer = {
 		selections: question.kind === "single" ? [ordered[0]!] : ordered,
@@ -107,6 +112,11 @@ export function parseNativeAnswer(question: NormalizedQuestion, raw: string): Pa
 
 /** Render the per-question input instruction used by the native route. */
 export function nativeInputHint(question: NormalizedQuestion): string {
+	if (question.allowFreeText === false && (question.kind === "single" || question.kind === "multi")) {
+		return question.kind === "single"
+			? "Single select. Reply with one option number only (e.g. 2)."
+			: "Multi select. Reply with option numbers only, separated by commas (e.g. 1,3).";
+	}
 	switch (question.kind) {
 		case "single":
 			return question.options.length > 0

package/src/schema.ts

@@ -30,7 +30,7 @@ const FIELD_KINDS = ["single", "multi", "input", "bool"] as const;
 const QUESTION_FIELDS = ["id", "title", "prompt", "kind", "options", "default", "fields"] as const;
 const FORM_FIELD_FIELDS = ["name", "label", "kind", "required", "options", "default"] as const;
 const OPTION_FIELDS = ["label", "description", "preview"] as const;
-const REQUEST_FIELDS = ["questions", "header", "displayMode", "timeoutPerQuestionMs"] as const;
+const REQUEST_FIELDS = ["questions", "header", "displayMode", "timeoutPerQuestionMs", "allowFreeText"] as const;
 const SAFE_FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 const UNSAFE_OBJECT_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
@@ -77,6 +77,7 @@ const QuestionSchema = Type.Object({
 export const AskUserParams = Type.Object({
 	questions: Type.Array(QuestionSchema, { minItems: 1, maxItems: MAX_QUESTIONS }),
 	header: Type.Optional(Type.String({ maxLength: LIMITS.header })),
+	allowFreeText: Type.Optional(Type.Boolean({ description: "Allow supplemental/free-text answers on single/multi questions (default true). False hides the extra text input and requires option selections; native single/bool use selectors (including form fields), while native multi/text keep input boxes." })),
 	displayMode: Type.Optional(StringEnum(["overlay", "inline"] as const)),
 	timeoutPerQuestionMs: Type.Optional(Type.Number({ minimum: 0 })),
 }, { additionalProperties: false });
@@ -312,6 +313,10 @@ export function normalizeAskUserRequest(raw: unknown): { request: NormalizedRequ
 	if (rawQuestions.length === 0) throw new AskUserValidationError("At least 1 question is required.");
 	if (rawQuestions.length > MAX_QUESTIONS) throw new AskUserValidationError(`At most ${MAX_QUESTIONS} questions; received ${rawQuestions.length}.`);
 
+	if (raw.allowFreeText !== undefined && typeof raw.allowFreeText !== "boolean") {
+		throw new AskUserValidationError("allowFreeText must be a boolean.");
+	}
+	const allowFreeText = raw.allowFreeText !== false;
 	const warnings: string[] = [];
 	const usedIds = new Set<string>();
 	const questions: NormalizedQuestion[] = [];
@@ -338,12 +343,19 @@ export function normalizeAskUserRequest(raw: unknown): { request: NormalizedRequ
 		};
 		if (question.prompt !== undefined) normalized.prompt = question.prompt;
 		if (question.default !== undefined) normalized.default = question.default;
+		if (question.kind === "single" || question.kind === "multi") {
+			normalized.allowFreeText = allowFreeText;
+			if (!allowFreeText && question.hasDefault && !question.options.some((option) => option.label === String(question.default).trim())) {
+				throw new AskUserValidationError(`Question ${index + 1} default must match an option label when allowFreeText is false.`);
+			}
+		}
 		questions.push(normalized);
 	});
 
 	const timeoutPerQuestionMs = readTimeoutPerQuestionMs(raw.timeoutPerQuestionMs);
 	const request: NormalizedRequest = {
 		questions,
+		allowFreeText,
 		displayMode: readDisplayMode(raw.displayMode),
 		timeoutPerQuestionMs,
 		totalTimeoutMs: timeoutPerQuestionMs * questions.length,

package/src/types.ts

@@ -5,7 +5,7 @@
  * answered through one of two routes:
  *
  *  - `custom` — a custom terminal UI (only a real Pi TUI)
- *  - `native` — native input dialogs (`ctx.hasUI` + callable input), one logical
+ *  - `native` — native dialogs (`ctx.hasUI` + callable input), one logical
  *    question at a time (a form uses sequential per-field dialogs)
  *
  * The route is resolved **once, when the host adapter is created**, from
@@ -141,6 +141,12 @@ export interface AskUserRequest {
 	questions: AskUserQuestion[];
 	/** Optional heading shown above the questionnaire. */
 	header?: string;
+	/**
+	 * Allow supplemental/free-text answers on single/multi questions. Defaults to true.
+	 * False also uses native selectors for single/bool (including form fields);
+	 * native multi/text continue using input boxes.
+	 */
+	allowFreeText?: boolean;
 	/** Custom-UI presentation. Defaults to `overlay`. */
 	displayMode?: AskUserDisplayMode;
 	/**
@@ -403,6 +409,8 @@ export interface NormalizedQuestion {
 	prompt?: string;
 	kind: QuestionKind;
 	options: AskUserOption[];
+	/** False disables free text for single/multi; absent preserves legacy behavior. */
+	allowFreeText?: boolean;
 	default?: string | boolean;
 	hasDefault: boolean;
 	/** Present for `simple-form`; omitted by older already-normalized callers. */
@@ -421,6 +429,8 @@ export interface NormalizedFormField {
 
 export interface NormalizedRequest {
 	header?: string;
+	/** Absent in older normalized callers means true. */
+	allowFreeText?: boolean;
 	questions: NormalizedQuestion[];
 	displayMode: AskUserDisplayMode;
 	timeoutPerQuestionMs: number;

package/src/ui/custom.ts

@@ -190,7 +190,9 @@ export class AskUserComponent implements Component, Focusable {
 		this.mdTheme = buildMarkdownTheme(options.theme);
 		this.overlayToggleKey =
 			options.request.displayMode === "overlay" ? options.overlayToggleKey : undefined;
-		this.drafts = options.request.questions.map(() => emptyDraft());
+		this.drafts = options.request.questions.map((question) =>
+			question.kind === "bool" ? draftFromDefault(question) ?? emptyDraft() : emptyDraft(),
+		);
 		this.cursors = options.request.questions.map(() => 0);
 		this.inputs = options.request.questions.map(
 			(question) => new Input({
@@ -226,7 +228,6 @@ export class AskUserComponent implements Component, Focusable {
 				selections: [], freeText: "", value: { ...values }, valueSet: true, usedDefault: usedDefaults.size > 0,
 			};
 			const optionCursors = fields.map((field) => {
-				if (field.kind === "bool" && field.default === false) return 1;
 				if (field.kind === "single" && typeof field.default === "string") {
 					return Math.max(0, field.options.findIndex((option) => option.label === field.default));
 				}
@@ -322,10 +323,15 @@ export class AskUserComponent implements Component, Focusable {
 		return this.request.questions[this.tab]!;
 	}
 
+	private hasInputBar(question: NormalizedQuestion): boolean {
+		return question.kind === "input" ||
+			((question.kind === "single" || question.kind === "multi") && question.allowFreeText !== false && this.request.allowFreeText !== false);
+	}
+
 	private rowCount(question: NormalizedQuestion): number {
-		if (question.kind === "bool") return 2;
+		if (question.kind === "bool") return 1;
 		if (question.kind === "simple-form") return (question.fields?.length ?? 0) + 1;
-		return question.options.length + 1;
+		return question.options.length + (this.hasInputBar(question) ? 1 : 0);
 	}
 
 	private rowIndex(): number {
@@ -336,7 +342,7 @@ export class AskUserComponent implements Component, Focusable {
 
 	private isInputRow(): boolean {
 		if (this.isReview) return false;
-		if (this.currentQuestion().kind === "bool" || this.currentQuestion().kind === "simple-form") return false;
+		if (!this.hasInputBar(this.currentQuestion())) return false;
 		return this.rowIndex() >= this.currentQuestion().options.length;
 	}
 
@@ -374,7 +380,7 @@ export class AskUserComponent implements Component, Focusable {
 	private syncDraftFromInput(index: number): void {
 		const draft = this.drafts[index];
 		const input = this.inputs[index];
-		if (!draft || !input) return;
+		if (!draft || !input || !this.hasInputBar(this.request.questions[index]!)) return;
 		draft.freeText = input.getValue();
 	}
 
@@ -540,18 +546,14 @@ export class AskUserComponent implements Component, Focusable {
 			return;
 		}
 		if (field.kind === "bool") {
-			if (matchesKey(data, Key.left) || matchesKey(data, Key.up)) cursor = 0;
-			else if (matchesKey(data, Key.right) || matchesKey(data, Key.down)) cursor = 1;
-			else if (matchesKey(data, Key.space)) {
-				this.setFormValue(field, cursor === 0, fieldIndex);
-			} else if (matchesKey(data, Key.enter)) {
-				this.setFormValue(field, cursor === 0, fieldIndex);
-				this.advanceFormField();
-				return;
-			} else return;
-			form.optionCursors[fieldIndex] = cursor;
+			const current = form.present.has(field.name) ? form.values[field.name] : undefined;
+			const next = this.boolValueForKey(data, typeof current === "boolean" ? current : undefined);
+			if (next === undefined) return;
+			// Confirming an existing default preserves its provenance.
+			if (!matchesKey(data, Key.enter) || current === undefined) this.setFormValue(field, next, fieldIndex);
 			this.syncFormDraft(this.tab);
-			this.refresh();
+			if (matchesKey(data, Key.enter)) this.advanceFormField();
+			else this.refresh();
 			return;
 		}
 		if (matchesKey(data, Key.up) || matchesKey(data, Key.left)) cursor = clamp(cursor - 1, 0, field.options.length - 1);
@@ -575,6 +577,15 @@ export class AskUserComponent implements Component, Focusable {
 		this.refresh();
 	}
 
+	/** One boolean control: arrows set, Space toggles, Enter confirms (unset -> true). */
+	private boolValueForKey(data: string, current: boolean | undefined): boolean | undefined {
+		if (matchesKey(data, Key.up) || matchesKey(data, Key.left) || matchesKey(data, "ctrl+p")) return true;
+		if (matchesKey(data, Key.down) || matchesKey(data, Key.right) || matchesKey(data, "ctrl+n")) return false;
+		if (matchesKey(data, Key.space)) return current === undefined ? true : !current;
+		if (matchesKey(data, Key.enter)) return current ?? true;
+		return undefined;
+	}
+
 	// -- key handling --------------------------------------------------------
 
 	handleInput(data: string): void {
@@ -642,28 +653,19 @@ export class AskUserComponent implements Component, Focusable {
 
 		const question = this.currentQuestion();
 		if (question.kind === "bool") {
-			if (matchesKey(data, Key.up) || matchesKey(data, Key.left) || matchesKey(data, "ctrl+p")) {
-				this.cursors[this.tab] = 0;
-				this.refresh();
-				return;
-			}
-			if (matchesKey(data, Key.down) || matchesKey(data, Key.right) || matchesKey(data, "ctrl+n")) {
-				this.cursors[this.tab] = 1;
-				this.refresh();
-				return;
-			}
 			if (matchesKey(data, "s")) {
 				this.skipWithDefault();
 				return;
 			}
-			if (matchesKey(data, Key.space) || matchesKey(data, Key.enter)) {
-				this.drafts[this.tab] = {
-					selections: [], freeText: "", usedDefault: false, value: this.rowIndex() === 0, valueSet: true,
-				};
-				this.notice = undefined;
-				if (matchesKey(data, Key.enter)) this.advance();
-				else this.refresh();
+			const draft = this.drafts[this.tab]!;
+			const next = this.boolValueForKey(data, draft.valueSet && typeof draft.value === "boolean" ? draft.value : undefined);
+			if (next === undefined) return;
+			if (!matchesKey(data, Key.enter) || !draft.valueSet) {
+				this.drafts[this.tab] = { selections: [], freeText: "", usedDefault: false, value: next, valueSet: true };
 			}
+			this.notice = undefined;
+			if (matchesKey(data, Key.enter)) this.advance();
+			else this.refresh();
 			return;
 		}
 		if (question.kind === "input") {
@@ -721,7 +723,7 @@ export class AskUserComponent implements Component, Focusable {
 		}
 
 		const printable = printableText(data);
-		if (printable !== undefined) {
+		if (printable !== undefined && this.hasInputBar(question)) {
 			this.moveRowToInput();
 			this.forwardToInput(data);
 			this.refresh();
@@ -731,7 +733,8 @@ export class AskUserComponent implements Component, Focusable {
 	private onOptionEnter(): void {
 		const question = this.currentQuestion();
 		if (question.kind === "multi") {
-			this.toggleRow();
+			if (this.hasInputBar(question)) this.toggleRow();
+			else this.commitAndAdvance();
 			return;
 		}
 		// Sync any typed note before advancing, so selecting an option never drops
@@ -782,7 +785,9 @@ export class AskUserComponent implements Component, Focusable {
 		this.syncDraftFromInput(this.tab);
 		const draft = this.drafts[this.tab]!;
 		if (draftIsEmpty(draft) && !question.hasDefault) {
-			this.notice = "This question is required: select an option or type text.";
+			this.notice = this.hasInputBar(question)
+				? "This question is required: select an option or type text."
+				: "This question is required: select an option.";
 			this.refresh();
 			return;
 		}
@@ -944,22 +949,19 @@ export class AskUserComponent implements Component, Focusable {
 		return lines;
 	}
 
+	private renderBoolControl(value: boolean | undefined): string {
+		if (value === undefined) return this.theme.fg("muted", "[ ] True (unset)");
+		return this.theme.fg(value ? "success" : "error", value ? "[✓] True" : "[✗] False");
+	}
+
 	private renderBoolOptions(width: number): { lines: string[]; focusLine: number } {
 		const draft = this.drafts[this.tab]!;
-		const row = this.rowIndex();
-		const selected = draft.valueSet ? draft.value : undefined;
-		const choices: Array<{ value: boolean; mark: string; label: string }> = [
-			{ value: true, mark: "✓", label: "True" },
-			{ value: false, mark: "✗", label: "False" },
-		];
-		const lines = choices.map((choice, index) => {
-			const cursor = index === row ? this.theme.fg("accent", "▸") : " ";
-			const chosen = selected === choice.value;
-			const control = chosen ? this.theme.fg(choice.value ? "success" : "error", `[${choice.mark}]`) : this.theme.fg("muted", `[ ] ${choice.mark}`);
-			const label = index === row ? this.theme.bold(this.theme.fg("accent", choice.label)) : choice.label;
-			return truncateToWidth(`  ${cursor} ${control} ${label}`, width);
-		});
-		return { lines, focusLine: row };
+		const value = draft.valueSet && typeof draft.value === "boolean" ? draft.value : undefined;
+		const defaultMark = draft.usedDefault ? this.theme.fg("muted", " (default)") : "";
+		return {
+			lines: [truncateToWidth(`  ${this.theme.fg("accent", "▸")} ${this.renderBoolControl(value)}${defaultMark}`, width)],
+			focusLine: 0,
+		};
 	}
 
 	/** Options only (no input row): the input stays pinned outside the body. */
@@ -1011,15 +1013,8 @@ export class AskUserComponent implements Component, Focusable {
 			}
 			if (field.kind === "bool") {
 				const value = form.present.has(field.name) ? form.values[field.name] : undefined;
-				const cursor = form.optionCursors[fieldIndex] ?? 0;
-				for (const [choiceIndex, choice] of [true, false].entries()) {
-					if (cursor === choiceIndex) focusLine = lines.length;
-					const at = cursor === choiceIndex ? this.theme.fg("accent", "▸") : " ";
-					const selected = value === choice;
-					const mark = choice ? "✓" : "✗";
-					const box = selected ? this.theme.fg(choice ? "success" : "error", `[${mark}]`) : this.theme.fg("muted", `[ ] ${mark}`);
-					lines.push(truncateToWidth(`    ${at} ${box} ${choice ? "True" : "False"}`, width));
-				}
+				focusLine = lines.length;
+				lines.push(truncateToWidth(`    ${this.renderBoolControl(typeof value === "boolean" ? value : undefined)}`, width));
 				return;
 			}
 
@@ -1116,7 +1111,7 @@ export class AskUserComponent implements Component, Focusable {
 
 	/** The free-input row, rendered as a fixed line that never scrolls away. */
 	private renderInputBar(width: number): string[] {
-		if (this.currentQuestion().kind === "bool" || this.currentQuestion().kind === "simple-form") return [];
+		if (!this.hasInputBar(this.currentQuestion())) return [];
 		const input = this.inputs[this.tab]!;
 		input.focused = this.focused && this.isInputRow();
 		return input
@@ -1192,18 +1187,18 @@ export class AskUserComponent implements Component, Focusable {
 			const form = this.forms[this.tab]!;
 			const field = question.fields?.[form.active];
 			if (field?.kind === "multi") hints.push("Space toggle", "Enter next");
-			else if (field?.kind === "bool") hints.push("←/→ choose", "Space set", "Enter next");
+			else if (field?.kind === "bool") hints.push("Space toggle", "←/→ set", "Enter next");
 			else if (field) hints.push("Enter next");
 			else hints.push("Enter continue");
 			if (this.viewport.maxScroll > 0) hints.push("PgUp/PgDn scroll");
 			return withControls(hints);
 		}
 		if (question.kind === "bool") {
-			const hints = ["↑/↓ choose", "Space set", "Enter confirm", "Tab switch"];
+			const hints = ["Space toggle", "↑/↓ set", "Enter confirm", "Tab switch"];
 			if (question.hasDefault) hints.push("s use default");
 			return withControls(hints);
 		}
-		const hints = ["Tab switch", "↑/↓ move", `Enter ${this.isInputRow() ? "confirm" : "select"}`];
+		const hints = ["Tab switch", "↑/↓ move", `Enter ${this.isInputRow() || (question.kind === "multi" && !this.hasInputBar(question)) ? "confirm" : "select"}`];
 		if (question.kind === "multi") hints.push("Space multi-select");
 		if (question.hasDefault) hints.push("s use default");
 		if (this.viewport.maxScroll > 0) hints.push("PgUp/PgDn preview");
@@ -1259,7 +1254,7 @@ export class AskUserComponent implements Component, Focusable {
 		const hintBlock = [this.hintLine(contentWidth)];
 
 		let remaining = contentRows;
-		const typedQuestion = !this.isReview && (this.currentQuestion().kind === "simple-form" || this.currentQuestion().kind === "bool");
+		const typedQuestion = !this.isReview && !this.hasInputBar(this.currentQuestion());
 		const reserveBody = typedQuestion && contentRows > 0 ? 1 : 0;
 		const take = (block: string[]): string[] => {
 			if (remaining <= reserveBody || block.length === 0) return [];

package/src/ui/native.ts

@@ -11,12 +11,21 @@ import type {
 	NormalizedRequest,
 } from "../types.ts";
 
-/** Minimal shape of the Pi UI context needed by the native route. */
+export interface NativeDialogOptions {
+	signal?: AbortSignal;
+	timeout?: number;
+}
+
+/** Native select is required for typed controls when allowFreeText is false. */
 export interface NativeDialogUI {
-	input(title: string, placeholder?: string, opts?: { signal?: AbortSignal; timeout?: number }): Promise<string | undefined>;
+	input(title: string, placeholder?: string, opts?: NativeDialogOptions): Promise<string | undefined>;
+	select?(title: string, options: string[], opts?: NativeDialogOptions): Promise<string | undefined>;
 }
 
 function placeholderFor(question: NormalizedQuestion): string {
+	if (question.allowFreeText === false && (question.kind === "single" || question.kind === "multi")) {
+		return question.kind === "single" ? "one option number, e.g. 2" : "option numbers, e.g. 1,3";
+	}
 	switch (question.kind) {
 		case "single": return 'e.g. 2 or "2 | note" or type free text';
 		case "multi": return 'e.g. 1,3 or "1,3 | note" or type free text';
@@ -26,7 +35,7 @@ function placeholderFor(question: NormalizedQuestion): string {
 	}
 }
 
-function buildPrompt(request: NormalizedRequest, question: NormalizedQuestion, invalid: string | undefined): string {
+function buildPrompt(request: NormalizedRequest, question: NormalizedQuestion, invalid: string | undefined, typed = false): string {
 	const lines: string[] = [];
 	if (request.header?.trim()) lines.push(request.header.trim());
 	lines.push(`[Question ${question.index + 1}/${request.questions.length}] ${question.title}`);
@@ -35,8 +44,8 @@ function buildPrompt(request: NormalizedRequest, question: NormalizedQuestion, i
 		const description = option.description?.trim();
 		lines.push(`  ${index + 1}. ${option.label}${description ? ` — ${description}` : ""}`);
 	});
-	if (question.hasDefault && question.default !== undefined) lines.push(`Default: ${String(question.default)} (empty box uses it)`);
-	lines.push(nativeInputHint(question));
+	if (question.hasDefault && question.default !== undefined) lines.push(`Default: ${String(question.default)}${typed ? "" : " (empty box uses it)"}`);
+	if (!typed) lines.push(nativeInputHint(question));
 	const body = lines.join("\n");
 	return invalid ? `⚠ Invalid input: ${invalid}\n\n${body}` : body;
 }
@@ -56,6 +65,7 @@ function buildFieldPrompt(
 	field: NormalizedFormField,
 	fieldIndex: number,
 	invalid: string | undefined,
+	typed = false,
 ): string {
 	const lines: string[] = [];
 	if (request.header?.trim()) lines.push(request.header.trim());
@@ -66,7 +76,8 @@ function buildFieldPrompt(
 		const description = option.description?.trim();
 		lines.push(`  ${index + 1}. ${option.label}${description ? ` — ${description}` : ""}`);
 	});
-	if (field.hasDefault) lines.push(`Default: ${Array.isArray(field.default) ? field.default.join(", ") : String(field.default)} (empty box uses it)`);
+	if (field.hasDefault) lines.push(`Default: ${Array.isArray(field.default) ? field.default.join(", ") : String(field.default)}${typed ? "" : " (empty box uses it)"}`);
+	if (typed) return lines.join("\n");
 	if (field.kind === "bool") lines.push("Enter exactly true or false (case-insensitive).");
 	else if (field.kind === "single") lines.push("Enter exactly one option number; arbitrary text is not accepted in a form.");
 	else if (field.kind === "multi") lines.push("Enter option numbers separated by commas/spaces; arbitrary text is not accepted in a form.");
@@ -108,13 +119,21 @@ export function createNativeRunner(ui: NativeDialogUI): NativeDialogRunner {
 	return {
 		async run({ request, deadline, signal, onUpdate }: AskUIInput): Promise<AskUIOutcome> {
 			const answers: AskUserAnswer[] = [];
-			const ask = async (title: string, placeholder: string): Promise<{ raw?: string; outcome?: AskUIOutcome }> => {
+			const usesTypedControl = (question: NormalizedQuestion): boolean =>
+				question.kind !== "input" && question.kind !== "multi" && (request.allowFreeText === false || question.allowFreeText === false);
+			// Refuse before showing any dialogs; never substitute text input for a missing selector.
+			const needsSelect = request.questions.some((question) => usesTypedControl(question) &&
+				(question.kind !== "simple-form" || question.fields?.some((field) => field.kind === "bool" || field.kind === "single")));
+			if (needsSelect && typeof ui.select !== "function") {
+				return { kind: "error", message: "allowFreeText=false requires native select dialogs, but this host does not provide ui.select. No text-input fallback was used." };
+			}
+			const dialog = async (invoke: (opts: NativeDialogOptions) => Promise<string | undefined>): Promise<{ raw?: string; outcome?: AskUIOutcome }> => {
 				if (signal?.aborted) return { outcome: { kind: "abort" } };
 				if (deadline.expired()) return { outcome: { kind: "timeout" } };
 				const opts: { signal?: AbortSignal; timeout?: number } = { timeout: deadline.remainingMs() };
 				if (signal) opts.signal = signal;
 				try {
-					const raw = await ui.input(title, placeholder, opts);
+					const raw = await invoke(opts);
 					if (signal?.aborted) return { outcome: { kind: "abort" } };
 					if (deadline.expired()) return { outcome: { kind: "timeout" } };
 					if (raw !== undefined) return { raw };
@@ -126,6 +145,26 @@ export function createNativeRunner(ui: NativeDialogUI): NativeDialogRunner {
 				}
 			};
 
+			const ask = (title: string, placeholder: string) => dialog((opts) => ui.input(title, placeholder, opts));
+			const select = (title: string, options: string[]) => dialog((opts) => ui.select!(title, options, opts));
+			const typedField = async (title: string, field: NormalizedFormField): Promise<{
+				value?: boolean | string | string[]; usedDefault?: boolean; outcome?: AskUIOutcome;
+			}> => {
+				const options = field.kind === "bool" ? ["✓ True", "✗ False"] : field.options.map((option, index) =>
+					`${index + 1}. ${option.label}${option.description ? ` — ${option.description}` : ""}`);
+				const defaultOption = `Use default: ${String(field.default)}`;
+				const skip = "Skip optional field";
+				const response = await select(title, [
+					...options, ...(field.hasDefault ? [defaultOption] : []), ...(!field.required ? [skip] : []),
+				]);
+				if (response.outcome) return { outcome: response.outcome };
+				if (field.hasDefault && response.raw === defaultOption) return { value: cloneDefault(field.default!), usedDefault: true };
+				if (!field.required && response.raw === skip) return {};
+				const index = options.indexOf(response.raw!);
+				if (index < 0) return { outcome: { kind: "error", message: "Native select returned an unknown option." } };
+				return { value: field.kind === "bool" ? index === 0 : field.options[index]!.label, usedDefault: false };
+			};
+
 			for (const question of request.questions) {
 				if (question.kind === "simple-form") {
 					const value: AskUserFormValue = {};
@@ -133,6 +172,14 @@ export function createNativeRunner(ui: NativeDialogUI): NativeDialogRunner {
 					const fields = question.fields ?? [];
 					for (let fieldIndex = 0; fieldIndex < fields.length; fieldIndex += 1) {
 						const field = fields[fieldIndex]!;
+						if (usesTypedControl(question) && (field.kind === "bool" || field.kind === "single")) {
+							onUpdate?.(`Waiting for the user to answer question ${question.index + 1}/${request.questions.length}, field ${fieldIndex + 1}/${fields.length}…`);
+							const response = await typedField(buildFieldPrompt(request, question, field, fieldIndex, undefined, true), field);
+							if (response.outcome) return response.outcome;
+							if (response.value !== undefined) value[field.name] = response.value;
+							usedDefault ||= response.usedDefault === true;
+							continue;
+						}
 						let invalid: string | undefined;
 						for (;;) {
 							onUpdate?.(`Waiting for the user to answer question ${question.index + 1}/${request.questions.length}, field ${fieldIndex + 1}/${fields.length}…`);
@@ -166,6 +213,26 @@ export function createNativeRunner(ui: NativeDialogUI): NativeDialogRunner {
 					continue;
 				}
 
+				if (usesTypedControl(question)) {
+					onUpdate?.(`Waiting for the user to answer question ${question.index + 1}/${request.questions.length}…`);
+					const field: NormalizedFormField = {
+						name: question.id, label: question.title, kind: question.kind as "bool" | "single",
+						required: true, options: question.options, hasDefault: question.hasDefault,
+						default: typeof question.default === "string" ? question.default.trim() : question.default,
+					};
+					const response = await typedField(buildPrompt(request, question, undefined, true), field);
+					if (response.outcome) return response.outcome;
+					const selections = question.kind === "bool" ? [] : question.options
+						.map((option, index) => ({ option, index }))
+						.filter(({ option }) => response.value === option.label)
+						.map(({ index }) => index);
+					answers.push(toAnswer(question, {
+						selections, freeText: "", usedDefault: response.usedDefault === true,
+						...(question.kind === "bool" ? { value: response.value as boolean, valueSet: true } : {}),
+					}));
+					continue;
+				}
+
 				let invalid: string | undefined;
 				for (;;) {
 					onUpdate?.(`Waiting for the user to answer question ${question.index + 1}/${request.questions.length}…`);
@@ -202,7 +269,9 @@ export function createNativeRunner(ui: NativeDialogUI): NativeDialogRunner {
 							answers.push(toAnswer(question, fallback));
 							break;
 						}
-						invalid = question.kind === "input" ? "This question is required and cannot be empty." : "This question is required; enter an option number or free text.";
+						invalid = question.kind === "input" ? "This question is required and cannot be empty."
+							: question.allowFreeText === false ? "This question is required; enter option numbers only."
+							: "This question is required; enter an option number or free text.";
 						continue;
 					}
 					answers.push(toAnswer(question, { selections: parsed.value.selections, freeText: parsed.value.freeText ?? "", usedDefault: false, valueSet: false }));