@black942026/pi-ask-user 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,11 @@
 # @black942026/pi-ask-user
 
-`ask_user` — a route-resolved "ask the user" interaction for Pi.
+A Pi extension for asking structured questions through interactive terminal
+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.
 
 Two entry points share one strict questionnaire contract and one route resolution:
 
@@ -12,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.
@@ -22,16 +27,14 @@ or probed when the host is created, never per request.
 
 ```bash
 pi install npm:@black942026/pi-ask-user
-# or, from a local checkout
-pi install /absolute/path/to/pi-ask-user
-# or, during development
-pi --extension ./index.ts
 ```
 
-Requires Node.js ≥ 22.19.0.
+Start a new Pi session, or run `/reload` in an existing session, to load the
+extension. The `ask_user` tool is registered automatically.
 
-Peer dependencies: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`,
-`typebox`.
+Requires Node.js ≥ 22.19.0 and Pi ≥ 0.87.0. Pi supplies the host dependencies
+`@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, and `typebox`;
+no separate dependency installation is needed when using `pi install`.
 
 ## Tool parameters
 
@@ -42,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 |
@@ -52,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" }
       ]
     }
   ]
@@ -74,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:
 
@@ -111,8 +157,8 @@ against the questionnaire's own controls. A malformed spec (`alt+banana`), a
 reserved key (`escape`/`esc` — which must keep cancelling — plus
 `enter`/`tab`/arrows/`space`/`pageUp`/…), a bare printable key that would swallow
 typing (`o`), and conflicting chords (`ctrl+c`, `ctrl+d`, `ctrl+u`, `ctrl+p`,
-`ctrl+n`, `ctrl+enter`) are each rejected with a specific reason. A key is never
-silently substituted.
+`ctrl+n`, `ctrl+enter`, `alt+q`) are each rejected with a specific reason. A key
+is never silently substituted.
 
 ### Effective precedence and read timing
 
@@ -275,6 +321,45 @@ an optional sink — `createAskUser(ctx, { events: { waitStarted, waitEnded } })
 or `createAskUser(host, { events })` — or accept that no runtime events are
 emitted. `AskUserEventSink` is exported for this.
 
+## Cancel countdown shortcut
+
+In the **custom terminal UI** (overlay or inline), press **`Alt+Q`** to cancel
+this questionnaire's countdown without dismissing it or changing your answers.
+The header shows **`No timeout`**; you can keep answering, submit normally, or
+press `Esc` to dismiss. Caller aborts still work. This is a one-way change for
+the current questionnaire only; the next call starts with its configured timeout.
+An already-expired deadline cannot be cancelled.
+
+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
@@ -314,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`,
@@ -325,42 +428,59 @@ for a refused explicit config, names the requested route.
 ## Key constraints
 
 - **The deadline is shared and owned by the core.** Per questionnaire it is
-  strictly `timeoutPerQuestionMs × questionCount` (default 60 s each), clamped to
+  initially `timeoutPerQuestionMs × questionCount` (default 60 s each), clamped to
   `MAX_SAFE_TIMEOUT_MS` (2³¹−1); there is no absolute override. The deadline and
   the caller's cancellation are raced independently of the renderer, so a renderer
   that never resolves or ignores its `AbortSignal` still yields
-  `timeout`/`aborted`; late results are discarded. Cancellation is checked before
-  any route branch, so an already-aborted call never renders a UI.
+  `timeout`/`aborted`, unless the user explicitly cancels the timeout with `Alt+Q`
+  in the custom UI (caller aborts remain effective); late results are discarded.
+  Cancellation is checked before any route branch, so an already-aborted call
+  never renders a UI.
 - **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
 
 ```bash
 npm install
 npm run typecheck   # tsc --noEmit
-npm test            # node --test test/*.test.ts (Node ≥ 22.6 runs TS directly)
+npm test            # node --test test/*.test.ts
 npm run check       # typecheck + tests
+
+# Load a local checkout for development
+pi --extension ./index.ts
+# Or install it as a local package
+pi install /absolute/path/to/pi-ask-user
 ```
 
-`@earendil-works/pi-tui` is a runtime dependency of the custom UI, and `typebox`
-is a runtime dependency of the parameter schema (`src/schema.ts`). The routing,
-parsing, and deadline layers are pure, non-TUI, and free of both.
+`@earendil-works/pi-tui` and `typebox` are host-provided peer dependencies used
+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,7 +1,7 @@
 {
   "name": "@black942026/pi-ask-user",
-  "version": "0.1.0",
-  "description": "AskUser - a route-forced ask-user interaction component/tool for Pi extensions (custom TUI or native dialogs)",
+  "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",
   "repository": {

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;
 }
@@ -195,6 +197,7 @@ export function createPiCustomRenderer(ui: ExtensionUIContext, options: PiCustom
 						component = new AskUserComponent({
 							request,
 							deadline,
+							cancelTimeout: input.cancelTimeout,
 							theme: theme as unknown as AskUserTheme,
 							tui,
 							done,

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,17 +23,19 @@
  * 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";
+/** Cancel the current questionnaire's countdown without dismissing the UI. */
+export const CANCEL_TIMEOUT_KEY = "alt+q";
 /** Built-in default custom-UI presentation. */
 export const DEFAULT_DISPLAY_MODE: AskUserDisplayMode = "overlay";
 
@@ -129,7 +133,7 @@ const RESERVED_BASES = new Set([
 ]);
 /** Modifier chords that conflict with a questionnaire control. */
 const RESERVED_SIGNATURES = new Set(
-	["ctrl+c", "ctrl+d", "ctrl+u", "ctrl+p", "ctrl+n", "ctrl+enter"].map((id) => {
+	["ctrl+c", "ctrl+d", "ctrl+u", "ctrl+p", "ctrl+n", "ctrl+enter", CANCEL_TIMEOUT_KEY].map((id) => {
 		const parts = id.split("+");
 		const base = parts.pop()!;
 		return [...parts.sort(), base].join("+");