@yagni-app/code 0.3.4 → 1.0.0

package/dist/extension/askUserQuestionTool.js

@@ -0,0 +1,621 @@
+/**
+ * ask_user_question — structured human questions.
+ *
+ * Adapts Claude Code's `AskUserQuestion` tool into yagni-code: when the model
+ * genuinely needs a human (an architectural fork, a product-intent call with
+ * no recorded answer), it poses a closed question — 2-4 mutually exclusive
+ * options, each with a description explaining the tradeoff and an optional
+ * preview — and gets back a clean machine-readable answer instead of parsing
+ * free text.
+ *
+ * Rendering is via `ctx.ui.custom` (not the bare `ctx.ui.select` used for the
+ * permission "don't ask again" flow) so each option can show its description
+ * and, when any option carries a preview, a two-column layout surfaces the
+ * focused option's preview on the right. "Other" is a trailing editable row
+ * (always last, no label) whose text is the answer on Enter — no mode switch.
+ *
+ * No backend changes; no new dependencies. Only pi's TUI primitives. When
+ * there is no interactive UI (print / headless), execute() returns a short
+ * message so the tool never hangs waiting for a keyboard.
+ */
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { logAskQuestion } from "./diagnostics.js";
+const TOOL_NAME = "ask_user_question";
+/** Claude mirrors this as ASK_USER_QUESTION_TOOL_CHIP_WIDTH. */
+const CHIP_WIDTH = 12;
+/** Same fail-closed ceiling as the permission-gate ask. */
+const ASK_TIMEOUT_MS = 120_000;
+/** Sentinel value representing the "Other" row in the multi-select toggle set. */
+const OTHER_KEY = "__other__";
+/** Label on the multi-select submit row (mirrors Claude's Submit button). */
+const SUBMIT_LABEL = "Submit";
+const optionParameters = Type.Object({
+    label: Type.String({
+        description: "The display text for this option that the user sees and selects. Concise (1-5 words) and clearly describes the choice.",
+    }),
+    description: Type.String({
+        description: "Explanation of what this option means or what happens if chosen. Provides context about the trade-off.",
+    }),
+    preview: Type.Optional(Type.String({
+        description: "Optional concrete content rendered when this option is focused — a mockup, code snippet, diagram, or config example the user needs to compare. Only used for single-select questions.",
+    })),
+});
+const questionParameters = Type.Object({
+    question: Type.String({
+        description: 'The complete question. Clear, specific, and end with a question mark. Example: "Which library should we use for date formatting?" If multiSelect is true, phrase it accordingly.',
+    }),
+    header: Type.String({
+        maxLength: CHIP_WIDTH,
+        description: `Very short label shown as a chip/tag (max ${CHIP_WIDTH} chars). Examples: "Auth method", "Approach".`,
+    }),
+    options: Type.Array(optionParameters, { minItems: 2, maxItems: 4 }),
+    multiSelect: Type.Optional(Type.Boolean({
+        default: false,
+        description: "Set to true to allow the user to select multiple options instead of just one. Use when choices are not mutually exclusive.",
+    })),
+});
+const parameters = Type.Object({
+    questions: Type.Array(questionParameters, { minItems: 1, maxItems: 4 }),
+});
+const PROMPT_SNIPPET = "ask_user_question: pose a structured multiple-choice question (2-4 options with tradeoffs) to the user and get back a clean machine-readable answer.";
+const PROMPT_GUIDELINES = [
+    "Use ask_user_question when you genuinely need a human decision during execution — an architectural fork, a product-intent call, or a choice between approaches — and the answer is not already recorded (check ask_yagni first).",
+    "Enumerate 2-4 distinct, mutually exclusive options, each with a description explaining its tradeoff. Do not ask a vague open question.",
+    "Never add an 'Other' option yourself — the UI always offers a trailing free-text row automatically.",
+    "If you recommend a specific option, make it the first one and append '(Recommended)' to its label.",
+    "Do not use this tool for feedback like 'does the plan look good?' — ask a real choice with real options.",
+];
+/**
+ * Whether any option in the question has a preview. Drives the two-column
+ * layout (Claude switches to side-by-side only when previews exist).
+ */
+function hasPreview(q) {
+    return q.options.some((o) => o.preview !== undefined);
+}
+/**
+ * Clamp a rendered line to the terminal width. pi hard-crashes on lines wider
+ * than the terminal; every line we emit must be within bounds.
+ */
+function clampLine(line, width) {
+    const safeWidth = Math.max(0, width);
+    return visibleWidth(line) > safeWidth ? truncateToWidth(line, safeWidth, "") : line;
+}
+/** A harmless Component returned when the dialog has already settled. */
+const NOOP_COMPONENT = {
+    invalidate() { },
+    render() {
+        return [];
+    },
+};
+/** Strip raw control/escape sequences so pasted content can't corrupt the TUI. */
+function sanitize(text) {
+    // Keep only printable chars, newline, and tab-ish; drop C0/C1 controls and
+    // ANSI/OSC escape sequences.
+    return text
+        .replace(/(?:\[[0-?]*[ -\/]*[@-~]|\][^\u0007]*(?:\u0007|\u001b\\))|[@-_]/g, "")
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+}
+/**
+ * Interactive selector for ONE question, rendered via `ctx.ui.custom`.
+ *
+ * Follows Claude Code's layout exactly:
+ * - No previews → one-column with numbered options (1., 2., ...) and description
+ *   indented under the label text. The "Other" row is an inline input field.
+ * - With previews → two-column: options left, focused option's preview right.
+ *   No "Other" row (Claude omits it; we keep it for parity with the tool spec).
+ */
+class QuestionComponent {
+    q;
+    qIndex;
+    theme;
+    keybindings;
+    onFinish;
+    selectedIndex = 0;
+    toggled = new Set();
+    closed = false;
+    otherValue = "";
+    constructor(q, qIndex, theme, keybindings, onFinish) {
+        this.q = q;
+        this.qIndex = qIndex;
+        this.theme = theme;
+        this.keybindings = keybindings;
+        this.onFinish = onFinish;
+    }
+    /** Single exit: mark closed so no post-resolution keystroke is processed, then resolve. */
+    finish(r) {
+        this.closed = true;
+        this.onFinish(r);
+    }
+    get multi() {
+        return this.q.multiSelect === true;
+    }
+    /** Index of the trailing "Other" editable row. */
+    get otherIndex() {
+        return this.q.options.length;
+    }
+    /** Index of the multi-select Submit row (after "Other"). */
+    get submitIndex() {
+        return this.q.options.length + 1;
+    }
+    /** Largest navigable cursor index. */
+    get maxIndex() {
+        return this.multi ? this.submitIndex : this.otherIndex;
+    }
+    focusedOption() {
+        return this.q.options[this.selectedIndex];
+    }
+    /** Whether the "Other" row counts as selected (multi-select auto-check rule). */
+    otherSelected() {
+        return this.multi && this.toggled.has(OTHER_KEY);
+    }
+    /** Add/remove a value from the multi-select toggle set. */
+    toggleValue(v) {
+        if (this.toggled.has(v))
+            this.toggled.delete(v);
+        else
+            this.toggled.add(v);
+    }
+    /**
+     * Multi-select rule mirroring Claude's `updateInputValue`: typing non-empty
+     * text auto-checks "Other"; emptying it back out un-checks it. Call on every
+     * edit to `otherValue`.
+     */
+    syncOtherToggle() {
+        if (this.otherValue.trim() !== "")
+            this.toggled.add(OTHER_KEY);
+        else
+            this.toggled.delete(OTHER_KEY);
+        logAskQuestion({ event: "other_toggle", checked: this.toggled.has(OTHER_KEY), otherLen: this.otherValue.length, qIndex: this.qIndex });
+    }
+    invalidate() {
+        // No cached render state; a full render is cheap.
+    }
+    render(width) {
+        const t = this.theme;
+        const safeWidth = Math.max(0, width);
+        const lines = [];
+        // Top border.
+        lines.push(t.fg("borderMuted", "─".repeat(safeWidth)));
+        // Header chip (inverse video, mirroring Claude's current-tab in the nav bar).
+        if (this.q.header) {
+            const chip = ` ${this.q.header} `;
+            lines.push(clampLine(t.bg("selectedBg", t.fg("accent", chip)), safeWidth));
+            lines.push("");
+        }
+        const heading = t.bold(this.q.question);
+        lines.push(...wrapTextWithAnsi(heading, Math.max(1, safeWidth - 2)).map((l) => clampLine(l, safeWidth)));
+        lines.push("");
+        if (hasPreview(this.q) && !this.multi) {
+            this.renderTwoColumn(lines, width, t);
+        }
+        else {
+            this.renderOneColumn(lines, width, t);
+        }
+        // Help line (mirrors Claude's footer guidance; no "Chat about this" row).
+        lines.push("");
+        const help = this.multi
+            ? "Enter to toggle · ↑/↓ to navigate · Enter on Submit to commit · Esc to cancel"
+            : "Enter to select · ↑/↓ to navigate · Esc to cancel";
+        lines.push(clampLine(t.fg("dim", `  ${help}`), safeWidth));
+        // Bottom border.
+        lines.push(t.fg("borderMuted", "─".repeat(safeWidth)));
+        return lines;
+    }
+    /**
+     * One-column layout (no previews). Matches Claude Code's `compact-vertical`:
+     * each option is `index. label`, description on the next line indented under
+     * the label text (not under the number).
+     */
+    renderOneColumn(lines, width, t) {
+        const maxIndexWidth = (this.q.options.length + 1).toString().length;
+        const indexPad = maxIndexWidth + 2; // Claude uses padEnd(maxIndexWidth + 2)
+        const descIndent = " ".repeat(indexPad + 2); // align under label text
+        this.q.options.forEach((opt, i) => {
+            const isSelected = i === this.selectedIndex;
+            const marker = this.multi
+                ? this.toggled.has(opt.label)
+                    ? t.fg("accent", "[x]")
+                    : "[ ]"
+                : isSelected
+                    ? t.fg("accent", "❯")
+                    : " ";
+            const indexText = `${i + 1}.`.padEnd(indexPad);
+            const label = isSelected ? t.fg("accent", opt.label) : opt.label;
+            lines.push(clampLine(`${marker} ${indexText}${label}`, width));
+            if (opt.description) {
+                lines.push(clampLine(t.fg("muted", descIndent + opt.description), width));
+            }
+        });
+        lines.push("");
+        this.renderOtherRow(lines, width, t, indexPad);
+        // Multi-select Submit row (after "Other"), mirroring Claude's button.
+        if (this.multi) {
+            lines.push("");
+            this.renderSubmitRow(lines, width, t);
+        }
+    }
+    /** The multi-select Submit row: selected → commits; Escape row is omitted. */
+    renderSubmitRow(lines, width, t) {
+        const isSelected = this.selectedIndex === this.submitIndex;
+        const marker = isSelected ? t.fg("accent", "❯") : " ";
+        const label = isSelected ? t.fg("accent", t.bold(SUBMIT_LABEL)) : t.bold(SUBMIT_LABEL);
+        lines.push(clampLine(` ${marker}   ${label}`, width));
+    }
+    /**
+     * Two-column layout (with previews). Matches Claude Code's `PreviewQuestionView`:
+     * left panel is a vertical numbered list, right panel shows the focused
+     * option's preview box + description.
+     */
+    renderTwoColumn(lines, width, t) {
+        const LEFT_PANEL_WIDTH = 30;
+        const GAP = 4;
+        const rightWidth = Math.max(20, width - LEFT_PANEL_WIDTH - GAP);
+        const maxIndexWidth = (this.q.options.length + 1).toString().length;
+        const indexPad = maxIndexWidth + 2;
+        // Build left panel lines: options list.
+        const leftLines = [];
+        this.q.options.forEach((opt, i) => {
+            const isSelected = i === this.selectedIndex;
+            const marker = isSelected ? t.fg("accent", "❯") : " ";
+            const indexText = `${i + 1}.`.padEnd(indexPad);
+            const label = isSelected ? t.fg("accent", opt.label) : opt.label;
+            leftLines.push(clampLine(`${marker} ${indexText}${label}`, LEFT_PANEL_WIDTH));
+        });
+        // Build right panel lines: preview box + description for focused option.
+        const rightLines = [];
+        const focused = this.focusedOption();
+        if (focused?.preview) {
+            rightLines.push(t.fg("mdCodeBlockBorder", "┌" + "─".repeat(rightWidth) + "┐"));
+            for (const raw of focused.preview.split("\n")) {
+                for (const wrapped of wrapTextWithAnsi(raw, rightWidth - 2)) {
+                    rightLines.push(t.fg("mdCodeBlock", "│ " + wrapped + " ".repeat(Math.max(0, rightWidth - 2 - visibleWidth(wrapped))) + " │"));
+                }
+            }
+            rightLines.push(t.fg("mdCodeBlockBorder", "└" + "─".repeat(rightWidth) + "┘"));
+        }
+        if (focused?.description) {
+            if (rightLines.length)
+                rightLines.push("");
+            rightLines.push(...wrapTextWithAnsi(t.fg("muted", focused.description), rightWidth));
+        }
+        // Merge left + right into side-by-side lines.
+        const maxRows = Math.max(leftLines.length, rightLines.length);
+        for (let r = 0; r < maxRows; r++) {
+            const left = leftLines[r] ?? "";
+            const right = rightLines[r] ?? "";
+            const leftPadded = left + " ".repeat(Math.max(0, LEFT_PANEL_WIDTH - visibleWidth(left)));
+            lines.push(clampLine(leftPadded + " ".repeat(GAP) + right, width));
+        }
+        // The "Other" row spans the full width (below the two-column area).
+        lines.push("");
+        this.renderOtherRow(lines, width, t, indexPad);
+    }
+    /**
+     * The trailing "Other" editable row. Always last, full width.
+     * Claude renders this as a proper input field inline in the list.
+     */
+    renderOtherRow(lines, width, t, indexPad) {
+        const isSelected = this.selectedIndex === this.otherIndex;
+        // Multi-select: a checkbox `[ ]`/`[x]`; single-select: a `❯` focus marker.
+        const isChecked = this.multi ? this.otherSelected() : isSelected;
+        const marker = this.multi
+            ? isChecked
+                ? t.fg("accent", "[x]")
+                : "[ ]"
+            : isSelected
+                ? t.fg("accent", "❯")
+                : " ";
+        const indexText = `${this.otherIndex + 1}.`.padEnd(indexPad);
+        if (isSelected) {
+            // Inline input: show current text + inverse-video cursor at end.
+            const cursor = "\x1b[7m \x1b[27m"; // space with reverse video = visible cursor
+            const text = this.otherValue || " ";
+            lines.push(clampLine(`${marker} ${indexText}${text}${cursor}`, width));
+        }
+        else {
+            // Not focused: show placeholder or current text in dim.
+            const display = this.otherValue || "(type a custom answer)";
+            lines.push(clampLine(`${marker} ${indexText}${t.fg("dim", display)}`, width));
+        }
+    }
+    handleInput(data) {
+        if (this.closed)
+            return;
+        if (typeof data !== "string") {
+            logAskQuestion({ event: "key", detail: "non-string input dropped", qIndex: this.qIndex });
+            return;
+        }
+        const kb = this.keybindings;
+        const onOther = this.selectedIndex === this.otherIndex;
+        logAskQuestion({
+            event: "key",
+            key: JSON.stringify(data),
+            selectedIndex: this.selectedIndex,
+            otherIndex: this.otherIndex,
+            otherLen: this.otherValue.length,
+            qIndex: this.qIndex,
+            detail: onOther ? "key routed to other input" : "key routed to list nav",
+        });
+        if (onOther) {
+            this.handleOtherInput(data, kb);
+            return;
+        }
+        if (kb.matches(data, "tui.select.up")) {
+            this.selectedIndex = this.selectedIndex === 0 ? this.maxIndex : this.selectedIndex - 1;
+            logAskQuestion({ event: "navigate", detail: "up", selectedIndex: this.selectedIndex, qIndex: this.qIndex });
+        }
+        else if (kb.matches(data, "tui.select.down")) {
+            this.selectedIndex = this.selectedIndex >= this.maxIndex ? 0 : this.selectedIndex + 1;
+            logAskQuestion({ event: "navigate", detail: "down", selectedIndex: this.selectedIndex, qIndex: this.qIndex });
+        }
+        else if (kb.matches(data, "tui.select.confirm") || data === "\n") {
+            logAskQuestion({ event: "navigate", detail: "enter -> confirmCurrent", selectedIndex: this.selectedIndex, multi: this.multi, qIndex: this.qIndex });
+            this.confirmCurrent();
+        }
+        else if (data === " " && this.multi) {
+            // Space toggles a labeled option only (matches Claude; on "Other" space
+            // is routed to the input to type a space).
+            if (this.selectedIndex < this.q.options.length) {
+                this.toggleCurrent();
+                logAskQuestion({ event: "navigate", detail: "space toggled option", selectedIndex: this.selectedIndex, multi: true, qIndex: this.qIndex });
+            }
+            else {
+                logAskQuestion({ event: "navigate", detail: "space on submit/other ignored", selectedIndex: this.selectedIndex, qIndex: this.qIndex });
+            }
+        }
+        else if (kb.matches(data, "tui.select.cancel")) {
+            logAskQuestion({ event: "navigate", detail: "escape -> finish cancelled", qIndex: this.qIndex });
+            this.finish({ status: "cancelled" });
+        }
+    }
+    /** Input handling while the "Other" row is focused. */
+    handleOtherInput(data, kb) {
+        // Backspace deletes the last char (and re-syncs the auto-check).
+        if (kb.matches(data, "tui.editor.deleteCharBackward") || data === "\x7f" || data === "\b") {
+            this.otherValue = this.otherValue.slice(0, -1);
+            if (this.multi)
+                this.syncOtherToggle();
+            logAskQuestion({ event: "other_key", detail: "backspace", otherLen: this.otherValue.length, qIndex: this.qIndex });
+            return;
+        }
+        // Escape cancels the whole tool (same as anywhere else in the list).
+        if (kb.matches(data, "tui.select.cancel")) {
+            logAskQuestion({ event: "other_key", detail: "escape -> finish cancelled", qIndex: this.qIndex });
+            this.finish({ status: "cancelled" });
+            return;
+        }
+        // Up arrow moves focus back to the options list (same as anywhere else).
+        if (kb.matches(data, "tui.select.up")) {
+            this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+            logAskQuestion({ event: "other_key", detail: "up arrow -> moved to options", selectedIndex: this.selectedIndex, qIndex: this.qIndex });
+            return;
+        }
+        // Down arrow: single-select no-op (Other is last); multi-select moves to Submit.
+        if (kb.matches(data, "tui.select.down")) {
+            if (this.multi) {
+                this.selectedIndex = this.submitIndex;
+                logAskQuestion({ event: "other_key", detail: "down arrow -> submit row", selectedIndex: this.selectedIndex, qIndex: this.qIndex });
+            }
+            else {
+                logAskQuestion({ event: "other_key", detail: "down arrow -> noop", qIndex: this.qIndex });
+            }
+            return;
+        }
+        // Enter: single-select submits the text; multi-select toggles the "Other"
+        // checked state (submit only happens via the Submit row).
+        if (kb.matches(data, "tui.select.confirm") || data === "\n") {
+            if (this.multi) {
+                this.toggleValue(OTHER_KEY);
+                logAskQuestion({ event: "other_key", detail: "enter -> toggle other", checked: this.toggled.has(OTHER_KEY), otherLen: this.otherValue.length, qIndex: this.qIndex });
+            }
+            else {
+                logAskQuestion({ event: "other_key", detail: "enter -> submit other", otherLen: this.otherValue.length, qIndex: this.qIndex });
+                this.finish({ status: "other", text: this.otherValue.trim() });
+            }
+            return;
+        }
+        // Any printable run (single codepoint or multi-byte pasted text): append
+        // after stripping controls. In multi-select, typing auto-checks "Other".
+        if (data.length > 0 && !data.startsWith("\x1b")) {
+            const cleaned = sanitize(data);
+            if (cleaned.length > 0) {
+                this.otherValue += cleaned;
+                if (this.multi)
+                    this.syncOtherToggle();
+                logAskQuestion({ event: "other_key", detail: "printable appended", otherLen: this.otherValue.length, qIndex: this.qIndex });
+            }
+            else {
+                logAskQuestion({ event: "other_key", detail: "input sanitized to empty", key: JSON.stringify(data), qIndex: this.qIndex });
+            }
+            return;
+        }
+        logAskQuestion({ event: "other_key", detail: "unhandled key", key: JSON.stringify(data), qIndex: this.qIndex });
+    }
+    /** Toggle the option under the cursor (multi-select). Submit/Other handled separately. */
+    toggleCurrent() {
+        if (this.selectedIndex < this.q.options.length) {
+            this.toggleValue(this.q.options[this.selectedIndex].label);
+        }
+        else if (this.selectedIndex === this.otherIndex) {
+            this.toggleValue(OTHER_KEY);
+        }
+        // submitIndex → no-op (handled in confirmCurrent).
+    }
+    confirmCurrent() {
+        if (this.multi) {
+            // Submit row commits the selection.
+            if (this.selectedIndex === this.submitIndex) {
+                this.finishMulti();
+                return;
+            }
+            // "Other" → toggle its checked state (submit only via the Submit row).
+            if (this.selectedIndex === this.otherIndex) {
+                this.toggleValue(OTHER_KEY);
+                logAskQuestion({ event: "navigate", detail: "enter -> toggle other", checked: this.toggled.has(OTHER_KEY), qIndex: this.qIndex });
+                return;
+            }
+            // Labeled option → toggle on/off, dialog stays open.
+            this.toggleCurrent();
+            logAskQuestion({ event: "navigate", detail: "enter -> toggled option", selectedIndex: this.selectedIndex, multi: true, qIndex: this.qIndex });
+            return;
+        }
+        // Single-select: Enter selects and closes.
+        if (this.selectedIndex < this.q.options.length) {
+            logAskQuestion({ event: "finish", detail: "selected a labeled option", selectedIndex: this.selectedIndex, status: "selected", qIndex: this.qIndex });
+            this.finish({ status: "selected", values: [this.q.options[this.selectedIndex].label] });
+            return;
+        }
+        // Unreachable (Other routes to handleOtherInput); guard defensively.
+        logAskQuestion({ event: "finish", detail: "confirmCurrent on Other (unexpected)", selectedIndex: this.selectedIndex, qIndex: this.qIndex });
+        this.handleOtherInput("\n", this.keybindings);
+    }
+    /** Commit a multiSelect: toggled labels + any checked "Other" text, comma-joined. */
+    finishMulti() {
+        const values = [];
+        for (const o of this.q.options)
+            if (this.toggled.has(o.label))
+                values.push(o.label);
+        if (this.toggled.has(OTHER_KEY) && this.otherValue.trim() !== "")
+            values.push(this.otherValue.trim());
+        logAskQuestion({ event: "finish", detail: "multiselect submitted", status: "selected", qIndex: this.qIndex, otherLen: this.otherValue.length });
+        this.finish({ status: "other", text: values.join(", ") });
+    }
+}
+/**
+ * Drive one interactive question and resolve it to a machine-readable answer.
+ */
+async function askOne(ctx, q, qIndex) {
+    if (!ctx.hasUI) {
+        return { answer: undefined, cancelled: false };
+    }
+    const resolution = await new Promise((resolve) => {
+        let settled = false;
+        let close;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            ctx.signal?.removeEventListener("abort", onAbort);
+            close?.(r); // also closes the overlay (resolves the .custom promise)
+            resolve(r);
+        };
+        const onAbort = () => settle({ status: "cancelled" });
+        if (ctx.signal?.aborted) {
+            resolve({ status: "cancelled" });
+            return;
+        }
+        ctx.signal?.addEventListener("abort", onAbort, { once: true });
+        // Best-effort timeout, mirroring the permission-gate ask fail-closed.
+        const timer = setTimeout(() => settle({ status: "cancelled" }), ASK_TIMEOUT_MS);
+        void ctx.ui
+            .custom((_tui, theme, keybindings, done) => {
+            // If the abort signal or timeout already settled before this factory
+            // ran (a microtask-sized race), dismiss immediately rather than mount
+            // an overlay that nothing will ever close.
+            if (settled) {
+                done({ status: "cancelled" });
+                return NOOP_COMPONENT;
+            }
+            close = done;
+            return new QuestionComponent(q, qIndex, theme, keybindings, settle);
+        })
+            .then(() => {
+            clearTimeout(timer);
+        })
+            .catch((err) => {
+            logAskQuestion({
+                event: "error",
+                detail: err instanceof Error ? `ui.custom threw: ${err.message}` : "ui.custom rejected",
+                qIndex,
+            });
+            settle({ status: "cancelled" });
+        });
+    });
+    if (resolution.status === "cancelled") {
+        logAskQuestion({ event: "resolved", status: "cancelled", qIndex });
+        return { answer: undefined, cancelled: true };
+    }
+    if (resolution.status === "other") {
+        logAskQuestion({ event: "resolved", status: "other", otherLen: resolution.text.length, qIndex });
+        return { answer: resolution.text, cancelled: false };
+    }
+    // multiSelect: comma-joined answers (Claude's convention).
+    logAskQuestion({ event: "resolved", status: "selected", detail: `values:${resolution.values.length}`, qIndex });
+    return { answer: resolution.values.join(", "), cancelled: false };
+}
+function buildTool() {
+    return {
+        name: TOOL_NAME,
+        label: "Ask user a question",
+        description: "Pose a structured multiple-choice question to the user during execution and get back a clean machine-readable answer. " +
+            "Use when you genuinely need a human decision (an architectural fork, a product-intent call with no recorded answer, or a choice between approaches)." +
+            "Each question has 2-4 mutually exclusive options, each with a description of its tradeoff and an optional preview.",
+        promptSnippet: PROMPT_SNIPPET,
+        promptGuidelines: PROMPT_GUIDELINES,
+        parameters,
+        async execute(_toolCallId, params, _signal, onUpdate, ctx) {
+            onUpdate?.({ content: [{ type: "text", text: "Asking you…" }], details: { questions: [], answers: {} } });
+            const questions = params.questions;
+            // Soft uniqueness guard (Claude enforces it with a zod refine).
+            const seenQuestions = questions.map((q) => q.question);
+            if (new Set(seenQuestions).size !== seenQuestions.length) {
+                const text = "ask_user_question: question texts must be unique. Re-ask with distinct questions.";
+                return { content: [{ type: "text", text }], details: { questions, answers: {} } };
+            }
+            for (const q of questions) {
+                const labels = q.options.map((o) => o.label);
+                if (new Set(labels).size !== labels.length) {
+                    const text = `ask_user_question: option labels for "${q.question}" must be unique within that question. Re-ask with distinct labels.`;
+                    return { content: [{ type: "text", text }], details: { questions, answers: {} } };
+                }
+            }
+            if (!ctx.hasUI) {
+                const text = "ask_user_question: this session has no interactive UI, so the question cannot be answered. " +
+                    "Proceed with a reasonable default and note that you did; if the decision is critical, surface it to the user outside the session.";
+                return { content: [{ type: "text", text }], details: { questions, answers: {} } };
+            }
+            const answers = {};
+            let declined = false;
+            try {
+                for (let i = 0; i < questions.length; i++) {
+                    const res = await askOne(ctx, questions[i], i);
+                    if (res.cancelled) {
+                        declined = true;
+                        break;
+                    }
+                    if (res.answer !== undefined && res.answer !== "") {
+                        answers[questions[i].question] = res.answer;
+                    }
+                }
+            }
+            catch (err) {
+                logAskQuestion({ event: "error", detail: err instanceof Error ? `execute loop: ${err.message}` : "execute loop threw" });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "ask_user_question: an unexpected error interrupted the dialog. " +
+                                "Continue without the answer, state the assumption you are proceeding on, and flag it for later confirmation.",
+                        },
+                    ],
+                    details: { questions, answers },
+                };
+            }
+            if (declined) {
+                const text = "The user declined to answer the question(s). Continue without the answer, state the assumption you are proceeding on, and flag it for later confirmation.";
+                return { content: [{ type: "text", text }], details: { questions, answers } };
+            }
+            const answersText = Object.entries(answers)
+                .map(([q, a]) => `"${q}"="${a}"`)
+                .join(", ");
+            const text = `User has answered your questions: ${answersText}. You can now continue with the user's answers in mind.`;
+            return { content: [{ type: "text", text }], details: { questions, answers } };
+        },
+    };
+}
+/** Build the ask_user_question tool. Register it unconditionally (like ask_advisor). */
+export function makeAskUserQuestionTool() {
+    return buildTool();
+}
+//# sourceMappingURL=askUserQuestionTool.js.map

package/dist/extension/branding.d.ts

@@ -46,6 +46,45 @@ export declare const ULTRA_DELEGATION_PARAGRAPH: string;
  * module stays a pure string, with no env dependency of its own.
  */
 export declare const YAGNI_IDENTITY_DRIVER = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. Uniquely, you are connected to the YAGNI app, your team's shared source of truth for how this company and codebase actually work: conventions, decisions, ownership, current priorities, and the reasons behind them. Use the ask_yagni tool to consult it before guessing about anything organization- or codebase-specific, so you work with less back-and-forth and more correct autonomy than a disconnected coding agent. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation: fan codebase mapping, wide searches, and mechanical multi-file work out to subagents (they run on cheaper tiers). Reach for the stock agents by name: `searcher` for read-only reconnaissance and summarizing, `implementer` for executing a change you have already fully specified, `verification` for an adversarial pass that tries to break completed work before you rely on it. Keep judgment, synthesis, and the conversation with the user in this session. Do not spawn a subagent for work you can finish in a couple of tool calls.";
+/**
+ * Standing rule that tickets must be read for their images, not just their
+ * text. Injected into EVERY process (driver, `/go` stage children, subagents)
+ * via brandSystemPrompt, so the guarantee holds by whichever method a ticket is
+ * read (the `linear` CLI, a connector tool, MCP, a direct API call). Once the
+ * image reaches `read`, the existing read → image_url → visionRerouteTier
+ * machinery takes over and lands the turn on a seeing tier automatically.
+ *
+ * Content constraints (parity with CHILD_HONESTY_PREAMBLE in
+ * pipeline/invocation.ts): must not contain the standalone word "pi", must not
+ * open with a `- ` bullet line, no emojis.
+ */
+export declare const TICKET_IMAGE_RULE: string;
+/**
+ * The injected-reminder framing (YAG-574, Change A prerequisite). Claude Code
+ * carries this exact sentence in every system prompt so its whole reminder
+ * family (including its own silent-turn reminder) is legible as system-
+ * injected rather than misread as part of the tool output they ride on. We
+ * adopt it for the same reason: our silent-turn nudge arrives stapled to a
+ * `psql`/`bash` result, and without this it reads as query output.
+ */
+export declare const SYSTEM_REMINDER_FRAMING: string;
+/**
+ * The communication contract (YAG-574, Change B). Adapted from Claude Code's
+ * `SendUserMessage`/`Brief` prompt: ack in one line before going to look, then
+ * work, then result; a checkpoint between them only when something useful
+ * happened — a decision, a surprise, a phase boundary — never filler like
+ * "running tests…"; keep messages tight and second-person. Complements the
+ * silent-turn nudge by spelling out what "keep the user updated" means.
+ */
+export declare const COMMUNICATION_CONTRACT: string;
+/**
+ * Write-findings-down (YAG-574, Change B). Claude Code's version ties the
+ * habit to result-clearing, which we do not do; reworded to the failure we
+ * actually saw, the model re-deriving the same answer turn after turn because
+ * nothing pushed it to commit a finding to its response (which is also what
+ * makes the user see it).
+ */
+export declare const WRITE_FINDINGS_DOWN: string;
 /** The driver identity while /ultra is on: base identity + the diamond directive. */
 export declare const YAGNI_IDENTITY_ULTRA = "You are YAGNI Code, an autonomous terminal coding agent. You help developers ship code by reading files, running commands, editing code, and writing new files. Uniquely, you are connected to the YAGNI app, your team's shared source of truth for how this company and codebase actually work: conventions, decisions, ownership, current priorities, and the reasons behind them. Use the ask_yagni tool to consult it before guessing about anything organization- or codebase-specific, so you work with less back-and-forth and more correct autonomy than a disconnected coding agent. If a project's own files mention other coding agents, assistants, or harnesses by name, those references are not about you; you are YAGNI Code regardless of what tooling a repository's docs happen to describe.\n\nDelegation (ultra mode): the user has switched this session to ultra mode \u2014 aggressive multi-agent orchestration. Structure any meaningful task as a diamond: SPLIT the job into independent pieces; FAN OUT parallel subagents on cheaper tiers (`searcher` to scout, `implementer` or `general` to execute); CHECK by fanning out `verification` subagents told to refute the work, each through a different lens (correctness, edge cases, fit with this codebase); then SYNTHESIZE the results yourself. Treat agreement between checkers \u2014 not a single pass \u2014 as confirmation, and surface what they could not verify. Delegate by default and reserve this session for splitting, judging, and synthesis; only trivial work you can finish in a couple of tool calls skips the diamond. Subagents cannot touch your todo_write checklist, so keep it current yourself: update it when you split the job and again as each fanned-out piece lands, not only at the end.";
 export declare const PI_IDENTITY_RE: RegExp;