ast-mcp-server 0.11.2 → 0.13.0

package/dist/services/agent-targets.js

@@ -1,18 +1,9 @@
+import { toolCatalog } from "../tools/catalog.js";
 export const MCP_SERVER_NAME = "ast";
-const EXPECTED_TOOLS = [
-    "ast_list_files",
-    "ast_get_outline",
-    "ast_get_symbol_source",
-    "ast_search_symbols",
-    "ast_find_references",
-    "ast_find_test_candidates",
-    "ast_get_diagnostics",
-    "ast_rename_symbol",
-    "ast_replace_symbol_body",
-    "ast_scaffold_class",
-    "ast_get_operation_preview",
-    "ast_apply_operation",
-];
+const EXPECTED_TOOLS = toolCatalog.compatibility.required;
+const APPLY_TOOL = "ast_apply_operation";
+/** Ambient agent surfaces opt into the apply-effect tool (fail-closed guard default is deny). */
+const APPLY_GUARD_ALLOW_ENV = "AST_MCP_APPLY_GUARD=allow";
 function semver(value) {
     const match = value.match(/(?:^|\s|v)(\d+)\.(\d+)\.(\d+)(?=\s|$|[-+()]|\.(?:\s|$))/);
     return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
@@ -40,6 +31,32 @@ function expected(context, command, args) {
         args.length === 1 &&
         args[0] === context.serverEntryPath);
 }
+function structuredGuardStatus(...values) {
+    const provided = values.filter((value) => value !== undefined);
+    if (provided.length === 0)
+        return "repairable";
+    const records = provided.filter((value) => value !== null && typeof value === "object" && !Array.isArray(value));
+    return records.length === provided.length &&
+        records.length === 1 &&
+        Object.keys(records[0]).length === 1 &&
+        records[0].AST_MCP_APPLY_GUARD === "allow"
+        ? "current"
+        : "conflict";
+}
+function matchingRegistration(hasExpectedCommand, guardStatus) {
+    if (!hasExpectedCommand) {
+        return {
+            status: "conflict",
+            detail: "The existing 'ast' registration does not match this package.",
+        };
+    }
+    return guardStatus === "conflict"
+        ? {
+            status: "conflict",
+            detail: "The existing 'ast' registration has unsupported environment settings.",
+        }
+        : { status: guardStatus };
+}
 function parseJson(result) {
     try {
         return JSON.parse(result.stdout);
@@ -58,12 +75,7 @@ function structuredInspection(result, context) {
     if (!value || value.name !== MCP_SERVER_NAME)
         return { status: "error", operation: "MCP inspection", result };
     const transport = (value.transport ?? value);
-    return expected(context, transport.command, transport.args)
-        ? { status: "current" }
-        : {
-            status: "conflict",
-            detail: "The existing 'ast' registration does not match this package.",
-        };
+    return matchingRegistration(transport.type === "stdio" && expected(context, transport.command, transport.args), structuredGuardStatus(transport.env, transport.environment));
 }
 function copilotStructuredInspection(result, context) {
     if (result.exitCode !== 0) {
@@ -77,18 +89,35 @@ function copilotStructuredInspection(result, context) {
         return { status: "error", operation: "MCP inspection", result };
     }
     const configuration = server;
-    return configuration.type === "local" &&
+    const matches = configuration.type === "local" &&
         configuration.source === "user" &&
         configuration.enabled === true &&
         Array.isArray(configuration.tools) &&
         configuration.tools.length === 1 &&
         configuration.tools[0] === "*" &&
-        expected(context, configuration.command, configuration.args)
-        ? { status: "current" }
-        : {
-            status: "conflict",
+        expected(context, configuration.command, configuration.args);
+    const inspection = matchingRegistration(matches, structuredGuardStatus(configuration.env, configuration.environment));
+    return inspection.status === "conflict"
+        ? {
+            ...inspection,
             detail: "The existing user-scoped 'ast' registration does not match this package.",
-        };
+        }
+        : inspection;
+}
+function claudeRegister(runtime, context, guarded) {
+    return runtime.run([
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
+        "--transport",
+        "stdio",
+        MCP_SERVER_NAME,
+        "--",
+        context.nodeExecutable,
+        context.serverEntryPath,
+    ]);
 }
 const claudeMcp = {
     async inspect(runtime, context) {
@@ -100,87 +129,140 @@ const claudeMcp = {
                 : { status: "error", operation: "MCP inspection", result };
         const fields = new Map();
         for (const line of result.stdout.split(/\r?\n/)) {
-            const match = line.match(/^\s*(Status|Type|Command|Args):\s*(.*)$/i);
+            const match = line.match(/^\s*(Scope|Status|Type|Command|Args):\s*(.*)$/i);
             if (match)
                 fields.set(match[1].toLowerCase(), match[2].trim());
         }
-        return /connected/i.test(fields.get("status") ?? "") &&
+        const matches = /^user config\b/i.test(fields.get("scope") ?? "") &&
+            /connected/i.test(fields.get("status") ?? "") &&
             fields.get("type")?.toLowerCase() === "stdio" &&
-            expected(context, fields.get("command"), [fields.get("args")])
-            ? { status: "current" }
-            : {
-                status: "conflict",
+            expected(context, fields.get("command"), [fields.get("args")]);
+        const hasEnvironment = /^\s*Environment:\s*$/im.test(result.stdout);
+        const inspection = matchingRegistration(matches, /(?:^|\s)AST_MCP_APPLY_GUARD\s*=\s*allow(?:\s|$)/m.test(result.stdout)
+            ? "current"
+            : hasEnvironment
+                ? "conflict"
+                : "repairable");
+        return inspection.status === "conflict"
+            ? {
+                ...inspection,
                 detail: "The existing user-scoped 'ast' registration does not match this package.",
-            };
+            }
+            : inspection;
     },
-    register: (runtime, context) => runtime.run([
+    register: (runtime, context) => claudeRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME, "--scope", "user"]),
+    registerLegacy: (runtime, context) => claudeRegister(runtime, context, false),
+    registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
+};
+function hermesRegister(runtime, context, guarded) {
+    return runtime.run([
         "mcp",
         "add",
-        "--scope",
-        "user",
-        "--transport",
-        "stdio",
         MCP_SERVER_NAME,
-        "--",
+        "--command",
         context.nodeExecutable,
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
+        "--args",
         context.serverEntryPath,
-    ]),
-    registrationAccepted: (result) => result.exitCode === 0,
-};
+    ], "\n");
+}
 const hermesMcp = {
-    async inspect(runtime) {
+    async inspect(runtime, context) {
         const listed = await runtime.run(["mcp", "list"]);
         if (listed.exitCode !== 0)
             return { status: "error", operation: "MCP list", result: listed };
         if (!/^\s*ast(?:\s|$)/im.test(listed.stdout))
             return { status: "missing" };
-        const tested = await runtime.run(["mcp", "test", MCP_SERVER_NAME]);
-        return tested.exitCode === 0 && EXPECTED_TOOLS.every((tool) => tested.stdout.includes(tool))
-            ? { status: "current" }
-            : {
+        const configured = await runtime.run(["config", "get", "mcp_servers.ast", "--json"]);
+        const registration = parseJson(configured);
+        if (configured.exitCode !== 0 ||
+            !registration ||
+            Array.isArray(registration) ||
+            !expected(context, registration.command, registration.args)) {
+            return {
                 status: "conflict",
-                detail: "The existing 'ast' registration does not expose the expected structural tools.",
+                detail: "The existing 'ast' registration cannot be authenticated as this package.",
             };
+        }
+        const guardStatus = structuredGuardStatus(registration.env);
+        const admittedKeys = guardStatus === "repairable" ? ["args", "command"] : ["args", "command", "env"];
+        if (guardStatus === "conflict" ||
+            Object.keys(registration).sort().join(",") !== admittedKeys.join(",")) {
+            return {
+                status: "conflict",
+                detail: "The existing 'ast' registration has unsupported configuration.",
+            };
+        }
+        const tested = await runtime.run(["mcp", "test", MCP_SERVER_NAME]);
+        const expectedWithoutApply = EXPECTED_TOOLS.filter((tool) => tool !== APPLY_TOOL);
+        if (tested.exitCode === 0 &&
+            expectedWithoutApply.every((tool) => tested.stdout.includes(tool))) {
+            const applyPresent = !EXPECTED_TOOLS.includes(APPLY_TOOL) || tested.stdout.includes(APPLY_TOOL);
+            return guardStatus === "current" && applyPresent
+                ? { status: "current" }
+                : guardStatus === "repairable" && !tested.stdout.includes(APPLY_TOOL)
+                    ? { status: "repairable" }
+                    : {
+                        status: "conflict",
+                        detail: "The existing 'ast' registration tool surface contradicts its configuration.",
+                    };
+        }
+        return {
+            status: "conflict",
+            detail: "The existing 'ast' registration does not expose the expected structural tools.",
+        };
     },
-    register: (runtime, context) => runtime.run([
+    register: (runtime, context) => hermesRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME]),
+    registerLegacy: (runtime, context) => hermesRegister(runtime, context, false),
+    registrationAccepted: (result) => result.exitCode === 0 && /saved\s+'ast'/i.test(result.stdout),
+    removalAccepted: (result) => result.exitCode === 0,
+};
+function separatorRegister(runtime, context, guarded) {
+    return runtime.run([
         "mcp",
         "add",
         MCP_SERVER_NAME,
-        "--command",
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
+        "--",
         context.nodeExecutable,
-        "--args",
         context.serverEntryPath,
-    ], "\n"),
-    registrationAccepted: (result) => result.exitCode === 0 && /saved\s+'ast'/i.test(result.stdout),
-};
+    ]);
+}
 const codexMcp = {
     async inspect(runtime, context) {
         return structuredInspection(await runtime.run(["mcp", "get", MCP_SERVER_NAME, "--json"]), context);
     },
-    register: (runtime, context) => runtime.run([
-        "mcp",
-        "add",
-        MCP_SERVER_NAME,
-        "--",
-        context.nodeExecutable,
-        context.serverEntryPath,
-    ]),
+    register: (runtime, context) => separatorRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME]),
+    registerLegacy: (runtime, context) => separatorRegister(runtime, context, false),
     registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
 };
 const copilotMcp = {
     async inspect(runtime, context) {
         return copilotStructuredInspection(await runtime.run(["mcp", "get", MCP_SERVER_NAME, "--json"]), context);
     },
-    register: (runtime, context) => runtime.run([
+    register: (runtime, context) => separatorRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME]),
+    registerLegacy: (runtime, context) => separatorRegister(runtime, context, false),
+    registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
+};
+function geminiRegister(runtime, context, guarded) {
+    return runtime.run([
         "mcp",
         "add",
         MCP_SERVER_NAME,
-        "--",
+        ...(guarded ? ["--env", APPLY_GUARD_ALLOW_ENV] : []),
         context.nodeExecutable,
         context.serverEntryPath,
-    ]),
-    registrationAccepted: (result) => result.exitCode === 0,
-};
+        "--scope",
+        "user",
+    ]);
+}
 const geminiMcp = {
     async inspect(runtime, context) {
         const result = await runtime.run(["mcp", "list"]);
@@ -199,23 +281,24 @@ const geminiMcp = {
         const match = result.stdout.match(pattern);
         if (!match)
             return { status: "error", operation: "MCP inspection", result };
-        return expected(context, match[1]?.trim(), match[2]?.split(",").map((item) => item.trim()))
-            ? { status: "current" }
-            : {
+        const matches = expected(context, match[1]?.trim(), match[2]?.split(",").map((item) => item.trim()));
+        const inspection = matchingRegistration(matches, /(?:^|\s|,)AST_MCP_APPLY_GUARD\s*=\s*allow(?:\s|$|,)/m.test(result.stdout)
+            ? "current"
+            : /\benv(?:ironment)?\s*:/i.test(result.stdout)
+                ? "conflict"
+                : "repairable");
+        return inspection.status === "conflict"
+            ? {
                 status: "conflict",
                 detail: "The existing Gemini 'ast' registration does not match this package.",
-            };
+            }
+            : inspection;
     },
-    register: (runtime, context) => runtime.run([
-        "mcp",
-        "add",
-        MCP_SERVER_NAME,
-        context.nodeExecutable,
-        context.serverEntryPath,
-        "--scope",
-        "user",
-    ]),
+    register: (runtime, context) => geminiRegister(runtime, context, true),
+    unregister: (runtime) => runtime.run(["mcp", "remove", MCP_SERVER_NAME, "--scope", "user"]),
+    registerLegacy: (runtime, context) => geminiRegister(runtime, context, false),
     registrationAccepted: (result) => result.exitCode === 0,
+    removalAccepted: (result) => result.exitCode === 0,
 };
 const opencodeMcp = {
     async inspect() {
@@ -232,7 +315,14 @@ const opencodeMcp = {
     async register() {
         return { exitCode: 1, stdout: "", stderr: "OpenCode CLI registration is disabled." };
     },
+    async unregister() {
+        return { exitCode: 1, stdout: "", stderr: "OpenCode CLI removal is disabled." };
+    },
+    async registerLegacy() {
+        return { exitCode: 1, stdout: "", stderr: "OpenCode CLI registration is disabled." };
+    },
     registrationAccepted: () => false,
+    removalAccepted: () => false,
 };
 export const AGENT_TARGETS = [
     { id: "claude", label: "Claude Code", command: "claude", skillTarget: "claude", mcp: claudeMcp },

package/dist/services/diagnostics.js

@@ -1,6 +1,61 @@
 import path from "node:path";
 import { DiagnosticCategory, ts } from "ts-morph";
 import { NO_REQUEST_CONTEXT } from "./request-context.js";
+export const DIAGNOSTIC_AGGREGATE_GROUP_LIMIT = 20;
+function safeCount(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("Diagnostic aggregate count is outside the safe integer range.");
+    }
+    return value;
+}
+function increment(counts, key) {
+    counts.set(key, safeCount((counts.get(key) ?? 0) + 1));
+}
+function rankGroups(counts, createGroup, compareKey, groupedDiagnosticCount, requestContext) {
+    const groups = [];
+    for (const [key, count] of counts) {
+        requestContext.checkpoint();
+        groups.push(createGroup(key, safeCount(count)));
+    }
+    groups.sort((left, right) => {
+        requestContext.checkpoint();
+        return right.count - left.count || compareKey(left, right);
+    });
+    const selected = groups.slice(0, DIAGNOSTIC_AGGREGATE_GROUP_LIMIT);
+    const covered = safeCount(selected.reduce((total, group) => safeCount(total + group.count), 0));
+    const omittedGroups = safeCount(groups.length - selected.length);
+    return {
+        groups: selected,
+        total_group_count: safeCount(groups.length),
+        omitted_group_count: omittedGroups,
+        covered_diagnostic_count: covered,
+        omitted_diagnostic_count: safeCount(groupedDiagnosticCount - covered),
+        truncated: omittedGroups > 0,
+    };
+}
+export function buildDiagnosticAggregates(diagnostics, requestContext = NO_REQUEST_CONTEXT) {
+    requestContext.checkpoint();
+    const codeCounts = new Map();
+    const fileCounts = new Map();
+    let unfiled = 0;
+    for (const diagnostic of diagnostics) {
+        requestContext.checkpoint();
+        increment(codeCounts, diagnostic.code);
+        if (diagnostic.file === null) {
+            unfiled = safeCount(unfiled + 1);
+        }
+        else {
+            increment(fileCounts, diagnostic.file);
+        }
+    }
+    const codes = rankGroups(codeCounts, (code, count) => ({ code, count }), (left, right) => left.code - right.code, safeCount(diagnostics.length), requestContext);
+    const files = rankGroups(fileCounts, (file, count) => ({ file, count }), (left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0), safeCount(diagnostics.length - unfiled), requestContext);
+    return {
+        group_limit: DIAGNOSTIC_AGGREGATE_GROUP_LIMIT,
+        codes,
+        files: { ...files, unfiled_diagnostic_count: unfiled },
+    };
+}
 export function normalizeDiagnostic(diagnostic, projectRoot, requestContext = NO_REQUEST_CONTEXT) {
     requestContext.checkpoint();
     const sourceFile = diagnostic.getSourceFile();

package/dist/services/opencode-config.js

@@ -3,6 +3,49 @@ import { link, mkdir, mkdtemp, open, readFile, rename, rm, stat, writeFile, } fr
 import os from "node:os";
 import path from "node:path";
 import { applyEdits, modify, parse } from "jsonc-parser";
+export class OpenCodeConfigRecoveryError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "OpenCodeConfigRecoveryError";
+    }
+}
+function desiredAst(nodeExecutable, serverEntryPath) {
+    return {
+        type: "local",
+        command: [nodeExecutable, serverEntryPath],
+        enabled: true,
+        environment: { AST_MCP_APPLY_GUARD: "allow" },
+    };
+}
+export function classifyOpenCodeAstRegistration(value, nodeExecutable, serverEntryPath) {
+    if (value === undefined)
+        return "missing";
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return "conflict";
+    const registration = value;
+    const command = registration.command;
+    const baseMatches = registration.type === "local" &&
+        registration.enabled === true &&
+        Array.isArray(command) &&
+        command.length === 2 &&
+        command[0] === nodeExecutable &&
+        command[1] === serverEntryPath;
+    if (!baseMatches)
+        return "conflict";
+    const keys = Object.keys(registration).sort().join(",");
+    if (keys === "command,enabled,type")
+        return "repairable";
+    if (keys !== "command,enabled,environment,type")
+        return "conflict";
+    const environment = registration.environment;
+    return environment !== null &&
+        typeof environment === "object" &&
+        !Array.isArray(environment) &&
+        Object.keys(environment).length === 1 &&
+        environment.AST_MCP_APPLY_GUARD === "allow"
+        ? "current"
+        : "conflict";
+}
 function hash(value) {
     return createHash("sha256").update(value).digest("hex");
 }
@@ -80,14 +123,11 @@ export async function planOpenCodeConfig(options) {
     }
     if (!parsed || typeof parsed !== "object")
         throw new Error("OpenCode configuration must contain an object.");
-    const desired = {
-        type: "local",
-        command: [options.nodeExecutable, options.serverEntryPath],
-        enabled: true,
-    };
-    if (parsed.mcp?.ast !== undefined && JSON.stringify(parsed.mcp.ast) !== JSON.stringify(desired))
+    const desired = desiredAst(options.nodeExecutable, options.serverEntryPath);
+    const registrationStatus = classifyOpenCodeAstRegistration(parsed.mcp?.ast, options.nodeExecutable, options.serverEntryPath);
+    if (registrationStatus === "conflict")
         throw new Error("OpenCode configuration conflict at mcp.ast.");
-    const content = parsed.mcp?.ast === undefined
+    const content = registrationStatus === "missing" || registrationStatus === "repairable"
         ? applyEdits(before, modify(before, ["mcp", "ast"], desired, {
             formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" },
         }))
@@ -96,6 +136,7 @@ export async function planOpenCodeConfig(options) {
         filePath: options.filePath,
         beforeHash: hash(beforeExists ? before : ""),
         beforeExists,
+        beforeContent: beforeExists ? before : "",
         mode,
         content,
         status: content === before ? "unchanged" : "installed",
@@ -146,3 +187,39 @@ export async function applyOpenCodeConfigPlan(plan) {
         await rm(temporary, { force: true });
     }
 }
+async function inspectOpenCodeConfigPlanState(plan) {
+    let content = "";
+    let exists = true;
+    let mode;
+    try {
+        content = await readFile(plan.filePath, "utf8");
+        mode = (await stat(plan.filePath)).mode & 0o777;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            exists = false;
+        else
+            throw error;
+    }
+    if (!plan.beforeExists && !exists)
+        return "preimage";
+    if (plan.beforeExists && exists && content === plan.beforeContent && mode === plan.mode)
+        return "preimage";
+    if (exists && content === plan.content && mode === plan.mode)
+        return "postimage";
+    return "conflict";
+}
+export async function runOpenCodeConfigTransaction(plan, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const state = await inspectOpenCodeConfigPlanState(plan);
+        if (state === "postimage")
+            return undefined;
+        if (state === "conflict") {
+            throw new OpenCodeConfigRecoveryError("OpenCode configuration changed concurrently after an ambiguous write outcome; the concurrent bytes were preserved.", { cause: error });
+        }
+        throw error;
+    }
+}

package/dist/services/runtime-policy.js

@@ -7,6 +7,7 @@ export const RUNTIME_POLICY_ENV_KEYS = Object.freeze([
     "AST_SHUTDOWN_DRAIN_TIMEOUT_MS",
     "AST_COMPILER_WORKER_MODE",
     "AST_COMPILER_WORKER_IDLE_TTL_MS",
+    "AST_MCP_APPLY_GUARD",
 ]);
 function parseBoundedInteger(rawValue, defaultValue, minimum, maximum) {
     if (rawValue === undefined)
@@ -37,6 +38,15 @@ export function parseRuntimePolicy(environment) {
             ? "configured"
             : "invalid_mode";
     const compilerWorkerIdleTtlMs = parseBoundedInteger(environment.AST_COMPILER_WORKER_IDLE_TTL_MS, 60_000, 0, 86_400_000);
+    const rawApplyGuard = environment.AST_MCP_APPLY_GUARD;
+    // Fail-closed: only an explicit `allow` permits the apply-effect MCP tool on
+    // this surface. A missing value, `deny`, or any invalid value denies apply.
+    const denyApply = rawApplyGuard !== "allow";
+    const applyGuardReason = rawApplyGuard === undefined
+        ? "default"
+        : rawApplyGuard === "allow" || rawApplyGuard === "deny"
+            ? "configured"
+            : "invalid_mode";
     const reasons = Object.freeze({
         AST_MAX_PROJECT_SESSIONS: maxProjectSessions.reason,
         AST_MAX_QUEUED_OPERATIONS_PER_PROJECT: maxQueuedOperationsPerProject.reason,
@@ -45,6 +55,7 @@ export function parseRuntimePolicy(environment) {
         AST_SHUTDOWN_DRAIN_TIMEOUT_MS: shutdownDrainTimeoutMs.reason,
         AST_COMPILER_WORKER_MODE: compilerWorkerModeReason,
         AST_COMPILER_WORKER_IDLE_TTL_MS: compilerWorkerIdleTtlMs.reason,
+        AST_MCP_APPLY_GUARD: applyGuardReason,
     });
     return Object.freeze({
         maxProjectSessions: maxProjectSessions.value,
@@ -54,6 +65,7 @@ export function parseRuntimePolicy(environment) {
         shutdownDrainTimeoutMs: shutdownDrainTimeoutMs.value,
         compilerWorkerMode,
         compilerWorkerIdleTtlMs: compilerWorkerIdleTtlMs.value,
+        denyApply,
         reasons,
     });
 }
@@ -95,6 +107,9 @@ export function createCompilerWorkerSpawnSpec(workerEntryPath, environment) {
         AST_QUEUE_WAIT_TIMEOUT_MS: String(policy.queueWaitTimeoutMs),
         AST_OPERATION_DEADLINE_MS: String(policy.operationDeadlineMs),
         AST_SHUTDOWN_DRAIN_TIMEOUT_MS: String(policy.shutdownDrainTimeoutMs),
+        // Forward the parent's resolved apply-guard policy so the supervised worker
+        // registers the same tool surface (deny-by-default fail-closed, allow opt-in).
+        AST_MCP_APPLY_GUARD: policy.denyApply ? "deny" : "allow",
     });
     return {
         ok: true,

package/dist/tools/apply_operation.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { applyOperation } from "../services/operations.js";
 import { createRequestContext } from "../services/request-context.js";
 import { createToolErrorContext, errorResult, structuredResult } from "./result.js";
+const TOOL_NAME = "ast_apply_operation";
 const AstApplyOperationInputSchema = z.object({
     operation_id: z.string().uuid().describe("Identifier returned by a prepare operation."),
     plan_hash: z.string().length(64).describe("Plan hash returned by the same prepare operation."),
@@ -15,7 +16,7 @@ const AstApplyOperationOutputSchema = z.object({
     idempotent_replay: z.boolean(),
 });
 export function registerApplyOperation(server) {
-    server.registerTool("ast_apply_operation", {
+    server.registerTool(TOOL_NAME, {
         title: "Apply a prepared structural operation",
         description: "Applies exactly the reviewed plan after verifying its plan hash and the complete TypeScript workspace fingerprint. Conflicts abort before writes; retries after success are idempotent.",
         inputSchema: AstApplyOperationInputSchema,
@@ -34,7 +35,9 @@ export function registerApplyOperation(server) {
             });
         }
         catch (error) {
-            return errorResult(error, createToolErrorContext("ast_apply_operation"));
+            return errorResult(error, createToolErrorContext(TOOL_NAME));
         }
     });
 }
+// prettier-ignore
+export const toolDescriptor = Object.freeze({ name: TOOL_NAME, register: registerApplyOperation, compatibility: "required", effect: "apply", batch: "none", directOutputFormats: Object.freeze(["json"]) });