@yagni-app/code 1.0.5 → 1.0.6

package/dist/extension/mcp/prompts.js

@@ -0,0 +1,93 @@
+/**
+ * MCP prompts as dynamically-registered pi slash commands: every prompt a
+ * server exposes becomes `/mcp__<server>__<prompt> [args]` whose handler
+ * fetches the rendered messages and injects them as the next user turn via
+ * pi.sendUserMessage. pi prompt templates are file-only, so runtime
+ * registration is the only path — commands are resolved live on each
+ * getRegisteredCommands() call.
+ */
+import { buildMcpPromptName } from "./names.js";
+export async function registerServerPrompts(pi, manager, serverName) {
+    const server = manager.get(serverName);
+    const result = { commands: [], warnings: [] };
+    if (!server?.client)
+        return result;
+    let promptList;
+    try {
+        promptList = await server.client.listPrompts();
+    }
+    catch (err) {
+        result.warnings.push(`${serverName}: listPrompts failed — ${err instanceof Error ? err.message : String(err)}`);
+        return result;
+    }
+    for (const prompt of promptList.prompts ?? []) {
+        const commandName = buildMcpPromptName(serverName, prompt.name);
+        if (!commandName)
+            continue;
+        const argSpec = (prompt.arguments ?? [])
+            .map((a) => (a.required ? `<${a.name}>` : `[${a.name}]`))
+            .join(" ");
+        pi.registerCommand(commandName, {
+            description: prompt.description
+                ? `${prompt.description} (MCP prompt from "${serverName}")`
+                : `MCP prompt "${prompt.name}" from server "${serverName}"`,
+            handler: async (args, ctx) => {
+                const active = manager.get(serverName);
+                if (!active?.client) {
+                    ctx.ui.notify(`MCP server "${serverName}" is not connected (try /mcp reconnect).`);
+                    return;
+                }
+                const parsedArgs = parsePromptArgs(args);
+                const missing = (prompt.arguments ?? [])
+                    .filter((a) => a.required && parsedArgs[a.name] === undefined)
+                    .map((a) => a.name);
+                if (missing.length > 0) {
+                    ctx.ui.notify(`Missing required argument(s): ${missing.join(", ")}`);
+                    return;
+                }
+                try {
+                    const rendered = await active.client.getPrompt({ name: prompt.name, arguments: parsedArgs });
+                    const text = (rendered.messages ?? [])
+                        .map((m) => {
+                        if (!("content" in m))
+                            return "";
+                        const content = Array.isArray(m.content) ? m.content : [m.content];
+                        return content
+                            .filter((c) => c && typeof c === "object" && "type" in c && c.type === "text")
+                            .map((c) => c.text)
+                            .join("\n");
+                    })
+                        .filter(Boolean)
+                        .join("\n\n");
+                    if (!text) {
+                        ctx.ui.notify(`Prompt "${prompt.name}" returned no text content.`);
+                        return;
+                    }
+                    pi.sendUserMessage(text);
+                }
+                catch (err) {
+                    ctx.ui.notify(`Prompt failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+            ...(argSpec ? { getArgumentCompletions: () => null } : {}),
+        });
+        result.commands.push({
+            command: commandName,
+            serverName,
+            promptName: prompt.name,
+            description: prompt.description ?? `MCP prompt "${prompt.name}"`,
+        });
+    }
+    return result;
+}
+/** "a=1 b=two" → { a: "1", b: "two" }; quotes group spaces. */
+export function parsePromptArgs(args) {
+    const parsed = {};
+    const re = /(\w+)=("([^"]*)"|'([^']*)'|(\S+))/g;
+    let match;
+    while ((match = re.exec(args)) !== null) {
+        parsed[match[1]] = match[3] ?? match[4] ?? match[5] ?? "";
+    }
+    return parsed;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/extension/mcp/startup.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Session wiring for MCP: load config, apply the approval gate and the
+ * kill-switch, connect servers, register tools/prompts/panel, and tear it
+ * all down on session_shutdown. Everything is fail-soft — a broken server
+ * or a broken config file never blocks the session.
+ *
+ * Startup notify (one line when a configured server failed to connect) is a
+ * deliberate deviation from Claude Code, which stays silent on failures.
+ *
+ * `YAGNI_CODE_MCP_DISABLED=1` skips the whole subsystem (kill-switch for
+ * incidents / suspicious servers), mirroring CC's MCP_AUTO_CONNECT killer
+ * but namespaced to this CLI.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { McpManager } from "./manager.js";
+export { _setMcpLogHomeForTest, appendMcpLogLine } from "./log.js";
+export declare function isMcpDisabled(env?: NodeJS.ProcessEnv): boolean;
+export interface StartupOutcome {
+    manager: McpManager;
+    connectedServers: string[];
+    failedServers: {
+        name: string;
+        error: string;
+    }[];
+    /** OAuth servers whose connect threw `UnauthorizedError` (interactive auth pending). */
+    needsAuthServers: string[];
+    skippedApproval: string[];
+    configErrors: string[];
+    /** Full wire names of registered tools that look mutating (gate input). */
+    mutatingToolNames: string[];
+}
+/**
+ * The full session-start sequence. Pure with respect to config homes (tests
+ * point them at tmpdirs via _setMcpHomeForTest / _setMcpLogHomeForTest).
+ */
+export declare function startMcp(pi: ExtensionAPI, opts: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    hasUI: boolean;
+    notify?: (msg: string) => void;
+}): Promise<StartupOutcome>;
+/**
+ * Derive the connectivity startup notices from the manager's LIVE state.
+ *
+ * These must NOT be frozen at `startMcp()` time: the index.ts wiring defers
+ * them to the first provider response, and by then the user may have already
+ * healed a server via `/mcp` (e.g. authenticated a `needs_auth` server). A
+ * server that has since reached `connected` is no longer "needs authentication"
+ * or "failed to connect", so recomputing against `manager.list()` at flush
+ * time is what keeps the banner honest.
+ */
+export declare function deriveStartupConnectivityNotices(manager: McpManager): string[];
+/** Wire shutdown cleanup: closes every transport on session_shutdown (any reason). */
+export declare function wireShutdown(pi: ExtensionAPI, manager: McpManager): void;
+//# sourceMappingURL=startup.d.ts.map

package/dist/extension/mcp/startup.js

@@ -0,0 +1,150 @@
+/**
+ * Session wiring for MCP: load config, apply the approval gate and the
+ * kill-switch, connect servers, register tools/prompts/panel, and tear it
+ * all down on session_shutdown. Everything is fail-soft — a broken server
+ * or a broken config file never blocks the session.
+ *
+ * Startup notify (one line when a configured server failed to connect) is a
+ * deliberate deviation from Claude Code, which stays silent on failures.
+ *
+ * `YAGNI_CODE_MCP_DISABLED=1` skips the whole subsystem (kill-switch for
+ * incidents / suspicious servers), mirroring CC's MCP_AUTO_CONNECT killer
+ * but namespaced to this CLI.
+ */
+import { loadMcpServers, resolveProjectRoot } from "./config.js";
+import { McpManager } from "./manager.js";
+import { readProjectApproval, undecidedProjectServers } from "./approval.js";
+import { registerMcpPanel } from "./panel.js";
+import { registerServerPrompts } from "./prompts.js";
+import { registerServerTools } from "./tools.js";
+// Re-export the log helpers from the shared module so callers (auth.ts) can
+// import logging without taking a dependency on the session wiring that was
+// their previous home.
+export { _setMcpLogHomeForTest, appendMcpLogLine } from "./log.js";
+import { appendMcpLogLine } from "./log.js";
+export function isMcpDisabled(env = process.env) {
+    return env.YAGNI_CODE_MCP_DISABLED === "1";
+}
+/**
+ * The full session-start sequence. Pure with respect to config homes (tests
+ * point them at tmpdirs via _setMcpHomeForTest / _setMcpLogHomeForTest).
+ */
+export async function startMcp(pi, opts) {
+    const env = opts.env ?? process.env;
+    const outcome = {
+        manager: new McpManager({
+            events: { onLog: appendMcpLogLine },
+            env,
+        }),
+        connectedServers: [],
+        failedServers: [],
+        needsAuthServers: [],
+        skippedApproval: [],
+        configErrors: [],
+        mutatingToolNames: [],
+    };
+    if (isMcpDisabled(env)) {
+        appendMcpLogLine(JSON.stringify({ ts: new Date().toISOString(), event: "disabled_by_env" }));
+        return outcome;
+    }
+    const repoRoot = resolveProjectRoot(opts.cwd);
+    const { servers, errors } = loadMcpServers(opts.cwd, env);
+    outcome.configErrors = errors.map((e) => (e.serverName ? `${e.serverName}: ${e.message}` : e.message));
+    registerMcpPanel(pi, outcome.manager, () => outcome.configErrors);
+    if (servers.length === 0 && errors.length === 0)
+        return outcome;
+    // Approval gate for project-scope servers (fail-closed: undecided = skip).
+    const { state } = readProjectApproval(repoRoot);
+    const projectNames = servers.filter((s) => s.scope === "project").map((s) => s.name);
+    const undecided = undecidedProjectServers(state, projectNames);
+    outcome.skippedApproval = undecided;
+    const gate = (server) => {
+        if (server.scope !== "project")
+            return true;
+        return !undecided.includes(server.name);
+    };
+    // Ask once, interactively, about undecided project servers (CC parity).
+    if (undecided.length > 0 && opts.hasUI && opts.notify) {
+        opts.notify(`.mcp.json in this repo defines MCP server(s) ${undecided.join(", ")} — not yet approved. ` +
+            `Run /mcp to approve them individually, or \`yagni mcp reset-project-choices\` to clear old choices.`);
+    }
+    const connectable = [];
+    for (const server of servers) {
+        if (!gate(server)) {
+            outcome.manager.register(server.name, server.scope, server.config, "disabled");
+            continue;
+        }
+        connectable.push(server);
+    }
+    // Connect in parallel; each server fails soft.
+    const results = await Promise.all(connectable.map(async (server) => {
+        const managed = outcome.manager.register(server.name, server.scope, server.config, "connecting");
+        const connected = await outcome.manager.connect(server.name);
+        if (connected?.status === "connected") {
+            const tools = await registerServerTools(pi, outcome.manager, server.name, env);
+            const prompts = await registerServerPrompts(pi, outcome.manager, server.name);
+            outcome.mutatingToolNames.push(...tools.mutatingToolNames);
+            for (const w of [...tools.warnings, ...prompts.warnings])
+                appendMcpLogLine(JSON.stringify({ ts: new Date().toISOString(), server: server.name, event: "registration_warning", warning: w }));
+            return { name: server.name, ok: true, toolCount: tools.tools.length, promptCount: prompts.commands.length };
+        }
+        return {
+            name: server.name,
+            ok: false,
+            needsAuth: connected?.status === "needs_auth",
+            error: connected?.error ?? "connect failed",
+            toolCount: 0,
+            promptCount: 0,
+        };
+    }));
+    for (const r of results) {
+        if (r.ok) {
+            outcome.connectedServers.push(r.name);
+            appendMcpLogLine(JSON.stringify({ ts: new Date().toISOString(), server: r.name, event: "connected", tools: r.toolCount, prompts: r.promptCount }));
+        }
+        else if ("needsAuth" in r && r.needsAuth) {
+            outcome.needsAuthServers.push(r.name);
+            appendMcpLogLine(JSON.stringify({ ts: new Date().toISOString(), server: r.name, event: "needs_auth" }));
+        }
+        else {
+            outcome.failedServers.push({ name: r.name, error: r.error });
+        }
+    }
+    return outcome;
+}
+/**
+ * Derive the connectivity startup notices from the manager's LIVE state.
+ *
+ * These must NOT be frozen at `startMcp()` time: the index.ts wiring defers
+ * them to the first provider response, and by then the user may have already
+ * healed a server via `/mcp` (e.g. authenticated a `needs_auth` server). A
+ * server that has since reached `connected` is no longer "needs authentication"
+ * or "failed to connect", so recomputing against `manager.list()` at flush
+ * time is what keeps the banner honest.
+ */
+export function deriveStartupConnectivityNotices(manager) {
+    const failed = [];
+    const needsAuth = [];
+    for (const server of manager.list()) {
+        if (server.status === "failed")
+            failed.push(server.name);
+        else if (server.status === "needs_auth")
+            needsAuth.push(server.name);
+    }
+    const notices = [];
+    if (failed.length > 0) {
+        notices.push(`MCP server${failed.length === 1 ? "" : "s"} ${failed.join(", ")} failed to connect — run /mcp to inspect or reconnect.`);
+    }
+    if (needsAuth.length > 0) {
+        notices.push(`MCP server${needsAuth.length === 1 ? "" : "s"} ${needsAuth.join(", ")} needs authentication — run /mcp to authenticate.`);
+    }
+    return notices;
+}
+/** Wire shutdown cleanup: closes every transport on session_shutdown (any reason). */
+export function wireShutdown(pi, manager) {
+    pi.on("session_shutdown", async () => {
+        appendMcpLogLine(JSON.stringify({ ts: new Date().toISOString(), event: "session_shutdown" }));
+        await manager.closeAll();
+    });
+}
+//# sourceMappingURL=startup.js.map

package/dist/extension/mcp/tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tool registration for connected MCP servers: one pi tool per MCP tool,
+ * named mcp__<server>__<tool> (Claude Code-compatible, so muscle memory and
+ * prompts transfer). Descriptions are capped at 2048 chars like Claude Code's
+ * client; MCP inputSchemas are plain JSON Schema, which is what TypeBox
+ * schemas are at runtime, so they pass through untouched.
+ *
+ * Known v1 limitation (shared with early Claude Code): tools are registered
+ * eagerly per server — a server exposing 100 tools puts 100 tools into every
+ * request. No tool-list deferral / ToolSearch in v1.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { McpManager } from "./manager.js";
+export declare const MAX_MCP_DESCRIPTION_LENGTH = 2048;
+export interface RegisteredToolInfo {
+    toolName: string;
+    serverName: string;
+    originalName: string;
+    description: string;
+}
+export interface ToolRegistrationResult {
+    tools: RegisteredToolInfo[];
+    /** Full registered tool names that look mutating (gate input). */
+    mutatingToolNames: string[];
+    warnings: string[];
+}
+export declare function registerServerTools(pi: ExtensionAPI, manager: McpManager, serverName: string, env?: NodeJS.ProcessEnv): Promise<ToolRegistrationResult>;
+export declare function capDescription(description: string): string;
+/** Cheap heuristic in the spirit of Claude Code's input-hint check; per-tool annotations arrive via listTools only in newer servers. */
+export declare function looksMutating(toolName: string, description?: string): boolean;
+//# sourceMappingURL=tools.d.ts.map

package/dist/extension/mcp/tools.js

@@ -0,0 +1,117 @@
+/**
+ * Tool registration for connected MCP servers: one pi tool per MCP tool,
+ * named mcp__<server>__<tool> (Claude Code-compatible, so muscle memory and
+ * prompts transfer). Descriptions are capped at 2048 chars like Claude Code's
+ * client; MCP inputSchemas are plain JSON Schema, which is what TypeBox
+ * schemas are at runtime, so they pass through untouched.
+ *
+ * Known v1 limitation (shared with early Claude Code): tools are registered
+ * eagerly per server — a server exposing 100 tools puts 100 tools into every
+ * request. No tool-list deferral / ToolSearch in v1.
+ */
+import { toolTimeoutFromEnv } from "./manager.js";
+import { buildMcpToolName } from "./names.js";
+export const MAX_MCP_DESCRIPTION_LENGTH = 2048;
+export async function registerServerTools(pi, manager, serverName, env = process.env) {
+    const server = manager.get(serverName);
+    const result = { tools: [], mutatingToolNames: [], warnings: [] };
+    if (!server?.client)
+        return result;
+    let toolList;
+    try {
+        toolList = await server.client.listTools();
+    }
+    catch (err) {
+        result.warnings.push(`${serverName}: listTools failed — ${err instanceof Error ? err.message : String(err)}`);
+        return result;
+    }
+    const toolTimeout = toolTimeoutFromEnv(env);
+    for (const tool of toolList.tools ?? []) {
+        const fullToolName = buildMcpToolName(serverName, tool.name);
+        if (!fullToolName) {
+            result.warnings.push(`${serverName}: tool "${tool.name}" produced an empty wire name; skipped`);
+            continue;
+        }
+        const description = capDescription(`${tool.description ?? `MCP tool ${tool.name}`} (MCP server "${serverName}")`);
+        const mutating = looksMutating(tool.name, tool.description);
+        const definition = {
+            name: fullToolName,
+            label: `${serverName}: ${tool.name}`,
+            description,
+            parameters: schemaFor(tool.inputSchema),
+            async execute(_toolCallId, params) {
+                const active = manager.get(serverName);
+                if (!active?.client) {
+                    throw new Error(`MCP server "${serverName}" is not connected (try /mcp reconnect).`);
+                }
+                const args = (params && typeof params === "object" ? params : {});
+                const call = active.client.callTool({ name: tool.name, arguments: args });
+                const settled = toolTimeout
+                    ? await withTimeout(call, toolTimeout, `MCP tool call timed out after ${toolTimeout}ms`)
+                    : await call;
+                return renderCallResult(settled, serverName, tool.name);
+            },
+        };
+        pi.registerTool(definition);
+        result.tools.push({ toolName: fullToolName, serverName, originalName: tool.name, description });
+        if (mutating)
+            result.mutatingToolNames.push(fullToolName);
+    }
+    return result;
+}
+export function capDescription(description) {
+    return description.length > MAX_MCP_DESCRIPTION_LENGTH
+        ? description.slice(0, MAX_MCP_DESCRIPTION_LENGTH - 1) + "…"
+        : description;
+}
+/** Cheap heuristic in the spirit of Claude Code's input-hint check; per-tool annotations arrive via listTools only in newer servers. */
+export function looksMutating(toolName, description) {
+    const name = toolName.toLowerCase();
+    const writeHints = /^(create|add|update|edit|delete|remove|set|write|send|post|put|patch|deploy|publish|close|merge|assign|move|archive|trash|restore)/;
+    if (writeHints.test(name))
+        return true;
+    if (description) {
+        const d = description.toLowerCase();
+        if (/\b(create|delete|update|modify|write|send|publish|deploy|remove)s?\b/.test(d.slice(0, 400)))
+            return true;
+    }
+    return false;
+}
+function schemaFor(inputSchema) {
+    if (inputSchema !== null &&
+        typeof inputSchema === "object" &&
+        !Array.isArray(inputSchema) &&
+        Object.keys(inputSchema).length > 0) {
+        // MCP inputSchemas are plain JSON Schema objects, which is exactly what
+        // TypeBox schemas are at runtime — pass the server's schema through so
+        // the model sees real parameter shapes.
+        return inputSchema;
+    }
+    return { type: "object", properties: {} };
+}
+function renderCallResult(settled, serverName, toolName) {
+    const parts = [];
+    for (const item of settled.content ?? []) {
+        if (item && typeof item === "object" && item.type === "text") {
+            parts.push(String(item.text ?? ""));
+        }
+    }
+    const text = parts.join("\n") || "(no text content)";
+    if (settled.isError === true) {
+        throw new Error(`MCP tool error from "${serverName}.${toolName}": ${text}`);
+    }
+    return { content: [{ type: "text", text }], details: { server: serverName, tool: toolName } };
+}
+function withTimeout(promise, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/extension/mcp/transports.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Transport construction: config shape → SDK transport instance. Kept as a
+ * separate module so tests can construct transports without a live process,
+ * and so the manager stays free of SDK import-path churn.
+ */
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { McpHttpServerConfig, McpServerConfig, McpStdioServerConfig } from "./config.js";
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 30000;
+export declare function stdioTransport(config: McpStdioServerConfig): StdioClientTransport;
+export declare function httpTransport(config: McpHttpServerConfig, authProvider?: OAuthClientProvider, fetchImpl?: typeof fetch): StreamableHTTPClientTransport;
+export declare function sseTransport(config: McpHttpServerConfig, authProvider?: OAuthClientProvider, fetchImpl?: typeof fetch): SSEClientTransport;
+export declare function transportFor(config: McpServerConfig, authProvider?: OAuthClientProvider, fetchImpl?: typeof fetch): Transport;
+//# sourceMappingURL=transports.d.ts.map

package/dist/extension/mcp/transports.js

@@ -0,0 +1,44 @@
+/**
+ * Transport construction: config shape → SDK transport instance. Kept as a
+ * separate module so tests can construct transports without a live process,
+ * and so the manager stays free of SDK import-path churn.
+ */
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+export const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+export function stdioTransport(config) {
+    return new StdioClientTransport({
+        command: config.command,
+        args: config.args ?? [],
+        env: config.env,
+        stderr: "pipe",
+    });
+}
+export function httpTransport(config, authProvider, fetchImpl) {
+    const url = new URL(config.url);
+    const headers = { ...config.headers };
+    return new StreamableHTTPClientTransport(url, {
+        requestInit: { headers },
+        ...(authProvider ? { authProvider } : {}),
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+}
+export function sseTransport(config, authProvider, fetchImpl) {
+    const headers = { ...config.headers };
+    return new SSEClientTransport(new URL(config.url), {
+        eventSourceInit: {},
+        requestInit: { headers },
+        ...(authProvider ? { authProvider } : {}),
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+}
+export function transportFor(config, authProvider, fetchImpl) {
+    if (config.type === "http")
+        return httpTransport(config, authProvider, fetchImpl);
+    if (config.type === "sse")
+        return sseTransport(config, authProvider, fetchImpl);
+    // type "stdio" or absent (CC-style bare command entries)
+    return stdioTransport(config);
+}
+//# sourceMappingURL=transports.js.map

package/dist/extension/permission/gate.d.ts

@@ -53,6 +53,13 @@ export interface PermissionPolicy {
     reviewConfirmTools: string[];
     /** Consequential external writes that require fresh consent in every mode. */
     alwaysConfirmTools?: string[];
+    /**
+     * Optional predicate: this tool is a mutating action (an MCP server tool
+     * that writes, for instance) so it joins planBlock/reviewConfirm even
+     * though it was registered dynamically and never appears in the static
+     * lists above. Evaluated AFTER the static lists (a static entry wins).
+     */
+    isMutating?: (toolName: string) => boolean;
     /**
      * Optional: a recorded decision already blesses this action, so it auto-runs in
      * review mode instead of prompting. The hook for tying the gate to captured

package/dist/extension/permission/gate.js

@@ -92,7 +92,7 @@ export function decideGate(toolName, params, mode, policy) {
             }
             return { block: false };
         }
-        if (policy.planBlockTools.includes(toolName)) {
+        if (policy.planBlockTools.includes(toolName) || policy.isMutating?.(toolName)) {
             return {
                 block: true,
                 reason: `plan mode: ${toolName} is a write or exec action and is held. Switch to /mode auto to apply changes.`,
@@ -142,7 +142,7 @@ export function decideGate(toolName, params, mode, policy) {
     if (mode === "auto")
         return { block: false };
     // review
-    if (policy.reviewConfirmTools.includes(toolName)) {
+    if (policy.reviewConfirmTools.includes(toolName) || policy.isMutating?.(toolName)) {
         if (policy.isBlessed?.(toolName, params))
             return { block: false };
         return { block: false, confirm: true };
@@ -314,6 +314,8 @@ export function registerPermissionGate(pi, deps = {}) {
         // and dropping it here silently reverts every custom policy to the
         // default (round-2 review blocker).
         execPolicy: basePolicy.execPolicy,
+        // Same carry-through for the mutating-tool predicate (dynamic mcp__* tools).
+        isMutating: basePolicy.isMutating,
         isBlessed: basePolicy.isBlessed ?? ((tool, params) => blessStore?.isBlessed(tool, params) ?? false),
     };
     const sideEffects = sideEffectTools(effectivePolicy);
@@ -575,6 +577,7 @@ export function registerPermissionGate(pi, deps = {}) {
                         void Promise.resolve(deps.onGuardianReview(buildDiagnosticEvent(outcome, {
                             durationMs,
                             tier: guardianTier,
+                            ...(reviewResult.repaired ? { repaired: true } : {}),
                             ...(rationale ? { rationale } : {}),
                             ...(rawOutput ? { rawOutput } : {}),
                             debug: isDebug(),
@@ -583,7 +586,11 @@ export function registerPermissionGate(pi, deps = {}) {
                     const verdict = reviewResult.verdict;
                     if (verdict?.outcome === "allow") {
                         guardianState.recordReview("allow");
-                        emitDiag("allow", verdict.rationale);
+                        // A repaired verdict is a REAL allow: it flows through the normal
+                        // path; the diag event carries `repaired` + the pre-repair shape so
+                        // telemetry can count salvage hits (the rawOutput is already
+                        // scrubbed + capped at the source).
+                        emitDiag("allow", verdict.rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
                         emitGateEvent({
                             ...eventBase,
                             outcome: "allow",
@@ -597,7 +604,7 @@ export function registerPermissionGate(pi, deps = {}) {
                     if (verdict?.outcome === "deny") {
                         guardianState.recordReview("deny");
                         const rationale = verdict.rationale;
-                        emitDiag("deny", rationale);
+                        emitDiag("deny", rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
                         emitGateEvent({
                             ...eventBase,
                             outcome: "deny",
@@ -622,7 +629,7 @@ export function registerPermissionGate(pi, deps = {}) {
                     }
                     if (verdict?.outcome === "ask") {
                         guardianState.recordReview("ask");
-                        emitDiag("ask", verdict.rationale);
+                        emitDiag("ask", verdict.rationale, reviewResult.repaired ? reviewResult.rawOutput : undefined);
                         if (!ctx?.hasUI) {
                             // Headless (includes every /go child stage): fail closed.
                             emitGateEvent({

package/dist/extension/permission/guardian.d.ts

@@ -99,6 +99,14 @@ export interface CircuitBreakerResult {
     reason?: string;
 }
 export declare function checkCircuitBreaker(state: GuardianState, limits: GuardianLimits): CircuitBreakerResult;
+export interface ParsedVerdict {
+    verdict: GuardianVerdict;
+    /** True when the strict parse failed and the lenient repair ladder salvaged it. */
+    repaired: boolean;
+}
+export declare function parseVerdictDetailed(raw: string): ParsedVerdict | null;
+/** Strict-shaped convenience wrapper: the verdict, or null. Callers that need
+ * the repaired signal use {@link parseVerdictDetailed}. */
 export declare function parseVerdict(raw: string): GuardianVerdict | null;
 export declare function formatGuardianSubtotal(state: GuardianState, limits: GuardianLimits): string;
 export type GuardianError = "timeout" | "malformed" | "network" | "empty" | "aborted";
@@ -106,11 +114,17 @@ export interface ReviewResult {
     verdict: GuardianVerdict | null;
     error?: GuardianError;
     cost: number;
+    /** True when the verdict came from the lenient repair ladder (strict parse
+     * failed first). The verdict is real and flows through the normal
+     * allow/ask/deny handling; this flag only marks it for telemetry. */
+    repaired?: boolean;
     /**
      * Scrubbed + capped copy of the model output when the verdict failed to
-     * parse (`error: "malformed"`). Present so the sink can capture the exact
-     * failure shape. Never contains the raw command unredacted: `scrubSecrets`
-     * removes secret-shaped values before this is stored.
+     * parse (`error: "malformed"`), or of the pre-repair extracted block when
+     * the repair ladder salvaged it (`repaired: true`). Present so the sink can
+     * capture the exact failure shape either way. Never contains the raw
+     * command unredacted: `scrubSecrets` removes secret-shaped values before
+     * this is stored.
      */
     rawOutput?: string;
 }
@@ -152,14 +166,18 @@ export interface GuardianDiagnosticEvent {
     outcome: GuardianOutcome | GuardianError;
     durationMs?: number;
     tier?: string;
+    /** True when the lenient repair ladder salvaged a broken verdict — the
+     * outcome is still the REAL verdict (allow/ask/deny); this flag marks it
+     * for telemetry so repair hit-rate is measurable. */
+    repaired?: true;
     /** Debug-only: command hash for correlation (never the raw command). */
     commandHash?: string;
     /** Debug-only: the Guardian's rationale. */
     rationale?: string;
     /**
      * Scrubbed + capped copy of the unparseable model output, present only for
-     * `outcome: "malformed"`. Always-on (NOT debug-gated): it is already
-     * `scrubSecrets`-redacted and size-capped at the source.
+     * `outcome: "malformed"` or `repaired: true`. Always-on (NOT debug-gated):
+     * it is already `scrubSecrets`-redacted and size-capped at the source.
      */
     rawOutput?: string;
 }
@@ -170,6 +188,7 @@ export interface GuardianDiagnosticEvent {
 export declare function buildDiagnosticEvent(outcome: GuardianOutcome | GuardianError, opts: {
     durationMs?: number;
     tier?: string;
+    repaired?: boolean;
     rationale?: string;
     commandHash?: string;
     rawOutput?: string;