@pugi/cli 0.1.0-beta.16 → 0.1.0-beta.18

package/dist/runtime/commands/mcp.js

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, resolve } from 'node:path';
 import { FileReadCache } from '../../core/file-cache.js';
 import { openSession } from '../../core/session.js';
 import { loadSettings } from '../../core/settings.js';
-import { loadMcpRegistry } from '../../core/mcp/registry.js';
+import { isAlive } from '../../core/mcp/client.js';
+import { loadMcpRegistry, mcpLogPath } from '../../core/mcp/registry.js';
 import { listMcpTrust, setMcpTrust } from '../../core/mcp/trust.js';
 import { createPugiMcpServer, serveStdio } from '../../core/mcp/server.js';
 import { buildPugiMcpTools } from '../../core/mcp/server-tools.js';
@@ -22,6 +23,15 @@ export async function runMcpCommand(args, ctx) {
             return runMcpFlip(args.slice(1), ctx, 'denied');
         case 'install':
             return runMcpInstall(args.slice(1), ctx);
+        case 'remove':
+        case 'uninstall':
+            return runMcpRemove(args.slice(1), ctx);
+        case 'doctor':
+            return runMcpDoctor(args.slice(1), ctx);
+        case 'logs':
+            return runMcpLogs(args.slice(1), ctx);
+        case 'restart':
+            return runMcpRestart(args.slice(1), ctx);
         case 'serve':
             return runMcpServe(args.slice(1), ctx);
         case 'perms':
@@ -32,7 +42,7 @@ export async function runMcpCommand(args, ctx) {
             ctx.writeOutput({ command: 'mcp', usage: USAGE_LINES }, USAGE_LINES.join('\n'));
             return;
         default:
-            throw new Error(`Unknown sub-command "pugi mcp ${sub}". Try one of: list, trust, deny, install, serve, perms.`);
+            throw new Error(`Unknown sub-command "pugi mcp ${sub}". Try one of: list, trust, deny, install, remove, doctor, logs, restart, serve, perms.`);
     }
 }
 const USAGE_LINES = [
@@ -44,6 +54,15 @@ const USAGE_LINES = [
     '  install <name> <command...>   Add a server to .pugi/mcp.json (workspace scope).',
     '                                <command> must be an absolute path OR a binary',
     '                                resolvable via `which` on the operator PATH.',
+    '  remove <name>                 Remove a server from .pugi/mcp.json (workspace scope).',
+    '                                Trust ledger entry is preserved — re-install reuses it.',
+    '  doctor [--connect]            Print per-server health (handshake, tool count, last error).',
+    '                                --connect actually spawns the children (slow, ~5s/server).',
+    '                                Without --connect, reports the declared state only.',
+    '  logs <name> [--tail N]        Tail the per-server log file at .pugi/logs/mcp-<name>.log.',
+    '                                Default tail is 40 lines.',
+    '  restart <name>                Bounce a server: tear down the connection, reload the',
+    '                                config, re-handshake. Surfaces the new tool count.',
     '  serve [options]               Run Pugi as an MCP server',
     '    --http :<port>              HTTP+SSE transport (default: stdio)',
     '    --host <ip>                 HTTP bind host (default: 127.0.0.1)',
@@ -219,6 +238,274 @@ function containsShellMetachar(value) {
     // a shell pipeline.
     return /[;|&`$<>(){}\n\r]/.test(value);
 }
+/* ---------- remove ---------------------------------------------------- */
+async function runMcpRemove(args, ctx) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: pugi mcp remove <name>');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp remove: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    const mcpJsonPath = resolve(ctx.workspaceRoot, '.pugi/mcp.json');
+    if (!existsSync(mcpJsonPath)) {
+        throw new Error(`pugi mcp remove: no .pugi/mcp.json at ${mcpJsonPath}. Nothing to remove.`);
+    }
+    let existing;
+    try {
+        const raw = readFileSync(mcpJsonPath, 'utf8');
+        if (raw.trim().length === 0) {
+            existing = { servers: {} };
+        }
+        else {
+            const parsed = JSON.parse(raw);
+            existing = { servers: parsed.servers ?? {} };
+        }
+    }
+    catch (error) {
+        throw new Error(`pugi mcp remove: cannot parse .pugi/mcp.json: ${error.message}. ` +
+            `Fix the file by hand or delete it and re-run.`);
+    }
+    if (!existing.servers[name]) {
+        throw new Error(`pugi mcp remove: server "${name}" not declared in ${mcpJsonPath}. ` +
+            `Run \`pugi mcp list\` to see declared servers.`);
+    }
+    // Preserve the trust ledger entry on purpose — a re-install of the same
+    // server name should land back at its old trust state so the operator
+    // does not have to re-approve it. To wipe trust as well, run
+    // `pugi mcp deny <name>` (or edit ~/.pugi/trust-mcp.json by hand).
+    delete existing.servers[name];
+    writeFileSync(mcpJsonPath, `${JSON.stringify(existing, null, 2)}\n`, { mode: 0o600 });
+    ctx.writeOutput({
+        command: 'mcp.remove',
+        name,
+        configPath: mcpJsonPath,
+        remaining: Object.keys(existing.servers),
+    }, [
+        `Removed MCP server "${name}" from ${mcpJsonPath}.`,
+        `Trust ledger entry preserved — re-install reuses it.`,
+        `Remaining servers: ${Object.keys(existing.servers).length === 0 ? '(none)' : Object.keys(existing.servers).join(', ')}.`,
+    ].join('\n'));
+}
+/* ---------- doctor ---------------------------------------------------- */
+async function runMcpDoctor(args, ctx) {
+    // `--connect` forces the doctor to actually spawn children + handshake.
+    // Default behaviour is dry-run (config + trust ledger only) so a routine
+    // `pugi doctor` does not block on a misbehaving server's 5s timeout per
+    // entry. Operators investigating an outage pass `--connect` explicitly.
+    const wantsConnect = args.includes('--connect');
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: wantsConnect });
+    const ledger = await listMcpTrust();
+    const rows = [];
+    for (const state of registry.servers.values()) {
+        const conn = state.connection;
+        let handshake;
+        if (!wantsConnect) {
+            handshake = 'not-attempted';
+        }
+        else if (state.lastError) {
+            handshake = 'failed';
+        }
+        else if (conn && isAlive(conn)) {
+            handshake = 'ok';
+        }
+        else {
+            handshake = 'failed';
+        }
+        rows.push({
+            name: state.name,
+            trust: state.trust,
+            handshake,
+            pid: conn?.child.pid ?? null,
+            tools: state.surfacedTools.length,
+            uptimeMs: conn ? Date.now() - conn.startedAt : null,
+            lastError: state.lastError ?? null,
+            logFile: mcpLogPath(ctx.workspaceRoot, state.name),
+        });
+    }
+    rows.sort((a, b) => a.name.localeCompare(b.name));
+    await registry.shutdown();
+    if (rows.length === 0) {
+        ctx.writeOutput({ command: 'mcp.doctor', rows, ledger, connectAttempted: wantsConnect }, 'No MCP servers declared. Add one with `pugi mcp install <name> <command...>`.');
+        return;
+    }
+    const headerLines = [
+        `MCP doctor (${wantsConnect ? 'live handshake' : 'declared state only — pass --connect for live probe'}):`,
+        '',
+        `  ${'NAME'.padEnd(20)} ${'TRUST'.padEnd(8)} ${'HANDSHAKE'.padEnd(14)} ${'TOOLS'.padEnd(6)} ${'PID'.padEnd(7)} NOTE`,
+    ];
+    for (const row of rows) {
+        const note = row.lastError
+            ? `error: ${truncate(row.lastError, 60)}`
+            : row.handshake === 'ok'
+                ? `uptime ${formatUptime(row.uptimeMs ?? 0)}`
+                : row.handshake === 'failed'
+                    ? 'see log file'
+                    : '';
+        headerLines.push(`  ${row.name.padEnd(20)} ${row.trust.padEnd(8)} ${row.handshake.padEnd(14)} ${String(row.tools).padEnd(6)} ${String(row.pid ?? '-').padEnd(7)} ${note}`);
+    }
+    headerLines.push('', `Log dir: ${resolve(ctx.workspaceRoot, '.pugi/logs')}`);
+    if (!wantsConnect) {
+        headerLines.push('Hint: pass --connect to actually spawn the children (slow, ~5s budget/server).');
+    }
+    ctx.writeOutput({ command: 'mcp.doctor', rows, ledger, connectAttempted: wantsConnect }, headerLines.join('\n'));
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}
+function formatUptime(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m${sec % 60}s`;
+    const hr = Math.floor(min / 60);
+    return `${hr}h${min % 60}m`;
+}
+/* ---------- logs ------------------------------------------------------ */
+async function runMcpLogs(args, ctx) {
+    const name = args[0];
+    if (!name || name.startsWith('--')) {
+        throw new Error('Usage: pugi mcp logs <name> [--tail N]');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp logs: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // `--tail N` and `--tail=N` both supported. Default 40 lines — matches
+    // typical `tail -n 40` muscle memory.
+    let tail = 40;
+    for (let i = 1; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (arg === '--tail') {
+            const next = args[i + 1];
+            if (!next)
+                throw new Error('pugi mcp logs: --tail requires a value');
+            const n = Number.parseInt(next, 10);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`pugi mcp logs: --tail must be a positive integer (got "${next}")`);
+            }
+            tail = n;
+            i += 1;
+        }
+        else if (arg.startsWith('--tail=')) {
+            const n = Number.parseInt(arg.slice('--tail='.length), 10);
+            if (!Number.isInteger(n) || n <= 0) {
+                throw new Error(`pugi mcp logs: --tail must be a positive integer (got "${arg}")`);
+            }
+            tail = n;
+        }
+        else {
+            throw new Error(`pugi mcp logs: unknown flag "${arg}"`);
+        }
+    }
+    const path = mcpLogPath(ctx.workspaceRoot, name);
+    if (!existsSync(path)) {
+        ctx.writeOutput({ command: 'mcp.logs', name, path, tail, lines: [] }, `No log file at ${path}. The server has not produced stderr output yet (or has never been started).`);
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`pugi mcp logs: cannot read ${path}: ${error.message}.`);
+    }
+    const allLines = raw.split('\n');
+    // `split('\n')` of a trailing-newline file yields an empty last element.
+    // Drop it so the displayed tail matches `wc -l` expectations.
+    if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
+        allLines.pop();
+    }
+    const tailed = allLines.slice(Math.max(0, allLines.length - tail));
+    const sizeBytes = (() => {
+        try {
+            return statSync(path).size;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    ctx.writeOutput({
+        command: 'mcp.logs',
+        name,
+        path,
+        tail,
+        totalLines: allLines.length,
+        sizeBytes,
+        lines: tailed,
+    }, [
+        `pugi mcp logs ${name} (${path}, ${sizeBytes} bytes, ${allLines.length} total lines, showing last ${Math.min(tail, allLines.length)}):`,
+        ...tailed,
+    ].join('\n'));
+}
+/* ---------- restart --------------------------------------------------- */
+async function runMcpRestart(args, ctx) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: pugi mcp restart <name>');
+    }
+    if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+        throw new Error(`pugi mcp restart: server name "${name}" must be [a-zA-Z0-9_-]+`);
+    }
+    // `pugi mcp restart` is stateless from the CLI's perspective — the CLI
+    // process has no long-lived MCP registry of its own (the REPL owns it
+    // and tears it down on exit). What we DO here is: load the config,
+    // refuse if the server is not declared or not trusted, then probe-spawn
+    // the server with the live handshake. This proves it is reachable +
+    // surfaces the tool count for the operator. The REPL picks up the
+    // change on its next `loadMcpRegistry` cycle.
+    const registry = await loadMcpRegistry(ctx.workspaceRoot, { connect: false });
+    const state = registry.servers.get(name);
+    if (!state) {
+        await registry.shutdown();
+        throw new Error(`pugi mcp restart: server "${name}" not declared. Run \`pugi mcp list\` to see declared servers.`);
+    }
+    if (state.trust !== 'trusted') {
+        await registry.shutdown();
+        throw new Error(`pugi mcp restart: server "${name}" trust state is "${state.trust}". ` +
+            `Run \`pugi mcp trust ${name}\` first.`);
+    }
+    await registry.shutdown();
+    // Re-load WITH connect=true but scoped to a single-server probe via
+    // handshakeTimeoutMs (5s default keeps the CLI snappy). We use the same
+    // loadMcpRegistry path so log routing + error capture stay consistent.
+    const probe = await loadMcpRegistry(ctx.workspaceRoot, { connect: true });
+    const probed = probe.servers.get(name);
+    const lastError = probed?.lastError ?? null;
+    const toolCount = probed?.surfacedTools.length ?? 0;
+    const pid = probed?.connection?.child.pid ?? null;
+    await probe.shutdown();
+    if (lastError) {
+        ctx.writeOutput({
+            command: 'mcp.restart',
+            name,
+            ok: false,
+            error: lastError,
+            logFile: mcpLogPath(ctx.workspaceRoot, name),
+        }, [
+            `pugi mcp restart ${name}: FAILED`,
+            `  error: ${lastError}`,
+            `  log file: ${mcpLogPath(ctx.workspaceRoot, name)}`,
+        ].join('\n'));
+        return;
+    }
+    ctx.writeOutput({
+        command: 'mcp.restart',
+        name,
+        ok: true,
+        pid,
+        surfacedTools: toolCount,
+    }, [
+        `pugi mcp restart ${name}: OK`,
+        `  pid: ${pid ?? '-'}`,
+        `  surfaced tools: ${toolCount}`,
+    ].join('\n'));
+}
 async function runMcpServe(args, ctx) {
     const flags = parseServeFlags(args);
     const session = openSession(ctx.workspaceRoot);

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.16');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.18');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tools/agent-tool.js

@@ -58,8 +58,16 @@ import { spawnSubagentWithOutcome } from '../core/subagents/spawn.js';
  * inverse (forces shared-fs even for roles whose default is `worktree`).
  *
  * The role enum mirrors the SDK's SubagentRole — keep both in lockstep.
+ *
+ * Leak P0 L2 (2026-05-27): `z.strictObject` rejects ANY additional or
+ * aliased fields at parse time. Matches the openclaude FileEditTool /
+ * FileWriteTool posture (research memo §1.1). The model-facing JSON
+ * schema already declares `additionalProperties: false`; the strict
+ * Zod variant is defense-in-depth — if the bridge ever bypasses the
+ * model-side gate (raw test fixture, internal dispatch), the runtime
+ * still refuses unknown keys instead of silently dropping them.
  */
-export const agentToolArgsSchema = z.object({
+export const agentToolArgsSchema = z.strictObject({
     role: z.enum([
         'orchestrator',
         'architect',
@@ -70,12 +78,18 @@ export const agentToolArgsSchema = z.object({
         'release',
         'devops',
         'design_qa',
-    ]),
+    ]).describe('SubagentRole — selects persona + isolation tier.'),
     brief: z
         .string()
         .min(1, 'brief must not be empty')
-        .max(8000, 'brief must be ≤ 8000 chars'),
-    isolation: z.enum(['worktree', 'shared_fs', 'auto']).optional(),
+        .max(8000, 'brief must be ≤ 8000 chars')
+        .describe('One-paragraph task description forwarded to the child as the user prompt. '
+        + 'Be concrete: include filenames, expected behavior, and acceptance criteria.'),
+    isolation: z
+        .enum(['worktree', 'shared_fs', 'auto'])
+        .optional()
+        .describe('Optional override. `worktree` forces a scratch git worktree for write isolation; '
+        + '`shared_fs` forces same-tree execution; `auto` (default) defers to the role tier.'),
 });
 /**
  * Dispatch a subagent via the `agent` tool. Returns the JSON envelope

package/dist/tools/ask-user-question.js

@@ -0,0 +1,213 @@
+/**
+ * AskUserQuestion structured tool — leak L5 (research memo §2.5).
+ *
+ * Mirrors openclaude's `src/tools/AskUserQuestionTool/prompt.ts`
+ * pattern: clarifying questions go through a structured multi-choice
+ * tool, NOT free-text prose. The model dispatches the tool with a
+ * `question` + a `header` chip + 2-4 `options` (each with `label` +
+ * `description`). The UI renders the modal, auto-appends an "Other"
+ * fallback for custom text, and surfaces the operator's pick back to
+ * the model as a tool_result frame.
+ *
+ * Why P0 leverage: the structured form forecloses Pugi's recurring
+ * "agent rambles instead of dispatching" failure mode at the schema
+ * level. When the model is uncertain, the cheapest legal output is
+ * `ask_user_question` — not a prose menu, not a fake "Шипану через
+ * 8 минут" dispatch promise.
+ *
+ * Relationship to ask-user.ts (β1 T2):
+ *   - ask-user.ts is the LEGACY string-array form (`options: string[]`).
+ *     Kept for back-compat; the existing prompt envelope `<pugi-ask>`
+ *     and the persona prompts still emit that grammar.
+ *   - ask-user-question.ts is the STRUCTURED form layered on top. It
+ *     normalises a {label, description} option into the legacy string
+ *     before delegating to `askUser`, so the Ink modal does not need
+ *     two render paths and the abort/timeout race logic is shared.
+ *
+ * Hard rules (enforced by Zod):
+ *   - question: 5-500 chars, must end with "?". Plain English.
+ *   - header: 2-12 chars (short chip label, e.g. "Auth method").
+ *   - options: 2-4 strict (no more, no less). Mutually exclusive.
+ *     UI auto-adds "Other" — the model NEVER emits it.
+ *   - multiSelect: default false.
+ */
+import { z } from 'zod';
+import { askUser } from './ask-user.js';
+/** Cap matches the Ink modal layout: 12 chars fits the header chip. */
+export const ASK_USER_QUESTION_HEADER_MIN = 2;
+export const ASK_USER_QUESTION_HEADER_MAX = 12;
+/** Question must be a real question (ends with ?). 5-500 chars. */
+export const ASK_USER_QUESTION_MIN = 5;
+export const ASK_USER_QUESTION_MAX = 500;
+/** Each option label: 2-40 chars (1-5 words). */
+export const ASK_USER_QUESTION_OPTION_LABEL_MIN = 2;
+export const ASK_USER_QUESTION_OPTION_LABEL_MAX = 40;
+/** Each option description: 10-200 chars (one short sentence). */
+export const ASK_USER_QUESTION_OPTION_DESC_MIN = 10;
+export const ASK_USER_QUESTION_OPTION_DESC_MAX = 200;
+/** Option count: 2-4 strict. UI adds "Other" automatically. */
+export const ASK_USER_QUESTION_OPTIONS_MIN = 2;
+export const ASK_USER_QUESTION_OPTIONS_MAX = 4;
+/**
+ * Structured option. `label` is the display text; `description` is the
+ * implication line shown dim below it. Both are required — the model
+ * cannot ship a label-only option (forces it to think about why each
+ * choice exists).
+ */
+export const askUserQuestionOptionSchema = z.strictObject({
+    label: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_LABEL_MIN)
+        .max(ASK_USER_QUESTION_OPTION_LABEL_MAX)
+        .describe('Display text. Concise (1-5 words).'),
+    description: z
+        .string()
+        .min(ASK_USER_QUESTION_OPTION_DESC_MIN)
+        .max(ASK_USER_QUESTION_OPTION_DESC_MAX)
+        .describe('What this option means / implications.'),
+});
+export const askUserQuestionSchema = z.strictObject({
+    question: z
+        .string()
+        .min(ASK_USER_QUESTION_MIN)
+        .max(ASK_USER_QUESTION_MAX)
+        .refine((q) => q.trim().endsWith('?'), {
+        message: 'question must end with "?"',
+    })
+        .describe('The complete question. Must end with "?". Plain English, no jargon.'),
+    header: z
+        .string()
+        .min(ASK_USER_QUESTION_HEADER_MIN)
+        .max(ASK_USER_QUESTION_HEADER_MAX)
+        .describe('Short chip label (max 12 chars). E.g. "Auth method".'),
+    options: z
+        .array(askUserQuestionOptionSchema)
+        .min(ASK_USER_QUESTION_OPTIONS_MIN)
+        .max(ASK_USER_QUESTION_OPTIONS_MAX)
+        .describe('2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.'),
+    multiSelect: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Allow multiple selections. Default false.'),
+});
+/**
+ * Dispatch the structured tool: validate args via Zod, then route
+ * through the shared `askUser` primitive so abort/timeout/non-TTY
+ * envelope behaviour is identical to the legacy form.
+ *
+ * The bridge surface is the same `AskUserBridge` signature — the
+ * structured form just gives the Ink modal richer metadata to render
+ * (header chip + per-option description). The bridge sees the legacy
+ * `{question, options: string[]}` shape because all production bridges
+ * (Ink modal + non-TTY envelope emitter) already consume that shape.
+ * Per-option descriptions and the header chip are surfaced separately
+ * via `enrich` — the modal layer reads them off the dispatched payload
+ * stash, NOT off the bridge input, so structured callers can layer on
+ * top of the legacy interface without touching the modal contract.
+ *
+ * Return contract:
+ *   - Interactive + bridge present + operator picks N options →
+ *     `[ask_user_question:answered] <labels joined by ", ">`.
+ *   - Interactive + bridge present + operator cancels →
+ *     `[ask_user_question:cancelled]`.
+ *   - Interactive + bridge present + timeout →
+ *     `[ask_user_question:timeout]`.
+ *   - Non-TTY or no bridge → `[user_input_required]<json>[/...]`
+ *     envelope identical to the legacy form. Includes `header` +
+ *     structured options so a scripted caller can parse the full shape.
+ */
+export async function dispatchAskUserQuestion(ctx, rawArgs) {
+    const parsed = askUserQuestionSchema.parse(rawArgs);
+    // Schema-level guard against the "Other" leak: the prompt rules tell
+    // the model NEVER to include "Other" in `options`, but we still reject
+    // it defensively in case a future model misreads the spec. The Ink
+    // modal auto-appends "Other" itself; a model-supplied duplicate would
+    // render two "Other" rows.
+    for (const opt of parsed.options) {
+        const trimmed = opt.label.trim().toLowerCase();
+        if (trimmed === 'other' || trimmed === 'другое') {
+            throw new Error('ask_user_question: do NOT include "Other" in options — UI auto-adds it');
+        }
+    }
+    const legacyOptions = parsed.options.map((opt) => opt.label);
+    const result = await askUser(ctx, {
+        question: parsed.question,
+        options: legacyOptions,
+        multiSelect: parsed.multiSelect ?? false,
+    });
+    if (result.answers && result.answers.length > 0) {
+        return {
+            answers: result.answers,
+            envelope: `[ask_user_question:answered] ${result.answers.join(', ')}`,
+        };
+    }
+    // Non-TTY / cancelled / timeout. Re-wrap the envelope so callers can
+    // grep for the structured tool name even when the underlying primitive
+    // surfaced its legacy `[user_input_required]` envelope.
+    if (result.envelope.includes('"reason":"timeout"')) {
+        return { envelope: '[ask_user_question:timeout]' };
+    }
+    if (result.envelope.includes('"reason":"cancelled"')) {
+        return { envelope: '[ask_user_question:cancelled]' };
+    }
+    // Default to the legacy envelope verbatim — it is still
+    // grep-friendly and includes the structured payload above.
+    return { envelope: result.envelope };
+}
+/**
+ * JSON-Schema fragment surfaced to the model via the tool-bridge
+ * `parameters` field. Mirrors the Zod schema 1:1 — kept hand-written
+ * because the runtime engine wires OpenAI-compatible JSON Schema and
+ * the Zod-to-JSON-Schema converter pulls in a transitive dep we have
+ * not greenlit. If the Zod schema above changes, mirror the change here.
+ */
+export const askUserQuestionJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['question', 'header', 'options'],
+    properties: {
+        question: {
+            type: 'string',
+            minLength: ASK_USER_QUESTION_MIN,
+            maxLength: ASK_USER_QUESTION_MAX,
+            description: 'The complete question. Must end with "?". Plain English, no jargon.',
+        },
+        header: {
+            type: 'string',
+            minLength: ASK_USER_QUESTION_HEADER_MIN,
+            maxLength: ASK_USER_QUESTION_HEADER_MAX,
+            description: 'Short chip label (max 12 chars). E.g. "Auth method".',
+        },
+        options: {
+            type: 'array',
+            minItems: ASK_USER_QUESTION_OPTIONS_MIN,
+            maxItems: ASK_USER_QUESTION_OPTIONS_MAX,
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['label', 'description'],
+                properties: {
+                    label: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_LABEL_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_LABEL_MAX,
+                        description: 'Display text. Concise (1-5 words).',
+                    },
+                    description: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_DESC_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_DESC_MAX,
+                        description: 'What this option means / implications.',
+                    },
+                },
+            },
+            description: '2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.',
+        },
+        multiSelect: {
+            type: 'boolean',
+            description: 'Allow multiple selections. Default false.',
+        },
+    },
+};
+//# sourceMappingURL=ask-user-question.js.map