@black942026/pi-ask-user 0.1.1 → 0.1.3

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,
@@ -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,8 @@ 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.",
+	"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.",
 ];
 
 /**
@@ -136,6 +140,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 +161,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 +225,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;
@@ -63,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 } };
 	}
@@ -93,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,
@@ -104,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
@@ -115,5 +128,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.";
 	}
 }

package/src/schema.ts

@@ -1,8 +1,16 @@
 import { Type } from "typebox";
-import type { AskUserOption, AskUserQuestion, NormalizedQuestion, NormalizedRequest, QuestionKind } from "./types.ts";
+import type {
+	AskUserOption,
+	FormFieldKind,
+	NormalizedFormField,
+	NormalizedQuestion,
+	NormalizedRequest,
+	QuestionKind,
+} from "./types.ts";
 
 export const MAX_QUESTIONS = 5;
 export const MAX_OPTIONS = 5;
+export const MAX_FORM_FIELDS = 10;
 export const DEFAULT_TIMEOUT_PER_QUESTION_MS = 60_000;
 
 export const LIMITS = {
@@ -13,18 +21,20 @@ export const LIMITS = {
 	preview: 4000,
 	defaultValue: 500,
 	header: 200,
+	fieldName: 64,
 } as const;
 
 const ID_MAX_LENGTH = 64;
-const QUESTION_KINDS = ["single", "multi", "input"] as const;
-const QUESTION_FIELDS = ["id", "title", "prompt", "kind", "options", "default"] as const;
+const QUESTION_KINDS = ["single", "multi", "input", "bool", "simple-form"] as const;
+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"]);
 
-/**
- * Flat string enum. Emitted as `{ type: "string", enum: [...] }` because some
- * provider proxies reject `anyOf`/`union` shapes.
- */
+/** Flat string enum: provider proxies commonly reject unions used only as enums. */
 function StringEnum<T extends readonly string[]>(values: T, options: Record<string, unknown> = {}) {
 	return Type.Unsafe<T[number]>({ type: "string", enum: [...values], ...options });
 }
@@ -33,7 +43,25 @@ const OptionSchema = Type.Object({
 	label: Type.String({ minLength: 1, maxLength: LIMITS.label }),
 	description: Type.Optional(Type.String({ maxLength: LIMITS.description })),
 	preview: Type.Optional(Type.String({ maxLength: LIMITS.preview })),
-});
+}, { additionalProperties: false });
+
+// Field defaults use three JSON types across the four field kinds. Keep that honest in
+// the provider schema; kind-specific membership and type rules are enforced by
+// the same direct normalizer used by tool execution.
+const FieldDefaultSchema = Type.Union([
+	Type.Boolean(),
+	Type.String({ maxLength: LIMITS.defaultValue }),
+	Type.Array(Type.String({ minLength: 1, maxLength: LIMITS.label }), { maxItems: MAX_OPTIONS }),
+]);
+
+const FormFieldSchema = Type.Object({
+	name: Type.String({ minLength: 1, maxLength: LIMITS.fieldName, pattern: SAFE_FIELD_NAME.source }),
+	label: Type.String({ minLength: 1, maxLength: LIMITS.label }),
+	kind: StringEnum(FIELD_KINDS),
+	required: Type.Optional(Type.Boolean()),
+	options: Type.Optional(Type.Array(OptionSchema, { maxItems: MAX_OPTIONS })),
+	default: Type.Optional(FieldDefaultSchema),
+}, { additionalProperties: false });
 
 const QuestionSchema = Type.Object({
 	id: Type.Optional(Type.String({ minLength: 1, maxLength: ID_MAX_LENGTH })),
@@ -41,27 +69,21 @@ const QuestionSchema = Type.Object({
 	prompt: Type.Optional(Type.String({ maxLength: LIMITS.prompt })),
 	kind: Type.Optional(StringEnum(QUESTION_KINDS)),
 	options: Type.Optional(Type.Array(OptionSchema, { maxItems: MAX_OPTIONS })),
-	default: Type.Optional(Type.String({ maxLength: LIMITS.defaultValue })),
-});
-
-/**
- * Parameter schema registered for the `ask_user` tool, and the single input
- * contract for direct `askUser` calls too. Only these fields and types are read;
- * anything else is rejected as `invalid_request` rather than coerced.
- *
- * The UI route is host configuration, resolved by the host adapter — it is never
- * part of a request.
- */
+	default: Type.Optional(Type.Union([Type.String({ maxLength: LIMITS.defaultValue }), Type.Boolean()])),
+	fields: Type.Optional(Type.Array(FormFieldSchema, { minItems: 1, maxItems: MAX_FORM_FIELDS })),
+}, { additionalProperties: false });
+
+/** Strict tool/direct-call parameter contract. */
 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 });
 
 export class AskUserValidationError extends Error {
 	readonly code = "invalid_request";
-
 	constructor(message: string) {
 		super(message);
 		this.name = "AskUserValidationError";
@@ -72,14 +94,12 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Reject any field that is not part of the declared contract. */
 function assertKnownKeys(record: Record<string, unknown>, allowed: readonly string[], where: string): void {
 	for (const key of Object.keys(record)) {
 		if (!allowed.includes(key)) throw new AskUserValidationError(`${where} has an unknown field "${key}".`);
 	}
 }
 
-/** A required, non-empty, length-bounded string; returns the trimmed value. */
 function requireText(value: unknown, where: string, maxLength: number): string {
 	if (typeof value !== "string") throw new AskUserValidationError(`${where} must be a string.`);
 	const text = value.trim();
@@ -88,7 +108,6 @@ function requireText(value: unknown, where: string, maxLength: number): string {
 	return text;
 }
 
-/** An optional, length-bounded string; absent stays absent. */
 function optionalText(value: unknown, where: string, maxLength: number): string | undefined {
 	if (value === undefined) return undefined;
 	if (typeof value !== "string") throw new AskUserValidationError(`${where} must be a string.`);
@@ -105,7 +124,6 @@ function optionalQuestionId(value: unknown, where: string): string | undefined {
 	return id;
 }
 
-/** A canonical option object: `{ label, description?, preview? }`. */
 function readOption(value: unknown, where: string, position: number): AskUserOption {
 	const at = `${where} option ${position + 1}`;
 	if (!isRecord(value)) throw new AskUserValidationError(`${at} must be an object with a "label".`);
@@ -119,137 +137,230 @@ function readOption(value: unknown, where: string, position: number): AskUserOpt
 	return option;
 }
 
-function readQuestion(value: unknown, index: number): { question: AskUserQuestion; warnings: string[] } {
+function readOptions(value: unknown, where: string, warnings: string[]): AskUserOption[] {
+	if (value !== undefined && !Array.isArray(value)) throw new AskUserValidationError(`${where} "options" must be an array.`);
+	const raw = value ?? [];
+	if (raw.length > MAX_OPTIONS) throw new AskUserValidationError(`${where} has more than ${MAX_OPTIONS} options.`);
+	const options: AskUserOption[] = [];
+	const seen = new Set<string>();
+	raw.forEach((entry: unknown, position: number) => {
+		const option = readOption(entry, where, position);
+		if (seen.has(option.label)) {
+			warnings.push(`${where} has a duplicate option "${option.label}"; de-duplicated.`);
+			return;
+		}
+		seen.add(option.label);
+		options.push(option);
+	});
+	return options;
+}
+
+function readFieldName(value: unknown, where: string): string {
+	if (typeof value !== "string") throw new AskUserValidationError(`${where} name must be a string.`);
+	if (value.length === 0) throw new AskUserValidationError(`${where} name must not be empty.`);
+	if (value.length > LIMITS.fieldName) throw new AskUserValidationError(`${where} name exceeds the ${LIMITS.fieldName}-character limit.`);
+	if (!SAFE_FIELD_NAME.test(value)) {
+		throw new AskUserValidationError(`${where} name must be a literal key using letters, digits, "_", or "-", and may not contain a path.`);
+	}
+	if (UNSAFE_OBJECT_KEYS.has(value)) throw new AskUserValidationError(`${where} name "${value}" is reserved and unsafe.`);
+	return value;
+}
+
+function readFormField(value: unknown, questionWhere: string, position: number, warnings: string[]): NormalizedFormField {
+	const where = `${questionWhere} field ${position + 1}`;
+	if (!isRecord(value)) throw new AskUserValidationError(`${where} must be an object.`);
+	assertKnownKeys(value, FORM_FIELD_FIELDS, where);
+	const name = readFieldName(value.name, where);
+	const label = requireText(value.label, `${where} label`, LIMITS.label);
+	if (typeof value.kind !== "string" || !FIELD_KINDS.includes(value.kind as FormFieldKind)) {
+		throw new AskUserValidationError(`${where} "kind" must be "bool", "single", "multi", or "input"; forms cannot nest.`);
+	}
+	const kind = value.kind as FormFieldKind;
+	if (value.required !== undefined && typeof value.required !== "boolean") {
+		throw new AskUserValidationError(`${where} "required" must be a boolean.`);
+	}
+	const required = value.required === true;
+	if ((kind === "bool" || kind === "input") && value.options !== undefined) {
+		throw new AskUserValidationError(`${where} is a "${kind}" field and must not have "options".`);
+	}
+	const options = readOptions(value.options, where, warnings);
+	if ((kind === "single" || kind === "multi") && options.length === 0) {
+		throw new AskUserValidationError(`${where} is a "${kind}" field but has no options.`);
+	}
+
+	const field: NormalizedFormField = { name, label, kind, required, options, hasDefault: value.default !== undefined };
+	if (value.default === undefined) return field;
+	if (kind === "bool") {
+		if (typeof value.default !== "boolean") throw new AskUserValidationError(`${where} bool default must be a boolean.`);
+		field.default = value.default;
+		return field;
+	}
+	if (kind === "input") {
+		if (typeof value.default !== "string") throw new AskUserValidationError(`${where} input default must be a string.`);
+		if (value.default.length > LIMITS.defaultValue) throw new AskUserValidationError(`${where} default exceeds the ${LIMITS.defaultValue}-character limit.`);
+		if (required && value.default.trim() === "") throw new AskUserValidationError(`${where} required input default must not be empty.`);
+		field.default = value.default;
+		return field;
+	}
+	if (kind === "single") {
+		if (typeof value.default !== "string") throw new AskUserValidationError(`${where} single default must be an option-label string.`);
+		if (!options.some((option) => option.label === value.default)) throw new AskUserValidationError(`${where} default must match one of its option labels.`);
+		field.default = value.default;
+		return field;
+	}
+	if (!Array.isArray(value.default)) throw new AskUserValidationError(`${where} multi default must be an array of option-label strings.`);
+	if (value.default.length > MAX_OPTIONS) throw new AskUserValidationError(`${where} multi default has more than ${MAX_OPTIONS} labels.`);
+	if (required && value.default.length === 0) throw new AskUserValidationError(`${where} required multi default must select at least one label.`);
+	const selected: string[] = [];
+	for (const [defaultIndex, entry] of value.default.entries()) {
+		const labelValue = requireText(entry, `${where} default item ${defaultIndex + 1}`, LIMITS.label);
+		if (!options.some((option) => option.label === labelValue)) throw new AskUserValidationError(`${where} default item "${labelValue}" is not an option label.`);
+		if (selected.includes(labelValue)) throw new AskUserValidationError(`${where} multi default contains duplicate label "${labelValue}".`);
+		selected.push(labelValue);
+	}
+	field.default = selected;
+	return field;
+}
+
+interface ParsedQuestion {
+	id?: string;
+	title: string;
+	prompt?: string;
+	kind: QuestionKind;
+	options: AskUserOption[];
+	default?: string | boolean;
+	hasDefault: boolean;
+	fields: NormalizedFormField[];
+}
+
+function readQuestion(value: unknown, index: number): { question: ParsedQuestion; warnings: string[] } {
 	const warnings: string[] = [];
 	const where = `Question ${index + 1}`;
 	if (!isRecord(value)) throw new AskUserValidationError(`${where} must be an object.`);
 	assertKnownKeys(value, QUESTION_FIELDS, where);
-
 	const title = requireText(value.title, `${where} title`, LIMITS.title);
 
 	let kind: QuestionKind | undefined;
 	if (value.kind !== undefined) {
 		if (typeof value.kind !== "string" || !QUESTION_KINDS.includes(value.kind as QuestionKind)) {
-			throw new AskUserValidationError(`${where} "kind" must be "single", "multi", or "input".`);
+			throw new AskUserValidationError(`${where} "kind" must be "single", "multi", "input", "bool", or "simple-form".`);
 		}
 		kind = value.kind as QuestionKind;
 	}
-
-	const rawOptions = value.options;
-	if (rawOptions !== undefined && !Array.isArray(rawOptions)) {
-		throw new AskUserValidationError(`${where} "options" must be an array.`);
+	if ((kind === "bool" || kind === "simple-form") && value.options !== undefined) {
+		throw new AskUserValidationError(`${where} is a "${kind}" question and must not have "options".`);
 	}
-	const rawOptionList = rawOptions ?? [];
-	if (rawOptionList.length > MAX_OPTIONS) {
-		throw new AskUserValidationError(`${where} has more than ${MAX_OPTIONS} options.`);
-	}
-
-	const options: AskUserOption[] = [];
-	const seen = new Set<string>();
-	rawOptionList.forEach((rawOption, position) => {
-		const option = readOption(rawOption, where, position);
-		if (seen.has(option.label)) {
-			warnings.push(`${where} has a duplicate option "${option.label}"; de-duplicated.`);
-			return;
-		}
-		seen.add(option.label);
-		options.push(option);
-	});
-
-	// When `kind` is omitted it is inferred from `options`: present ⇒ `single`,
-	// absent ⇒ `input`. `multi` is only ever explicit.
+	const options = readOptions(value.options, where, warnings);
 	if (kind === undefined) kind = options.length > 0 ? "single" : "input";
-	if (kind !== "input" && options.length === 0) {
-		throw new AskUserValidationError(`${where} is a "${kind}" question but has no options.`);
+	if ((kind === "single" || kind === "multi") && options.length === 0) throw new AskUserValidationError(`${where} is a "${kind}" question but has no options.`);
+	if (kind !== "simple-form" && value.fields !== undefined) throw new AskUserValidationError(`${where} is a "${kind}" question and must not have "fields".`);
+
+	const fields: NormalizedFormField[] = [];
+	if (kind === "simple-form") {
+		if (value.default !== undefined) throw new AskUserValidationError(`${where} simple-form uses field defaults and must not have a top-level "default".`);
+		if (!Array.isArray(value.fields)) throw new AskUserValidationError(`${where} simple-form must have a "fields" array.`);
+		if (value.fields.length === 0) throw new AskUserValidationError(`${where} simple-form must have at least 1 field.`);
+		if (value.fields.length > MAX_FORM_FIELDS) throw new AskUserValidationError(`${where} has more than ${MAX_FORM_FIELDS} fields.`);
+		const names = new Set<string>();
+		value.fields.forEach((entry, fieldIndex) => {
+			const field = readFormField(entry, where, fieldIndex, warnings);
+			if (names.has(field.name)) throw new AskUserValidationError(`${where} has duplicate field name "${field.name}".`);
+			names.add(field.name);
+			fields.push(field);
+		});
+	} else if (kind === "bool") {
+		if (value.default !== undefined && typeof value.default !== "boolean") throw new AskUserValidationError(`${where} bool default must be a boolean.`);
+	} else if (value.default !== undefined && typeof value.default !== "string") {
+		throw new AskUserValidationError(`${where} default must be a string.`);
 	}
 
-	const question: AskUserQuestion = { title, kind };
+	const question: ParsedQuestion = {
+		title,
+		kind,
+		options: kind === "input" ? [] : options,
+		hasDefault: value.default !== undefined,
+		fields,
+	};
 	const prompt = optionalText(value.prompt, `${where} prompt`, LIMITS.prompt);
 	if (prompt !== undefined) question.prompt = prompt;
-	if (kind === "input") {
-		delete question.options;
-	} else {
-		question.options = options;
-	}
 	const id = optionalQuestionId(value.id, where);
 	if (id) question.id = id;
-	const fallback = optionalText(value.default, `${where} default`, LIMITS.defaultValue);
-	if (fallback !== undefined) question.default = fallback;
+	if (value.default !== undefined) {
+		if (typeof value.default === "string" && value.default.length > LIMITS.defaultValue) throw new AskUserValidationError(`${where} default exceeds the ${LIMITS.defaultValue}-character limit.`);
+		question.default = value.default as string | boolean;
+	}
 	return { question, warnings };
 }
 
 function readDisplayMode(value: unknown): "overlay" | "inline" {
 	if (value === undefined) return "overlay";
-	if (value !== "overlay" && value !== "inline") {
-		throw new AskUserValidationError('displayMode must be "overlay" or "inline".');
-	}
+	if (value !== "overlay" && value !== "inline") throw new AskUserValidationError('displayMode must be "overlay" or "inline".');
 	return value;
 }
 
 function readTimeoutPerQuestionMs(value: unknown): number {
 	if (value === undefined) return DEFAULT_TIMEOUT_PER_QUESTION_MS;
-	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-		throw new AskUserValidationError("timeoutPerQuestionMs must be a non-negative finite number.");
-	}
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new AskUserValidationError("timeoutPerQuestionMs must be a non-negative finite number.");
 	return Math.floor(value);
 }
 
-/** Normalize and validate a request against the {@link AskUserParams} contract. */
+/** Normalize and validate a request against the exact tool/direct-call contract. */
 export function normalizeAskUserRequest(raw: unknown): { request: NormalizedRequest; warnings: string[] } {
 	if (!isRecord(raw)) throw new AskUserValidationError("Missing the questions array.");
-	for (const key of Object.keys(raw)) {
-		if (!REQUEST_FIELDS.includes(key as (typeof REQUEST_FIELDS)[number])) {
-			throw new AskUserValidationError(`Unknown field "${key}".`);
-		}
-	}
+	assertKnownKeys(raw, REQUEST_FIELDS, "Request");
 	const rawQuestions = raw.questions;
 	if (!Array.isArray(rawQuestions)) throw new AskUserValidationError("Missing the questions array.");
 	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 (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[] = [];
 	rawQuestions.forEach((rawQuestion, index) => {
-		const { question, warnings: questionWarnings } = readQuestion(rawQuestion, index);
-		warnings.push(...questionWarnings);
-
+		const parsed = readQuestion(rawQuestion, index);
+		warnings.push(...parsed.warnings);
+		const question = parsed.question;
 		let id = question.id ?? "";
 		if (id === "" || usedIds.has(id)) {
 			let candidate = `q${index + 1}`;
 			let suffix = 1;
-			while (usedIds.has(candidate)) {
-				candidate = `q${index + 1}_${suffix++}`;
-			}
+			while (usedIds.has(candidate)) candidate = `q${index + 1}_${suffix++}`;
 			id = candidate;
 		}
 		usedIds.add(id);
-
 		const normalized: NormalizedQuestion = {
 			id,
 			index,
 			title: question.title,
 			kind: question.kind,
-			options: question.options ?? [],
-			hasDefault: question.default !== undefined,
+			options: question.options,
+			hasDefault: question.hasDefault,
+			fields: question.fields,
 		};
 		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 header = optionalText(raw.header, "header", LIMITS.header);
-	const displayMode = readDisplayMode(raw.displayMode);
 	const timeoutPerQuestionMs = readTimeoutPerQuestionMs(raw.timeoutPerQuestionMs);
-
 	const request: NormalizedRequest = {
 		questions,
-		displayMode,
+		allowFreeText,
+		displayMode: readDisplayMode(raw.displayMode),
 		timeoutPerQuestionMs,
 		totalTimeoutMs: timeoutPerQuestionMs * questions.length,
 	};
+	const header = optionalText(raw.header, "header", LIMITS.header);
 	if (header !== undefined) request.header = header;
 	return { request, warnings };
 }