@yagni-app/code-staging 0.3.5-staging.1160.1 → 0.3.5-staging.1165.1

package/dist/extension/askUserQuestionTool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+declare const parameters: Type.TObject<{
+    questions: Type.TArray<Type.TObject<{
+        question: Type.TString;
+        header: Type.TString;
+        options: Type.TArray<Type.TObject<{
+            label: Type.TString;
+            description: Type.TString;
+            preview: Type.TOptional<Type.TString>;
+        }>>;
+        multiSelect: Type.TOptional<Type.TBoolean>;
+    }>>;
+}>;
+type QuestionOption = {
+    label: string;
+    description: string;
+    preview?: string;
+};
+type Question = {
+    question: string;
+    header: string;
+    options: QuestionOption[];
+    multiSelect?: boolean;
+};
+/** The structured answer bag stored on the tool result. */
+type AskDetails = {
+    questions: Question[];
+    answers: Record<string, string>;
+};
+/** Build the ask_user_question tool. Register it unconditionally (like ask_advisor). */
+export declare function makeAskUserQuestionTool(): ToolDefinition<typeof parameters, AskDetails>;
+export {};
+//# sourceMappingURL=askUserQuestionTool.d.ts.map

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/diagnostics.d.ts

@@ -14,6 +14,8 @@
  */
 export declare function _setDiagnosticsHomeForTest(dir: string | null): void;
 export declare function diagnosticsLogPath(): string;
+/** Dedicated log for the ask_user_question interactive tool's state machine. */
+export declare function askQuestionLogPath(): string;
 /** Layer A: verbose mode. `YAGNI_DEBUG=1` (or "true") turns on extra detail. */
 export declare function isDebug(env?: NodeJS.ProcessEnv): boolean;
 export interface ImagePasteEvent {
@@ -34,6 +36,32 @@ export interface ImagePasteEvent {
  * prompt. `detail` is included only when YAGNI_DEBUG is on.
  */
 export declare function logImagePaste(ev: ImagePasteEvent): void;
+export interface AskQuestionEvent {
+    /** Stable event name: "key" | "finish" | "render" | "navigate" | "other_key". */
+    event: string;
+    /** Human-readable description; NEVER user-typed text or question content. */
+    detail?: string;
+    selectedIndex?: number;
+    otherIndex?: number;
+    otherLen?: number;
+    /** Raw key bytes, escaped (only for debug). */
+    key?: string;
+    /** Resolution status when the tool finishes: selected | other | cancelled. */
+    status?: string;
+    /** Whether the question is multiSelect at the time of the event. */
+    multi?: boolean;
+    /** 0-based index of the question within this tool call (multi-question runs). */
+    qIndex?: number;
+    /** Whether the "Other" row auto-check is on (multi-select). */
+    checked?: boolean;
+}
+/**
+ * Append one sanitized ask-user-question event to `ask-question.log`.
+ * Fail-soft and hermetically gated under `node --test` exactly like
+ * `logImagePaste`. Never logs user-typed text, question text, or option labels
+ * — only indices, lengths, key bytes (escaped), and resolution status.
+ */
+export declare function logAskQuestion(ev: AskQuestionEvent): void;
 /** Read the most recent log content (for a user-triggered report). */
 export declare function readRecentDiagnostics(maxBytes?: number): string;
 /** List existing diagnostic log files (active + rotations), for a report. */

package/dist/extension/diagnostics.js

@@ -26,6 +26,10 @@ function yagniCodeHome() {
 export function diagnosticsLogPath() {
     return join(yagniCodeHome(), "logs", "image-paste.log");
 }
+/** Dedicated log for the ask_user_question interactive tool's state machine. */
+export function askQuestionLogPath() {
+    return join(yagniCodeHome(), "logs", "ask-question.log");
+}
 const MAX_LOG_BYTES = 256 * 1024; // rotate the active file past this
 const KEEP_ROTATIONS = 2; // keep image-paste.log.1 and .2 alongside the active file
 /** Layer A: verbose mode. `YAGNI_DEBUG=1` (or "true") turns on extra detail. */
@@ -84,6 +88,38 @@ function rotateIfNeeded(path) {
         /* rotation is best-effort */
     }
 }
+/**
+ * Append one sanitized ask-user-question event to `ask-question.log`.
+ * Fail-soft and hermetically gated under `node --test` exactly like
+ * `logImagePaste`. Never logs user-typed text, question text, or option labels
+ * — only indices, lengths, key bytes (escaped), and resolution status.
+ */
+export function logAskQuestion(ev) {
+    try {
+        if (process.env.NODE_TEST_CONTEXT && homeOverride === null)
+            return;
+        const line = {
+            ts: new Date().toISOString(),
+            event: ev.event,
+            ...(ev.selectedIndex !== undefined ? { selectedIndex: ev.selectedIndex } : {}),
+            ...(ev.otherIndex !== undefined ? { otherIndex: ev.otherIndex } : {}),
+            ...(ev.otherLen !== undefined ? { otherLen: ev.otherLen } : {}),
+            ...(ev.status !== undefined ? { status: ev.status } : {}),
+            ...(ev.multi !== undefined ? { multi: ev.multi } : {}),
+            ...(ev.qIndex !== undefined ? { qIndex: ev.qIndex } : {}),
+            ...(ev.checked !== undefined ? { checked: ev.checked } : {}),
+            ...(ev.key !== undefined ? { key: ev.key } : {}),
+            ...(ev.detail !== undefined && isDebug() ? { detail: ev.detail } : {}),
+        };
+        const path = askQuestionLogPath();
+        mkdirSync(dirname(path), { recursive: true });
+        rotateIfNeeded(path);
+        appendFileSync(path, JSON.stringify(line) + "\n", "utf8");
+    }
+    catch {
+        /* logging must never throw into the tool */
+    }
+}
 /** Read the most recent log content (for a user-triggered report). */
 export function readRecentDiagnostics(maxBytes = 64 * 1024) {
     try {

package/dist/extension/index.d.ts

@@ -120,6 +120,7 @@ export default function (pi: ExtensionAPI): Promise<void>;
 export { makeAskYagniTool } from "./askYagniTool.js";
 export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+export { makeAskUserQuestionTool } from "./askUserQuestionTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
 export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs, } from "./permission/guardian.js";
 export type { GuardianOutcome, GuardianVerdict, GuardianState, GuardianStateHandle, GuardianLimits, ReviewResult, ReviewCommandDeps, } from "./permission/guardian.js";

package/dist/extension/index.js

@@ -7,6 +7,7 @@ import { appendGrant, loadGrants, resolveRepoKey, storagePrefix } from "./permis
 import { redactCommand } from "./redact.js";
 import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs } from "./permission/guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+import { makeAskUserQuestionTool } from "./askUserQuestionTool.js";
 import { makeAskYagniTool } from "./askYagniTool.js";
 import { makeWebFetchTool } from "./webFetchTool.js";
 import { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
@@ -181,6 +182,9 @@ export async function registerYagni(pi, deps = {}) {
     // /advise runs the SAME tool, sharing the state handle, so a manual consult
     // draws on the same cap rather than opening a side channel around it.
     registerAdviseCommand(pi, askAdvisorTool);
+    // Structured human questions: the model poses a closed 2-4-option question
+    // and gets a clean machine-readable answer via ctx.ui.custom.
+    pi.registerTool(makeAskUserQuestionTool());
     // The differentiated business-grounded tools (loop bricks): review a change
     // for business fit, rank the next work by business priority, and record the
     // engineering rationale back onto the work-item.
@@ -763,6 +767,16 @@ export async function registerYagni(pi, deps = {}) {
     // and a "Pi can explain its own features…" line) with a YAGNI Code masthead,
     // set the terminal title, and add a footer brand mark. TUI only.
     pi.on("session_start", async (event, ctx) => {
+        // Surface Pi's native find/grep/ls on the driver. These are Pi's
+        // equivalents of Claude Code's Glob/Grep/LS; the /go stages and subagents
+        // already pass them explicitly, but the driver defaults to read/bash/edit/write
+        // and otherwise reaches for `bash` find/grep/ls.
+        try {
+            pi.setActiveTools([...pi.getActiveTools(), "grep", "find", "ls"]);
+        }
+        catch {
+            // Tool enrichment must never break session start.
+        }
         ctx.ui?.setTitle(BRAND_NAME);
         if (ctx.mode === "tui") {
             ctx.ui?.setStatus?.("brand", BRAND_NAME);
@@ -906,6 +920,7 @@ export default async function (pi) {
 export { makeAskYagniTool } from "./askYagniTool.js";
 export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
+export { makeAskUserQuestionTool } from "./askUserQuestionTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
 export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, deriveGuardianTimeoutMs, } from "./permission/guardian.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "0.3.5-staging.1160.1",
+  "version": "0.3.5-staging.1165.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -40,5 +40,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "cb341f87d13165d17246c8c335200c69982bd60b"
+  "yagniSourceSha": "09b1377d109fda746976e90031aa0641e24e79b3"
 }