@black942026/pi-ask-user 0.1.1 → 0.1.3

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 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; 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.
@@ -45,30 +45,99 @@ 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 |
+| `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 |
 
 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`.
+
+### 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,
+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 +146,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 +366,36 @@ 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. 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 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
+  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 +435,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 +475,32 @@ 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 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
   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). 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 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. `render(width)` never exceeds the requested width or `terminal.rows`.
+  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
 
@@ -388,3 +520,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.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

@@ -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;
 }
@@ -57,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

@@ -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,126 @@ 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 (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";
+	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 };