@black942026/pi-ask-user 0.1.1 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # @black942026/pi-ask-user
 
 A Pi extension for asking structured questions through interactive terminal
-or native input dialogs. Supports single-choice, multiple-choice, and free-text
-answers, with configurable timeouts and cancellation.
+or native input 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
 reuse the same interaction through the TypeScript API.
@@ -17,8 +17,8 @@ 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, a pinned free-input row, and a Markdown preview |
-| `native` | `ctx.hasUI` with a callable `ctx.ui.input` (TUI, RPC/ACP) | native input dialogs, one question at a time (invalid input re-prompts) |
+| `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 |
 
 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.
@@ -45,9 +45,16 @@ The registered tool name is exactly **`ask_user`**.
 | `questions` | `Question[]` | 1–5 questions (required) |
 | `questions[].title` | `string` | heading (required) |
 | `questions[].prompt` | `string?` | extra hint under the heading |
-| `questions[].kind` | `"single" \| "multi" \| "input"?` | inferred from `options` when omitted: present ⇒ `single`, absent ⇒ `input`; `multi` is explicit |
-| `questions[].options` | `Option[]?` | 1–5 × `{ label, description?, preview? }`; required for `single`/`multi`, ignored for `input` |
-| `questions[].default` | `string?` | makes the question skippable |
+| `questions[].kind` | `"single" \| "multi" \| "input" \| "bool" \| "simple-form"?` | inferred from `options` when omitted: present ⇒ `single`, absent ⇒ `input`; other kinds are explicit |
+| `questions[].options` | `Option[]?` | 1–5 × `{ label, description?, preview? }`; required for `single`/`multi`, validated then dropped for legacy `input`, rejected for `bool`/`simple-form` |
+| `questions[].default` | `(string \| boolean)?` | string for legacy kinds, boolean for `bool`; `simple-form` uses field defaults |
+| `questions[].fields` | `FormField[]?` | required only for `simple-form`; 1–10 flat fields, never nested |
+| `fields[].name` | `string` | unique literal output key, 1–64 ASCII letters/digits/`_`/`-`, starting with a letter or `_` |
+| `fields[].label` | `string` | field label (required) |
+| `fields[].kind` | `"bool" \| "single" \| "multi" \| "input"` | exact non-nesting field kind |
+| `fields[].required` | `boolean?` | default `false`; `false` is a valid answered boolean |
+| `fields[].options` | `Option[]?` | required for field `single`/`multi`, rejected for field `bool`/`input` |
+| `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 |
 | `displayMode` | `"overlay" \| "inline"?` | custom route only; default `overlay`; a user-configured preference overrides it |
@@ -55,20 +62,50 @@ The registered tool name is exactly **`ask_user`**.
 
 These fields are the whole input contract, for the tool and for direct calls
 alike. Unknown fields, wrong types, empty ids, and over-long values are rejected
-as `invalid_request`; a `single`/`multi` question without options is an error. An
-explicit `kind: "input"` ignores `options` — if present they are still validated,
-then dropped. Duplicate option labels are de-duplicated and reported in
-`warnings`. Limits: 1–5 questions, ≤5 options each.
+as `invalid_request`; a `single`/`multi` question or field without options is an
+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`.
+
+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,
+against the option labels. A top-level form `options` or `default`, a nested
+form/schema, and `options` on a boolean are errors. Limits are `MAX_QUESTIONS=5`,
+`MAX_OPTIONS=5`, and `MAX_FORM_FIELDS=10`.
 
 ```json
 {
+  "header": "Release",
   "questions": [
     {
-      "title": "Which deploy target?",
-      "kind": "single",
-      "options": [
-        { "label": "staging", "description": "Internal smoke test" },
-        { "label": "production", "description": "Customer-facing" }
+      "title": "Proceed with deployment?",
+      "kind": "bool",
+      "default": false
+    },
+    {
+      "title": "Deployment settings",
+      "kind": "simple-form",
+      "fields": [
+        { "name": "confirmed", "label": "Confirm", "kind": "bool", "required": true },
+        {
+          "name": "target",
+          "label": "Target",
+          "kind": "single",
+          "required": true,
+          "options": [
+            { "label": "staging", "description": "Internal smoke test" },
+            { "label": "production", "description": "Customer-facing" }
+          ]
+        },
+        {
+          "name": "checks",
+          "label": "Checks",
+          "kind": "multi",
+          "options": [{ "label": "unit" }, { "label": "integration" }],
+          "default": ["unit"]
+        },
+        { "name": "note", "label": "Release note", "kind": "input" }
       ]
     }
   ]
@@ -77,13 +114,19 @@ then dropped. Duplicate option labels are de-duplicated and reported in
 
 ## User config file
 
-There are **no environment variables**. User preferences live in a documented
-JSON file:
+There are **no AskUser-specific environment-variable preferences**. User
+preferences live in a JSON file alongside Pi's `settings.json`:
 
 ```
-~/.pi/ask-user/config.json
+~/.pi/agent/ask-user.json
 ```
 
+The directory is resolved by Pi's `getAgentDir()`. If you set Pi's
+`PI_CODING_AGENT_DIR`, the file is `<PI_CODING_AGENT_DIR>/ask-user.json` instead.
+The old `~/.pi/ask-user/config.json` location is no longer read; move an existing
+file to the new location (without overwriting a config already there), then
+restart Pi or run `/reload`.
+
 No file — or an empty/whitespace-only file — means the built-in defaults. The
 knobs are:
 
@@ -291,6 +334,32 @@ The key is shown in the bottom hints and reserved against `overlayToggleKey`
 conflicts. Native input dialogs do not support this shortcut. If an overlay is
 hidden, restore it first with its show/hide key before pressing `Alt+Q`.
 
+## Questionnaire keyboard controls
+
+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.
+
+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
+  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
+  fields focus the first invalid field. `PageUp` / `PageDown` scrolls long form
+  or preview content.
+- `Esc`, `Alt+Q`, and overlay show/hide keep their existing behavior.
+
+The active form field's input or selected option is automatically scrolled into view. Rendering is bounded
+by both terminal width and rows, including narrow/short terminals. Focus is
+propagated to Pi's `Input`, so the hardware cursor marker remains available to
+Chinese/Japanese/Korean IMEs.
+
 ## Overlay show/hide key
 
 On the **custom overlay route only** (never inline, never native), the overlay
@@ -330,8 +399,26 @@ interface AskUserResult {
   warnings?: string[];
   error?: { code: AskUserErrorCode; message: string };
 }
+
+interface AskUserAnswer {
+  index: number;
+  id: string;
+  title: string;
+  kind: "single" | "multi" | "input" | "bool" | "simple-form";
+  selections: string[];            // unchanged for legacy kinds
+  freeText?: string;               // unchanged for legacy kinds
+  usedDefault: boolean;
+  value?: boolean | Record<string, boolean | string | string[]>;
+}
 ```
 
+`bool` answers use `value: boolean`, including meaningful `value: false`.
+`simple-form` answers use a flat object keyed by field `name`. Choice values are
+option labels, multi-choice values are label arrays, boolean values stay
+booleans, and entered text is trimmed on both routes. Optional fields left
+unset are omitted. An explicit field default is included and makes `usedDefault` true; required empty
+text/multi fields are still invalid.
+
 `aborted` covers both a user dismissal and a caller abort, distinguished by
 `cancelledReason`. Errors use `empty_answer`, `invalid_request`,
 `custom_ui_failed`, `native_ui_failed`, `invalid_config`, `unsupported_mode`,
@@ -352,23 +439,29 @@ for a refused explicit config, names the requested route.
 - **A missing route is an error, not a downgrade.** JSON/print, or an explicit
   `mode` that cannot run, is refused with `unsupported_mode` and never replaced by
   another route.
-- **Configuration is a file, never the environment.** No `process.env` knob
-  exists; `~/.pi/ask-user/config.json` is read once per host/session and
-  strictly validated. An invalid config is `invalid_config`, never a fallback.
+- **Preferences are configured in a file, not environment variables.**
+  `<Pi agent directory>/ask-user.json` (normally `~/.pi/agent/ask-user.json`) is
+  read once per host/session and strictly validated. Only the directory follows
+  Pi's `PI_CODING_AGENT_DIR`. An invalid config is `invalid_config`, never a fallback.
 - **Events never leak content by default.** `herdr:blocked` bounds a real wait
   exactly once on each side; outcome events are one per UI attempt and carry only
   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 question at a time (not
+- **The native route uses 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
   re-prompt, and an empty box is rejected unless the question has a `default`.
+  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.
 - **Tool calls run sequentially** (`executionMode: "sequential"`).
-- **Short terminals degrade in a defined order:** the pinned free-input row and
+- **Short terminals degrade in a defined order:** the pinned legacy free-input row and
   the key hints survive first, down to `MIN_USABLE_ROWS` (3); 0 rows renders
-  nothing. `render(width)` never exceeds the requested width or `terminal.rows`.
+  nothing. Forms reserve a visible row for the focused field and auto-scroll it.
+  `render(width)` never exceeds the requested width or `terminal.rows`.
 
 ## Development
 
@@ -388,3 +481,6 @@ pi install /absolute/path/to/pi-ask-user
 by the custom UI and parameter schema (`src/schema.ts`). They are also declared
 as development dependencies for local checks. The routing, parsing, and deadline
 layers are pure, non-TUI, and free of both.
+
+For maintainer release instructions, see
+[CONTRIBUTING.md](https://github.com/black-94/pi-ask-user/blob/main/CONTRIBUTING.md#release).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@black942026/pi-ask-user",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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

@@ -35,7 +35,9 @@ export interface PiHostOptions {
 	timeoutPerQuestionMs?: number;
 	/**
 	 * Path to the user config file, or `false` to skip reading it. Defaults to
-	 * `~/.pi/ask-user/config.json`. There are no environment variables.
+	 * `<Pi agent directory>/ask-user.json` (normally `~/.pi/agent/ask-user.json`).
+	 * The directory follows Pi's `PI_CODING_AGENT_DIR`; there are no AskUser-specific
+	 * environment-variable preferences.
 	 */
 	configFile?: string | false;
 }

package/src/answers.ts

@@ -1,46 +1,42 @@
-import type { AskUserAnswer, NormalizedQuestion } from "./types.ts";
+import type { AskUserAnswer, AskUserFormValue, NormalizedFormField, NormalizedQuestion } from "./types.ts";
 
-/**
- * A draft answer as manipulated by a UI before being finalized. Selections are
- * option indices; free text is kept verbatim while editing.
- */
+/** A UI draft. `valueSet` makes boolean `false` distinct from unanswered. */
 export interface DraftAnswer {
 	selections: number[];
 	freeText: string;
 	usedDefault: boolean;
+	value?: boolean | AskUserFormValue;
+	/** Required to distinguish typed false/empty forms; optional for legacy drafts. */
+	valueSet?: boolean;
 }
 
 export function emptyDraft(): DraftAnswer {
-	return { selections: [], freeText: "", usedDefault: false };
+	return { selections: [], freeText: "", usedDefault: false, valueSet: false };
 }
 
-/** A draft is empty when it carries neither a selection nor any free text. */
+/** A draft is empty only when it contains no legacy or typed value. */
 export function draftIsEmpty(draft: DraftAnswer): boolean {
-	return draft.selections.length === 0 && draft.freeText.trim() === "";
+	return !draft.valueSet && draft.selections.length === 0 && draft.freeText.trim() === "";
 }
 
-/**
- * Materialize the question default as a draft, or `undefined` when the question
- * has no default. A default that matches an option label selects that option;
- * otherwise it is treated as free text (which is what `input` questions want).
- */
+/** Materialize a standalone question default. Forms use per-field defaults. */
 export function draftFromDefault(question: NormalizedQuestion): DraftAnswer | undefined {
 	if (!question.hasDefault || question.default === undefined) return undefined;
+	if (question.kind === "bool") {
+		return { selections: [], freeText: "", value: question.default as boolean, valueSet: true, usedDefault: true };
+	}
 	if (question.kind !== "input") {
-		const idx = question.options.findIndex((option) => option.label === question.default!.trim());
-		if (idx >= 0) {
-			return { selections: [idx], freeText: "", usedDefault: true };
-		}
+		const idx = question.options.findIndex((option) => option.label === String(question.default).trim());
+		if (idx >= 0) return { selections: [idx], freeText: "", valueSet: false, usedDefault: true };
 	}
-	return { selections: [], freeText: question.default, usedDefault: true };
+	return { selections: [], freeText: String(question.default), valueSet: false, usedDefault: true };
 }
 
-/** Finalize a draft into an answer. Assumes the draft is non-empty. */
+/** Finalize a UI draft. Validation is performed separately before acceptance. */
 export function toAnswer(question: NormalizedQuestion, draft: DraftAnswer): AskUserAnswer {
 	const selections = draft.selections
 		.filter((idx) => idx >= 0 && idx < question.options.length)
 		.map((idx) => question.options[idx]!.label);
-	const freeText = draft.freeText.trim();
 	const answer: AskUserAnswer = {
 		index: question.index,
 		id: question.id,
@@ -49,36 +45,125 @@ export function toAnswer(question: NormalizedQuestion, draft: DraftAnswer): AskU
 		selections,
 		usedDefault: draft.usedDefault,
 	};
+	const freeText = draft.freeText.trim();
 	if (freeText !== "") answer.freeText = freeText;
+	if (draft.valueSet && draft.value !== undefined) {
+		answer.value = typeof draft.value === "object" ? { ...draft.value } : draft.value;
+	}
 	return answer;
 }
 
 export interface FinalizeResult {
 	answers: AskUserAnswer[];
-	/** Indices (0-based question indices) still unanswered and without a default. */
+	/** Indices (0-based question indices) that fail the normalized contract. */
 	unanswered: number[];
 }
 
-/**
- * Apply defaults to empty drafts and finalize the questionnaire. Questions that
- * are still empty and have no default are reported in `unanswered`; they are
- * omitted from `answers`.
- */
+/** Apply defaults and finalize; required form fields and `false` are handled explicitly. */
 export function finalizeAnswers(questions: NormalizedQuestion[], drafts: DraftAnswer[]): FinalizeResult {
 	const answers: AskUserAnswer[] = [];
 	const unanswered: number[] = [];
 	questions.forEach((question, index) => {
-		const draft = drafts[index] ?? emptyDraft();
+		let draft = drafts[index] ?? emptyDraft();
 		if (draftIsEmpty(draft)) {
 			const fallback = draftFromDefault(question);
-			if (fallback) {
-				answers.push(toAnswer(question, fallback));
-			} else {
-				unanswered.push(index);
-			}
+			if (fallback) draft = fallback;
+		}
+		if (draftIsEmpty(draft)) {
+			unanswered.push(index);
 			return;
 		}
-		answers.push(toAnswer(question, draft));
+		const answer = toAnswer(question, draft);
+		if (validateAnswer(question, answer) !== undefined) {
+			unanswered.push(index);
+			return;
+		}
+		answers.push(answer);
 	});
 	return { answers, unanswered };
 }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(record: Record<string, unknown>, key: string): boolean {
+	return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function validateFieldValue(field: NormalizedFormField, value: unknown): string | undefined {
+	switch (field.kind) {
+		case "bool":
+			return typeof value === "boolean" ? undefined : "must be a boolean";
+		case "input":
+			if (typeof value !== "string") return "must be a string";
+			if (field.required && value.trim() === "") return "must not be empty";
+			return undefined;
+		case "single":
+			if (typeof value !== "string") return "must be one option label";
+			return field.options.some((option) => option.label === value) ? undefined : "is not an option label";
+		case "multi": {
+			if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) return "must be an array of option labels";
+			if (field.required && value.length === 0) return "must contain at least one option";
+			if (new Set(value).size !== value.length) return "contains duplicate labels";
+			return value.every((entry) => field.options.some((option) => option.label === entry))
+				? undefined
+				: "contains a label that is not an option";
+		}
+	}
+}
+
+/**
+ * Validate a renderer outcome against its exact normalized question. This is
+ * the core trust boundary: malformed ids/kinds/options/typed values are never
+ * silently accepted as user input.
+ */
+export function validateAnswer(question: NormalizedQuestion, candidate: unknown): string | undefined {
+	if (!isRecord(candidate)) return "answer must be an object";
+	const allowedAnswerKeys = ["index", "id", "title", "kind", "selections", "freeText", "usedDefault", "value"];
+	const extra = Object.keys(candidate).find((key) => !allowedAnswerKeys.includes(key));
+	if (extra) return `answer has unknown field "${extra}"`;
+	const answer = candidate as unknown as AskUserAnswer;
+	if (answer.index !== question.index || answer.id !== question.id || answer.title !== question.title || answer.kind !== question.kind) {
+		return "answer identity does not match the question";
+	}
+	if (!Array.isArray(answer.selections) || answer.selections.some((entry) => typeof entry !== "string")) return "selections must be strings";
+	if (typeof answer.usedDefault !== "boolean") return "usedDefault must be a boolean";
+	if (answer.freeText !== undefined && typeof answer.freeText !== "string") return "freeText must be a string";
+
+	if (question.kind === "bool") {
+		if (answer.selections.length > 0 || answer.freeText !== undefined) return "bool answers cannot contain selections or freeText";
+		return typeof answer.value === "boolean" ? undefined : "bool answer value must be a boolean";
+	}
+	if (question.kind === "simple-form") {
+		if (answer.selections.length > 0 || answer.freeText !== undefined) return "simple-form answers cannot contain selections or freeText";
+		if (!isRecord(answer.value)) return "simple-form answer value must be a flat object";
+		const prototype = Object.getPrototypeOf(answer.value);
+		if (prototype !== Object.prototype && prototype !== null) return "simple-form answer value has an unsafe prototype";
+		const fields = question.fields ?? [];
+		const allowed = new Map(fields.map((field) => [field.name, field]));
+		for (const key of Object.keys(answer.value)) {
+			const field = allowed.get(key);
+			if (!field) return `simple-form answer has unknown field "${key}"`;
+			const invalid = validateFieldValue(field, answer.value[key]);
+			if (invalid) return `simple-form field "${key}" ${invalid}`;
+		}
+		for (const field of fields) {
+			if (!field.required) continue;
+			if (!hasOwn(answer.value, field.name)) return `simple-form required field "${field.name}" is missing`;
+			const invalid = validateFieldValue(field, answer.value[field.name]);
+			if (invalid) return `simple-form required field "${field.name}" ${invalid}`;
+		}
+		return undefined;
+	}
+
+	if (answer.value !== undefined) return `${question.kind} answers cannot contain a typed value`;
+	if (question.kind === "input") {
+		if (answer.selections.length > 0) return "input answers cannot contain selections";
+		return (answer.freeText ?? "").trim() === "" ? "input answer is empty" : undefined;
+	}
+	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";
+	return answer.selections.length === 0 && (answer.freeText ?? "").trim() === "" ? "answer is empty" : undefined;
+}

package/src/config.ts

@@ -1,16 +1,18 @@
 /**
  * User configuration for AskUser.
  *
- * Configuration is a plain JSON file — never environment variables. It lives in
- * a per-user directory and is read **once per host/session creation**, never per
- * request:
+ * Configuration is a plain JSON file — no AskUser-specific environment knobs.
+ * It lives alongside Pi's settings.json and is read **once per host/session
+ * creation**, never per request:
  *
- *   ~/.pi/ask-user/config.json
+ *   ~/.pi/agent/ask-user.json
+ *
+ * The directory follows Pi's getAgentDir(), including PI_CODING_AGENT_DIR.
  *
  * No file (or an empty file) means the built-in defaults. An existing file is
  * validated strictly: malformed JSON, unknown keys, and bad values are reported
  * as actionable `invalid_config` errors instead of being silently ignored or
- * coerced. There are deliberately no environment-variable knobs.
+ * coerced. Preferences are configured only through the file or explicit options.
  *
  * Effective precedence for every knob is:
  *
@@ -21,14 +23,14 @@
  * reports what the user actually configured, leaving unset knobs `undefined`.
  */
 import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { AskUserDisplayMode, AskUserMode, AskUserUiPreferences } from "./types.ts";
 
 /** Directory holding the user config file. */
-export const USER_CONFIG_DIR = join(homedir(), ".pi", "ask-user");
-/** The documented user config file. */
-export const USER_CONFIG_PATH = join(USER_CONFIG_DIR, "config.json");
+export const USER_CONFIG_DIR = getAgentDir();
+/** The documented user config file, alongside Pi's settings.json. */
+export const USER_CONFIG_PATH = join(USER_CONFIG_DIR, "ask-user.json");
 
 /** Built-in default key that toggles the overlay between hidden and visible. */
 export const DEFAULT_OVERLAY_TOGGLE_KEY = "alt+o";

package/src/core.ts

@@ -1,4 +1,5 @@
 import { combineSignals, createDeadline, safeTimeoutMs } from "./deadline.ts";
+import { validateAnswer } from "./answers.ts";
 import { AskUserValidationError, normalizeAskUserRequest } from "./schema.ts";
 import type {
 	AskUIInput,
@@ -272,7 +273,15 @@ function mapOutcome(
 ): AskUserResult {
 	switch (outcome.kind) {
 		case "submitted": {
-			const answers = outcome.answers ?? [];
+			if (!Array.isArray(outcome.answers)) {
+				return {
+					status: "error",
+					route,
+					answers: [],
+					error: { code: "internal", message: `${route} UI returned a malformed answers payload.` },
+				};
+			}
+			const answers = outcome.answers;
 			if (answers.length !== request.questions.length) {
 				return {
 					status: "error",
@@ -284,15 +293,23 @@ function mapOutcome(
 					},
 				};
 			}
-			const empty = answers.find(
-				(answer) => answer.selections.length === 0 && (answer.freeText ?? "").trim() === "",
-			);
-			if (empty) {
+			for (let index = 0; index < answers.length; index += 1) {
+				const answer = answers[index]!;
+				let invalid: string | undefined;
+				try {
+					invalid = validateAnswer(request.questions[index]!, answer);
+				} catch (error) {
+					invalid = `answer validation failed: ${messageOf(error)}`;
+				}
+				if (!invalid) continue;
 				return {
 					status: "error",
 					route,
 					answers,
-					error: { code: "empty_answer", message: `The answer to question "${empty.title}" is empty.` },
+					error: {
+						code: invalid.includes("empty") || invalid.includes("missing") ? "empty_answer" : "internal",
+						message: `The ${route} UI returned an invalid answer for question "${request.questions[index]!.title}": ${invalid}.`,
+					},
 				};
 			}
 			return { status: "answered", route, answers };

package/src/index.ts

@@ -38,6 +38,7 @@ export {
 	DEFAULT_TIMEOUT_PER_QUESTION_MS,
 	LIMITS,
 	MAX_OPTIONS,
+	MAX_FORM_FIELDS,
 	MAX_QUESTIONS,
 	normalizeAskUserRequest,
 } from "./schema.ts";
@@ -77,6 +78,7 @@ export {
 	emptyDraft,
 	finalizeAnswers,
 	toAnswer,
+	validateAnswer,
 	type DraftAnswer,
 	type FinalizeResult,
 } from "./answers.ts";
@@ -98,7 +100,7 @@ export interface AskUserToolDetails {
 	progress?: string;
 }
 
-const DESCRIPTION = "Ask the user one or more structured questions through the host's interactive UI.";
+const DESCRIPTION = "Ask the user structured single-choice, multi-choice, text, boolean, or flat form questions through the host's interactive UI.";
 
 const PROMPT_SNIPPET = "Ask the user structured questions when you would otherwise guess.";
 
@@ -106,6 +108,7 @@ const PROMPT_GUIDELINES = [
 	"Use ask_user when a choice is high-impact or ambiguous and you cannot infer the answer.",
 	"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.",
 ];
 
 /**
@@ -136,6 +139,12 @@ function describeRequestAsText(request: NormalizedRequest): string {
 			const description = option.description?.trim();
 			lines.push(`   ${optionIndex + 1}) ${option.label}${description ? ` — ${description}` : ""}`);
 		});
+		if (question.kind === "bool") lines.push("   answer: true or false");
+		for (const field of question.fields ?? []) {
+			lines.push(`   - ${field.label} [${field.name}: ${field.kind}]${field.required ? " required" : " optional"}`);
+			field.options.forEach((option, optionIndex) => lines.push(`      ${optionIndex + 1}) ${option.label}`));
+			if (field.hasDefault) lines.push(`      default: ${JSON.stringify(field.default)}`);
+		}
 		if (question.hasDefault && question.default !== undefined) lines.push(`   default: ${question.default}`);
 	});
 	return lines.join("\n");
@@ -151,6 +160,10 @@ function buildModelContent(result: AskUserResult, request: NormalizedRequest): s
 	switch (result.status) {
 		case "answered": {
 			const lines = result.answers.map((answer) => {
+				if (answer.value !== undefined) {
+					const suffix = answer.usedDefault ? " (default used)" : "";
+					return `- ${answer.title}: ${JSON.stringify(answer.value)}${suffix}`;
+				}
 				const parts: string[] = [];
 				if (answer.selections.length > 0) parts.push(answer.selections.join(", "));
 				if (answer.freeText) parts.push(answer.freeText);
@@ -211,7 +224,9 @@ export interface RegisterAskUserOptions {
 	timeoutPerQuestionMs?: number;
 	/**
 	 * Path to the user config file, or `false` to skip reading it. Defaults to
-	 * `~/.pi/ask-user/config.json`. There are no environment variables.
+	 * `<Pi agent directory>/ask-user.json` (normally `~/.pi/agent/ask-user.json`).
+	 * The directory follows Pi's `PI_CODING_AGENT_DIR`; there are no AskUser-specific
+	 * environment-variable preferences.
 	 */
 	configFile?: string | false;
 }

package/src/parse.ts

@@ -54,6 +54,9 @@ export function parseNativeAnswer(question: NormalizedQuestion, raw: string): Pa
 	if (question.kind === "input") {
 		return { ok: true, value: { selections: [], freeText: trimmed, empty: false } };
 	}
+	if (question.kind === "bool" || question.kind === "simple-form") {
+		return { ok: false, error: `${question.kind} uses typed native input and cannot be parsed as a legacy answer.` };
+	}
 
 	const pipeIndex = raw.indexOf("|");
 	const left = pipeIndex >= 0 ? raw.slice(0, pipeIndex) : raw;
@@ -115,5 +118,9 @@ export function nativeInputHint(question: NormalizedQuestion): string {
 				: "Free input. Reply with text to answer.";
 		case "input":
 			return "Free input. Reply with text to answer.";
+		case "bool":
+			return "Boolean. Reply with true or false.";
+		case "simple-form":
+			return "Form fields are asked one at a time.";
 	}
 }