@cspeach/cli 1.0.0 → 1.1.0

package/dist/tools/approval.js

@@ -10,6 +10,10 @@ import { maybeShowAutoApproveNag } from '../approvals/approval-prompt.js';
 import { renderAdvisoryProposal, } from '../approvals/advisory-render.js';
 import { promptAdvisory } from '../approvals/advisory-prompt.js';
 import { markPlanGateApproved } from '../repl/rule8-detector.js';
+import { getEffectiveWriteMode } from '../repl/mode-cycle.js';
+import { getCurrentTransport } from '../repl/current-transport.js';
+import { displayTransport } from '../approvals/op-labels.js';
+import { isGuardedRunActive, getCurrentPhaseWrites, notePlanDeviation, PLAN_DEVIATION_DETAIL, } from '../commands/plan-gate.js';
 /**
  * Advisory-only replacement for the per-change approval gauntlet.
  *
@@ -65,6 +69,42 @@ export async function handleAdvisoryApproval(args, _ctx) {
         }),
     };
 }
+/**
+ * §6 escalation exception — the infra base-object TYPE CODES a no-write/design
+ * phase (writes:false) may self-create under abap-plan rule 4a. These are the
+ * ADT type codes the model puts in `request_approval` `changes[].type`:
+ *   - DEVC — package   (sap_create_object type DEVC)
+ *   - CTS  — transport (sap_transport_create surfaces as {op:'create',type:'CTS'})
+ *
+ * §6's third member — number range — is intentionally ABSENT: the
+ * sap_number_range_intervals tool is a STUB (registered as "do not call", no
+ * ADT write), so a number-range op never reaches request_approval. Adding a
+ * marker for it would be dead code. Add its type code here if/when that tool
+ * ships and starts flowing through the approval gate.
+ *
+ * DUPLICATION NOTE (deliberate, for a follow-up): the AUDIT side enforces the
+ * SAME set in plan-audit.ts (PLAN_AUDIT_PROMPT_CONTRACT §6) — but as PROSE in
+ * an LLM prompt ("DEVC (package), transport, or number range"), not code. There
+ * is no clean seam to share a predicate because one enforcement layer is a
+ * natural-language contract and the other is TypeScript. The two must be kept
+ * in sync by hand; this comment and the audit prose both name the same set.
+ */
+const INFRA_BASE_OBJECT_TYPES = new Set(['DEVC', 'CTS']);
+/**
+ * TRUE iff EVERY change is a pure infra base-object CREATE — the sanctioned 4a
+ * self-create escalation (§6/§7.2). Tightness is the safety property: a single
+ * non-infra change (a CLAS/DDLS/… deliverable), any non-create op, or an empty
+ * set makes this FALSE, so the writes:false backstop denies it (the correct
+ * out-of-lane B3 case). Type is normalized (trim + upper) to match how the
+ * model may spell it; op is restricted to 'create' because 4a sanctions
+ * self-CREATE only (a transport release / package delete is not an escalation).
+ */
+function isPureInfraEscalation(changes) {
+    return (!!changes &&
+        changes.length > 0 &&
+        changes.every((c) => c.op === 'create' &&
+            INFRA_BASE_OBJECT_TYPES.has((c.type ?? '').trim().toUpperCase())));
+}
 registerTool({
     name: 'request_approval',
     description: 'Request user approval for one or more SAP mutations. Returns approval_ids (one per change) to be passed as approval_id on matching mutating tool calls.',
@@ -83,7 +123,8 @@ registerTool({
                         op: { type: 'string', enum: ['create', 'modify', 'delete', 'activate', 'release'] },
                         object: { type: 'string' },
                         type: { type: 'string' },
-                        diff: { type: 'string', description: 'Unified diff for modify/create ops (optional)' },
+                        diff: { type: 'string', description: 'For a CREATE op this MUST be the exact, complete source that will be written — verbatim, character-for-character, NOT a description, summary, or paraphrase. It is shown to the developer in the approval box as the exact thing they are approving, so a one-line summary here means they approve a write they cannot inspect. For a MODIFY op, the real unified diff of the change (again verbatim, not a description).' },
+                        package: { type: 'string', description: 'Target package (development class) for the object, if known — shown on the approval box' },
                     },
                     required: ['op', 'object', 'type'],
                 },
@@ -92,11 +133,52 @@ registerTool({
         required: ['summary', 'risk', 'changes'],
     },
     handler: async (args, ctx) => {
+        // Task 10 (agentic-flow, 2026-07-03) — deviation backstop, BEFORE the
+        // approval flow renders anything (including the advisory prompt, which
+        // would hang an unattended chain just the same). In guarded mode the
+        // write-phase stops are computed from the plan's DECLARED writes field;
+        // a phase that declared writes:false and requests a write approval
+        // anyway is a plan deviation: DENY without prompting, raise the flag
+        // the post-turn chain (plan-chain.ts) turns into blocked + STOPPED.
+        // Same error mechanism as the headless fail-fast below: a structured
+        // error RESULT so the model wraps up gracefully instead of writing.
+        // Guarded-gated: step mode / outside phases are byte-identical.
+        //
+        // §6/§7.2 escalation exception (audit redesign, Task 4): a PURE infra
+        // base-object create (DEVC / transport) under writes:false is the
+        // sanctioned rule-4a self-create. The very act of routing through
+        // request_approval IS the user-consent gate, so it must NOT be denied here
+        // — fall through to the normal approval flow (which prompts the user, whose
+        // approval is the 4a consent). Guarded-mode clients could otherwise never
+        // run 4a: this backstop blocks it BEFORE the audit even runs. TIGHT: the
+        // exception fires only when EVERY change is infra; a deliverable
+        // (CLAS/DDLS/…) or a mixed set still denies (correct out-of-lane B3).
+        if (isGuardedRunActive() &&
+            getCurrentPhaseWrites() === false &&
+            !isPureInfraEscalation(args.changes)) {
+            const detail = PLAN_DEVIATION_DETAIL;
+            notePlanDeviation(detail);
+            console.error(chalk.red('plan deviation: this phase declared writes:false but requested a write approval — ' +
+                'the write is denied and the guarded chain will stop.'));
+            return {
+                content: JSON.stringify({
+                    error: 'plan_deviation',
+                    detail,
+                }),
+                is_error: true,
+            };
+        }
         let cfg = await loadConfig();
+        // Task 2 (ux-wave1) — the approval flow reads the EFFECTIVE write mode:
+        // config overlaid by the session override, clamped to the active alias's
+        // role ceiling (prd pins advisory-only; qas caps at approval-gated). With
+        // no role configured and no session override this is exactly
+        // cfg.write_mode — byte-identical behavior.
+        const role = cfg.sap[ctx.sapAlias]?.role;
         // Advisory-only short-circuit — never mint approval_ids.
         // The developer applies the change manually in ADT; the AI gets an
         // ai_directive telling it not to attempt any SAP write tools.
-        if (cfg.write_mode === 'advisory-only') {
+        if (getEffectiveWriteMode(cfg.write_mode, role) === 'advisory-only') {
             return handleAdvisoryApproval(args, { sapAlias: ctx.sapAlias });
         }
         let sapCfg = cfg.sap[ctx.sapAlias];
@@ -107,10 +189,36 @@ registerTool({
         const changes = args.changes;
         const declared = args.risk;
         const eff = effectiveRisk(declared, changes, riskCtx);
+        // Transport shown on the approval surfaces — resolved PER OP to mirror
+        // what the write tools will actually do (I2, 2026-07-05 review):
+        // create-family tools fall back to the session transport, so the box may
+        // show it; modify/delete tools do NOT (resolveWriteTransport uses args
+        // only + owning-TR override), so those boxes show only an explicit
+        // request transport; activate/release take no transport at all. See
+        // displayTransport in approvals/op-labels.ts. The plan gate is a batch
+        // summary: session fallback applies only when the batch contains a
+        // create (the only op it is true for).
+        const sessionTransport = getCurrentTransport();
+        const planGateTransport = args.transport
+            ?? (changes.some((c) => c.op === 'create') ? sessionTransport ?? undefined : undefined);
+        // Task 6 (agentic-flow, 2026-07-03) — guarded plan chains disable
+        // auto-approve entirely: the user's auto_approve consent was given for
+        // hand-driven turns, not for phases the harness auto-dispatched. When the
+        // flag is active, skip the nag (it only advertises auto-approve) and fall
+        // through to the interactive prompts below. Flag off ⇒ this whole block
+        // is a no-op and behaviour stays byte-identical (skill-mode compat).
+        const guardedRun = isGuardedRunActive();
+        // Task 3 (ux-wave1) — qas systems never auto-approve: the role's promise
+        // is "no unattended writes", and a pre-configured auto_approve would mint
+        // silently. Treat auto_approve as 'never' on a qas alias — composes with
+        // the guarded-run skip above, same skip points, ladder order unchanged.
+        // (prd needs nothing here: the advisory clamp already prevents minting.)
+        const qasNoAutoApprove = role === 'qas';
         // Progressive-disclosure: offer to upgrade never→low on first low-risk
         // encounter. B5: skipped in headless — the nag's raw-mode keypress wait
-        // would hang on piped/closed stdin just like any other prompt.
-        if (!isHeadless()) {
+        // would hang on piped/closed stdin just like any other prompt. Skipped on
+        // qas too: the nag only advertises auto-approve, which qas disables.
+        if (!isHeadless() && !guardedRun && !qasNoAutoApprove) {
             await maybeShowAutoApproveNag({ sapAlias: ctx.sapAlias, effectiveRisk: eff.level });
             // Refresh cfg so this approval benefits from a just-enabled auto_approve.
             cfg = await loadConfig();
@@ -118,7 +226,7 @@ registerTool({
             riskCtx.autoApprovePolicy = sapCfg?.auto_approve ?? 'never';
         }
         // Auto-approve caps — never auto-approve at high, cap change count per risk level.
-        const autoApproveAllowed = ((sapCfg?.auto_approve === 'low' && eff.level === 'low' && changes.length <= 5) ||
+        const autoApproveAllowed = !guardedRun && !qasNoAutoApprove && ((sapCfg?.auto_approve === 'low' && eff.level === 'low' && changes.length <= 5) ||
             (sapCfg?.auto_approve === 'medium' && (eff.level === 'low' || eff.level === 'medium') && changes.length <= 2));
         if (autoApproveAllowed) {
             const ids = [];
@@ -170,7 +278,7 @@ registerTool({
         // gate. Cancel rejects the whole plan.
         let skipPerChangeGates = false;
         if (changes.length > 1) {
-            const mode = await renderPlanGate(args.summary, changes, args.transport, eff);
+            const mode = await renderPlanGate(args.summary, changes, planGateTransport, eff);
             if (mode === 'cancel') {
                 return {
                     content: JSON.stringify({
@@ -223,7 +331,7 @@ registerTool({
                 outcome = { approved: false, reason: 'sibling_write_skipped' };
             }
             else {
-                outcome = await renderPerChangeApprovalV3(c, eff, args.transport);
+                outcome = await renderPerChangeApprovalV3(c, eff, displayTransport(c.op, args.transport, sessionTransport));
             }
             if (outcome.approved) {
                 if (c.op === 'modify' || c.op === 'create')

package/dist/tools/ask-question.js

@@ -13,13 +13,18 @@
  * structurally reliable: the API validates the input schema, no parsing
  * needed, no streaming ambiguity.
  *
- * Renders:
+ * Renders (v1 single-question shape):
  *   - kind=text: prompt for free-form answer
  *   - kind=choice: arrow-key pick-one via inquirer select
  *   - kind=multi: space-to-toggle via inquirer checkbox
  *
  * Returns JSON `{ answer, id, kind, cancelled? }` so the LLM knows what
  * it just got back and can cross-reference the question id.
+ *
+ * UX Wave 2 — v2 batched `questions` shape (up to 4 related questions in
+ * ONE call): Ink renders a single <AskForm> (Task 2); classic runs the
+ * questions as a sequential inquirer flow (Task 3). Both return
+ * `{ formId, answers: [{id, answer, custom?}], cancelled? }`.
  */
 import chalk from 'chalk';
 import { registerTool } from './index.js';
@@ -27,6 +32,92 @@ import { input, select, checkbox } from '@inquirer/prompts';
 import { withInquirer } from '../repl/inquirer-guard.js';
 import { shouldUseInk, isHeadless } from '../renderer/tty.js';
 import { askQuestionEmitter } from '../ui/ask-question-emitter.js';
+/** Chip labels in the v2 form are capped at 12 chars (brief-binding). */
+const HEADER_MAX_CHARS = 12;
+/**
+ * UX Wave 2 / Task 1 — validation failure for a v2 `questions` payload.
+ * The handler converts this into an error RESULT (`ask_form_invalid`),
+ * never a throw across the tool boundary.
+ */
+export class AskFormValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AskFormValidationError';
+    }
+}
+function normalizeOptions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((o) => {
+        const opt = { value: String(o.value), label: String(o.label) };
+        if (o.description != null)
+            opt.description = String(o.description);
+        if (o.recommended === true)
+            opt.recommended = true;
+        return opt;
+    });
+}
+/**
+ * UX Wave 2 / Task 1 — normalize EVERY ask_question call (v1 single-question
+ * or v2 `questions` batch) into the one internal AskFormRequest shape.
+ *
+ * v1 mapping: kind=multi → multiSelect; kind=text (or no choices) →
+ * freeText with empty options; header defaults to the question id.
+ * v2 mapping is 1:1; headers (explicit or defaulted from id) are truncated
+ * to 12 chars for the chip row.
+ *
+ * IMPORTANT: normalization does NOT decide routing. The handler routes
+ * v1-shaped ORIGINALS through the untouched v1 code paths (byte-compat by
+ * construction); only genuine v2 calls reach the form machinery.
+ *
+ * Throws AskFormValidationError on an invalid v2 payload (0 or >4
+ * questions, entries missing id/question) — the handler converts that to
+ * an `ask_form_invalid` error result. Exported for tests.
+ */
+export function normalizeAskInput(args) {
+    const header = (q) => String(q.header != null && String(q.header).length > 0 ? q.header : q.id)
+        .slice(0, HEADER_MAX_CHARS);
+    if (Array.isArray(args?.questions)) {
+        const raw = args.questions;
+        if (raw.length < 1 || raw.length > 4) {
+            throw new AskFormValidationError(`\`questions\` must contain 1 to 4 items (got ${raw.length}). ` +
+                'Never ask more than 4 at once — split into a follow-up call instead.');
+        }
+        const questions = raw.map((q, i) => {
+            if (q == null || typeof q !== 'object' || q.id == null || q.question == null) {
+                throw new AskFormValidationError(`questions[${i}] is invalid — each entry needs at least { id, question }.`);
+            }
+            const options = normalizeOptions(q.options);
+            return {
+                id: String(q.id),
+                question: String(q.question),
+                context: q.context != null ? String(q.context) : undefined,
+                header: header({ id: String(q.id), header: q.header }),
+                multiSelect: q.multiSelect === true,
+                freeText: options.length === 0,
+                options,
+            };
+        });
+        const formId = args.id != null ? String(args.id) : questions.map((q) => q.id).join('+');
+        return { formId, questions };
+    }
+    // v1 single-question shape → one-question form.
+    const id = String(args.id);
+    const kind = args.kind;
+    const options = kind === 'text' ? [] : normalizeOptions(args.choices);
+    return {
+        formId: id,
+        questions: [{
+                id,
+                question: String(args.question),
+                context: args.context != null ? String(args.context) : undefined,
+                header: header({ id, header: undefined }),
+                multiSelect: kind === 'multi',
+                freeText: kind === 'text' || options.length === 0,
+                options,
+            }],
+    };
+}
 /**
  * Label heuristic for rule 2 of pickHeadlessChoices: a string counts as
  * "recommended" only when it contains the word AND that word is not part of
@@ -76,7 +167,7 @@ export function pickHeadlessChoices(kind, choices) {
 }
 registerTool({
     name: 'ask_question',
-    description: "Ask the user a clarifying question and get their answer. Use this for ANY user-decision point in a skill conversation — object names, design choices, approval checkpoints, etc. The CLI renders a formatted prompt, waits for the user's answer, and returns it as the tool result. Prefer this over emitting a text question — it is the only reliable mechanism for mid-turn user interaction.",
+    description: "Ask the user a clarifying question and get their answer. Use this for ANY user-decision point in a skill conversation — object names, design choices, approval checkpoints, etc. The CLI renders a formatted prompt, waits for the user's answer, and returns it as the tool result. Prefer this over emitting a text question — it is the only reliable mechanism for mid-turn user interaction. When you have MULTIPLE related questions, batch up to 4 into ONE call via `questions` — the user answers them in a single form. Never ask more than 4 at once; never split related questions across calls.",
     isMutating: false,
     input_schema: {
         type: 'object',
@@ -114,10 +205,220 @@ registerTool({
                     required: ['value', 'label'],
                 },
             },
+            questions: {
+                type: 'array',
+                minItems: 1,
+                maxItems: 4,
+                description: 'v2 batched form — ask up to 4 related questions in ONE call; the user answers them all in a single form. When `questions` is provided, the single-question fields (question/kind/choices) are ignored; a top-level `id` (if given) names the form. Omit `options` on a question for a free-text answer.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string', description: 'Short stable identifier for this question.' },
+                        question: { type: 'string', description: 'The question text. Keep concise — max ~200 chars.' },
+                        context: { type: 'string', description: 'Optional one-line explanation of why this matters.' },
+                        header: {
+                            type: 'string',
+                            description: 'Optional chip label for the form header row (max 12 chars). Defaults to the question id.',
+                        },
+                        multiSelect: {
+                            type: 'boolean',
+                            description: 'true = the user may pick several options; false/omitted = pick exactly one.',
+                        },
+                        options: {
+                            type: 'array',
+                            description: 'Answer options. Omit entirely for a free-text question.',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    value: { type: 'string', description: 'Machine value returned if the user picks this.' },
+                                    label: { type: 'string', description: 'Human-readable label shown in the form.' },
+                                    description: { type: 'string', description: 'Optional secondary line, rendered dim under the label.' },
+                                    recommended: {
+                                        type: 'boolean',
+                                        description: 'Mark the option you would recommend. Auto-picked in headless runs.',
+                                    },
+                                },
+                                required: ['value', 'label'],
+                            },
+                        },
+                    },
+                    required: ['id', 'question'],
+                },
+            },
         },
-        required: ['id', 'question', 'kind'],
+        // v2: `questions` replaces the single-question fields, so nothing can be
+        // unconditionally required any more. Single-question calls still need
+        // id/question/kind (per their descriptions); batched calls need `questions`.
+        required: [],
     },
     handler: async (args, _ctx) => {
+        // UX Wave 2 / Task 1 — v2 batched form branch. Routing rule (byte-compat
+        // by construction): ONLY calls that actually send a `questions` array
+        // enter the form machinery; every v1-shaped original falls through to
+        // the untouched v1 code paths below — identical prompts, results, and
+        // headless behavior, guaranteed structurally rather than by re-testing.
+        if (Array.isArray(args.questions)) {
+            let form;
+            try {
+                form = normalizeAskInput(args);
+            }
+            catch (err) {
+                if (err instanceof AskFormValidationError) {
+                    return {
+                        content: JSON.stringify({ error: 'ask_form_invalid', message: err.message }),
+                        is_error: true,
+                    };
+                }
+                throw err;
+            }
+            // Headless v2 — fully implemented NOW (per-question policy, mirroring
+            // the v1 B5 rules): optioned questions auto-pick with the fired rule
+            // reported; a free-text question inside a batch becomes a per-question
+            // `headless_unanswerable` entry but NEVER fails the whole form.
+            if (isHeadless()) {
+                const answers = form.questions.map((q) => {
+                    if (!q.freeText && q.options.length > 0) {
+                        const { picked, rule } = pickHeadlessChoices(q.multiSelect ? 'multi' : 'choice', q.options);
+                        const answer = picked.map((c) => c.value).join(',');
+                        console.error(chalk.dim(`headless: auto-answered '${q.question}' → '${answer}' (${rule})`));
+                        return { id: q.id, answer, auto_answered: true, auto_answer_rule: rule };
+                    }
+                    console.error(chalk.yellow(`headless: cannot answer free-text question '${q.question}' — ` +
+                        'provide this detail in the prompt or run interactively.'));
+                    return { id: q.id, answer: null, error: 'headless_unanswerable' };
+                });
+                return {
+                    content: JSON.stringify({
+                        formId: form.formId,
+                        headless: true,
+                        answers,
+                        note: 'Headless run: the user did not actually answer this form. Optioned questions ' +
+                            'were auto-selected (rule reported per answer); free-text questions are ' +
+                            'unanswerable (answer: null). Proceed with sensible assumptions and clearly ' +
+                            'note them in your final output.',
+                    }),
+                };
+            }
+            // Interactive v2, INK path — wired by Task 2: requestForm emits the
+            // discriminated form request, App routes it to <AskForm> (v1 requests
+            // keep rendering the untouched AskQuestionModal), and the resolved
+            // AskFormResult comes back here. Cancel (Esc / no listener) mirrors
+            // the v1 cancel contract: empty answers + cancelled: true.
+            if (shouldUseInk()) {
+                const result = await askQuestionEmitter.requestForm(form);
+                if (result.cancelled) {
+                    return {
+                        content: JSON.stringify({ formId: form.formId, answers: [], cancelled: true }),
+                    };
+                }
+                return {
+                    content: JSON.stringify({ formId: result.formId, answers: result.answers }),
+                };
+            }
+            // Interactive v2, CLASSIC path — Task 3 flag-day (this replaces the
+            // Task-1 `ask_form_not_wired` stub; Task 2 wired the Ink side).
+            // Sequential inquirer prompts, one per question IN FORM ORDER, each
+            // under a dim `form i/n · <header>` progress prefix and built from
+            // the v1 building blocks: select + "(type a custom answer)" escape
+            // for pick-one, checkbox for multiSelect, input for freeText.
+            //
+            // Result shapes mirror the Ink AskForm EXACTLY (Task-2 contract):
+            //   success → { formId, answers: [{ id, answer, custom? }] }  — in
+            //             question order; custom:true ONLY for the escape.
+            //   Esc anywhere (ExitPromptError) → { formId, answers: [],
+            //             cancelled: true } — the WHOLE form cancels, partial
+            //             answers are discarded (non-error content, v1 cancel
+            //             semantics).
+            // Empty submissions re-prompt, mirroring the Ink form ignoring
+            // empty submits — a committed form answer is never empty.
+            {
+                const total = form.questions.length;
+                const answers = [];
+                try {
+                    for (let i = 0; i < total; i++) {
+                        const q = form.questions[i];
+                        console.log('');
+                        console.log(chalk.dim(`form ${i + 1}/${total} · ${q.header ?? q.id}`));
+                        console.log(chalk.bold(q.question));
+                        if (q.context)
+                            console.log(chalk.dim(q.context));
+                        console.log('');
+                        let entry = null;
+                        while (entry === null) {
+                            if (!q.freeText && !q.multiSelect && q.options.length > 0) {
+                                // Pick-one — same select + custom-escape recipe as v1.
+                                const CUSTOM = '__cspeach_custom__';
+                                const picked = await withInquirer(() => select({
+                                    message: 'Pick an answer:',
+                                    choices: [
+                                        ...q.options.map((c) => ({ value: c.value, name: c.label })),
+                                        { value: CUSTOM, name: chalk.dim('(type a custom answer)') },
+                                    ],
+                                }));
+                                if (picked === CUSTOM) {
+                                    const raw = (await withInquirer(() => input({ message: 'Your answer:' }))).trim();
+                                    if (raw.length === 0)
+                                        continue; // empty custom — re-prompt
+                                    entry = { id: q.id, answer: raw, custom: true };
+                                }
+                                else {
+                                    entry = { id: q.id, answer: picked };
+                                }
+                            }
+                            else if (q.multiSelect && q.options.length > 0) {
+                                const picked = await withInquirer(() => checkbox({
+                                    message: 'Pick one or more (space to toggle, enter to confirm):',
+                                    choices: q.options.map((c) => ({ value: c.value, name: c.label })),
+                                }));
+                                if (picked.length === 0)
+                                    continue; // nothing toggled — re-prompt
+                                entry = { id: q.id, answer: picked.join(',') };
+                            }
+                            else {
+                                // freeText (options empty — including multiSelect without
+                                // options, which normalization degrades to freeText).
+                                const raw = (await withInquirer(() => input({ message: 'Your answer:' }))).trim();
+                                if (raw.length === 0)
+                                    continue;
+                                entry = { id: q.id, answer: raw };
+                            }
+                        }
+                        console.log(chalk.dim(`  → ${entry.answer}`));
+                        answers.push(entry);
+                    }
+                }
+                catch (err) {
+                    const name = err?.name;
+                    if (name === 'ExitPromptError') {
+                        return {
+                            content: JSON.stringify({ formId: form.formId, answers: [], cancelled: true }),
+                        };
+                    }
+                    throw err;
+                }
+                return { content: JSON.stringify({ formId: form.formId, answers }) };
+            }
+        }
+        // UX Wave 2 / Task 1 review fix — malformed v1 shape guard. With
+        // `required: []` on the schema (needed so `questions`-only calls pass
+        // API validation) a call like `{id:'x'}` with no question/kind/questions
+        // would reach the v1 paths: headless would embed the literal question
+        // "undefined" in its error, and interactive would render a bold prompt
+        // reading `undefined` and BLOCK the loop on user input. Reject it here
+        // with a structured error result instead. Unreachable for any
+        // previously-valid v1 call (id/question/kind used to be schema-required)
+        // ⇒ zero byte-compat exposure.
+        if (args.id == null || args.question == null || args.kind == null) {
+            return {
+                content: JSON.stringify({
+                    error: 'ask_question_invalid',
+                    message: 'Invalid ask_question call: the single-question shape requires `id`, `question`, ' +
+                        'and `kind` ("text" | "choice" | "multi"). To ask several related questions at ' +
+                        'once, use the `questions` array (1-4 items, each { id, question, ... }) instead.',
+                }),
+                is_error: true,
+            };
+        }
         const id = String(args.id);
         const question = String(args.question);
         const context = args.context ? String(args.context) : undefined;