@voybio/ace-swarm 2.4.2 → 2.4.4

package/dist/store/gate-contract-migration.js

@@ -0,0 +1,413 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const PACKAGE_GATE_CONTRACT_VERSION = 2;
+export const PACKAGE_GATE_CONTRACT_VERSION_KEY = "meta/package_gate_contract_version";
+const LEGACY_GATE_MIGRATIONS = [
+    {
+        fileName: "gate-autonomy.json",
+        legacyContent: JSON.stringify({
+            id: "gate-autonomy",
+            type: "artifact_scan",
+            invariant: "Every execution cycle records objective, strategy, evidence, and next state",
+            command: "",
+            evidence_requirement: "STATUS + EVIDENCE_LOG + HANDOFF pointers",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-autonomy.json",
+    },
+    {
+        fileName: "gate-completeness.json",
+        legacyContent: JSON.stringify({
+            id: "gate-completeness",
+            type: "artifact_scan",
+            invariant: "All required artifacts exist and are non-empty",
+            command: "",
+            evidence_requirement: "File presence and section completeness evidence",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-completeness.json",
+    },
+    {
+        fileName: "gate-operability.json",
+        legacyContent: JSON.stringify({
+            id: "gate-operability",
+            type: "artifact_scan",
+            invariant: "Runbooks, ownership, and incident routing are defined for release",
+            command: "",
+            evidence_requirement: "COMMUNICATION_CHANNELS.md + observability/release artifacts",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-operability.json",
+    },
+    {
+        fileName: "gate-security.json",
+        legacyContent: JSON.stringify({
+            id: "gate-security",
+            type: "manual_review",
+            invariant: "No unmitigated high-severity security or policy risks",
+            command: "",
+            evidence_requirement: "SECURITY_REPORT.md with explicit mitigations or accepted residual risk",
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/gates/gate-security.json",
+    },
+    {
+        fileName: "gate-correctness.json",
+        legacyContent: JSON.stringify({
+            id: "gate-correctness",
+            type: "executable",
+            invariant: "All required tests pass",
+            command: "if [ -f ace-mcp-server/package.json ]; then cd ace-mcp-server && npm test --silent; elif [ -f package.json ]; then npm test --silent; else echo 'package.json not found for gate-correctness' && exit 1; fi",
+            evidence_requirement: "Command output snippet with exit code 0",
+        }, null, 2),
+        remove: true,
+    },
+    {
+        fileName: "gate-evaluation.json",
+        legacyContent: JSON.stringify({
+            id: "gate-evaluation",
+            type: "executable",
+            invariant: "Core autonomy benchmark suites meet defined pass thresholds",
+            command: "bash scripts/ace/eval-harness.sh",
+            evidence_requirement: "EVAL_REPORT.md + command output",
+        }, null, 2),
+        remove: true,
+    },
+    {
+        fileName: "gate-typescript-public-surface.json",
+        legacyContent: JSON.stringify({
+            id: "gate-typescript-public-surface",
+            type: "executable",
+            invariant: "Exported MCP tools, resources, prompts, and public status events stay registered, described, schema-backed where required, and covered by the audit gate",
+            command: "node --input-type=module -e \"import('./dist/public-surface.js').then(async (m) => { const result = await m.auditPublicSurface({ write_artifact: false }); if (!result.ok) { console.error(result.failures.join('\\n')); process.exit(1); } console.log(JSON.stringify(result.summary)); })\"",
+            evidence_requirement: "PUBLIC_SURFACE_REPORT.md + passing public-surface audit",
+        }, null, 2),
+        remove: true,
+    },
+];
+const LEGACY_STATIC_ASSET_MIGRATIONS = [
+    {
+        key: "knowledge/agent-state/TEAL_CONFIG.md",
+        legacyContent: `# TEAL_CONFIG.md
+
+\`\`\`yaml
+teal_version: "1.1"
+timestamp: "2026-03-03T20:45:00Z"
+
+modules:
+  skeptic:
+    version: "1.0.0"
+    interface: "QUALITY_GATES.md"
+    sidecar: true
+
+  ops:
+    version: "1.0.0"
+    outputs: ["STATUS.md", "HANDOFF.json"]
+
+  astgrep:
+    version: "1.0.0"
+    inputs: ["TASK.md", "SCOPE.md", "AST_GREP_COMMANDS.md"]
+    outputs: ["AST_GREP_INDEX.md", "AST_GREP_INDEX.json"]
+
+  research:
+    version: "1.0.0"
+    inputs: ["TASK.md"]
+    outputs: ["EVIDENCE_LOG.md"]
+
+  spec:
+    version: "1.0.0"
+    depends_on: ["research", "skeptic"]
+    outputs: ["SPEC_CONTRACT.json", "INTERFACE_REGISTRY.md"]
+
+  build:
+    version: "1.0.0"
+    depends_on: ["spec"]
+    parallelizable: true
+
+  qa:
+    version: "1.0.0"
+    depends_on: ["build"]
+    gates: ["gate-completeness", "gate-correctness", "gate-autonomy"]
+
+  docs:
+    version: "1.0.0"
+    depends_on: ["build", "qa"]
+
+  memory:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["ops"]
+    outputs: ["MEMORY_INDEX.md"]
+
+  security:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["skeptic", "spec", "build"]
+    gates: ["gate-security"]
+
+  observability:
+    version: "1.0.0"
+    sidecar: true
+    depends_on: ["ops", "qa"]
+    outputs: ["OBSERVABILITY_REPORT.md"]
+
+  eval:
+    version: "1.0.0"
+    depends_on: ["qa"]
+    gates: ["gate-evaluation"]
+
+  release:
+    version: "1.0.0"
+    depends_on: ["security", "observability", "eval"]
+    gates: ["gate-operability"]
+
+pipelines:
+  standard:
+    - astgrep -> research -> spec -> build -> qa -> docs
+    - skeptic (sidecar)
+
+  high_certainty:
+    - astgrep -> spec -> build -> qa
+    - security (sidecar)
+    - eval -> release
+
+  high_ambiguity:
+    - astgrep -> research -> spec -> build
+    - skeptic (continuous)
+    - memory (continuous)
+    - ops (orchestration)
+
+  production_promotion:
+    - qa -> security -> eval -> observability -> release
+
+gates:
+  gate-completeness:
+    module: qa
+    inputs: ["SPEC_CONTRACT.json", "artifact_set"]
+
+  gate-correctness:
+    module: qa
+    inputs: ["test_results", "EVIDENCE_LOG.md"]
+
+  gate-autonomy:
+    module: skeptic
+    inputs: ["STATUS.md", "HANDOFF.json", "EVIDENCE_LOG.md"]
+
+  gate-security:
+    module: security
+    inputs: ["RISKS.md", "SECURITY_REPORT.md"]
+
+  gate-evaluation:
+    module: eval
+    inputs: ["EVAL_REPORT.md"]
+
+  gate-operability:
+    module: release
+    inputs: ["OBSERVABILITY_REPORT.md", "RELEASE_DECISION.md"]
+\`\`\`
+`,
+        currentAssetRelativePath: "agent-state/TEAL_CONFIG.md",
+    },
+    {
+        key: "knowledge/agent-state/MODULES/registry.json",
+        legacyContent: JSON.stringify({
+            roles: [
+                "capability-astgrep",
+                "capability-skeptic",
+                "capability-ops",
+                "capability-research",
+                "capability-spec",
+                "capability-build",
+                "capability-qa",
+                "capability-docs",
+                "capability-memory",
+                "capability-security",
+                "capability-observability",
+                "capability-eval",
+                "capability-release",
+                "capability-safety",
+                "capability-framework",
+                "capability-git",
+            ],
+            gates: [
+                "gate-completeness",
+                "gate-correctness",
+                "gate-autonomy",
+                "gate-security",
+                "gate-operability",
+                "gate-evaluation",
+                "gate-typescript-public-surface",
+            ],
+            schemas: [
+                "STATUS_EVENT.schema.json",
+                "HANDOFF.schema.json",
+                "ARTIFACT_MANIFEST.schema.json",
+                "ACE_RUNTIME_PROFILE.schema.json",
+                "WORKSPACE_SESSION_REGISTRY.schema.json",
+                "RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+                "RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+                "TRACKER_SNAPSHOT.schema.json",
+                "VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+                "VERICIFY_PROCESS_POST_LOG.schema.json",
+            ],
+        }, null, 2),
+        currentAssetRelativePath: "agent-state/MODULES/registry.json",
+    },
+    {
+        key: "knowledge/agent-state/QUALITY_GATES.md",
+        legacyContent: `# QUALITY GATES
+
+## gate-completeness
+
+- Invariant: required artifacts exist and are non-empty.
+- Pass condition: all required files are present with required sections.
+- Fail condition: any missing required artifact or empty required section.
+- Evidence: file list + section checks in \`EVIDENCE_LOG.md\`.
+
+## gate-correctness
+
+- Invariant: behavior satisfies spec acceptance criteria.
+- Pass condition: mapped tests pass and no unresolved critical failures.
+- Fail condition: failing mapped test, unresolved regression, or invalid provenance.
+- Evidence: test output and verification report pointers.
+`,
+        currentAssetRelativePath: "agent-state/QUALITY_GATES.md",
+    },
+    {
+        key: "knowledge/agent-state/INTERFACE_REGISTRY.md",
+        legacyContent: `# INTERFACE_REGISTRY
+
+## Runtime Executor Session Contract
+
+- \`runtime-executor-sessions.json\` is the authoritative session registry for unattended runtime executor workspaces.
+- It must validate against \`MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json\`.
+- Every session entry must expose \`session_id\`, \`workspace_path\`, \`root_path\`, \`status\`, \`source\`, timestamps, optional hook details, and any \`metadata\` required for routing/debugging.
+
+## Runtime Tool Spec Contract
+
+- \`runtime-tool-specs.json\` is the authoritative registry for external runtime tool declarations.
+- It must validate against \`MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json\`.
+- Each tool entry must include deterministic command metadata and explicitly declare environment inputs under \`env_keys\`.
+
+## Workspace Session Registry Contract
+
+- \`runtime-workspaces.json\` is the authoritative registry for active ACE workspace sessions.
+- It must validate against \`MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json\`.
+- Entries may optionally include hook health summaries and per-hook status under \`hooks\`.
+
+## Tracker Snapshot Contract
+
+- \`tracker-snapshot.json\` is the normalized cache of task/comment data mirrored from provider trackers.
+- It must validate against \`MODULES/schemas/TRACKER_SNAPSHOT.schema.json\`.
+- Scheduler and future executor consumers must use normalized item/comment fields only; provider-specific detail belongs under \`metadata\`.
+
+## Vericify Sidecar Contract
+
+- \`vericify/ace-bridge.json\` is an optional sidecar bridge snapshot for Vericify-style read-model consumers.
+- It must validate against \`MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json\`.
+- \`vericify/process-posts.json\` is an optional structured process-post log and must validate against \`MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json\`.
+- Vericify remains optional; ACE must not require the Vericify package to read or write these artifacts.
+
+## Public Surface Gate
+
+- \`audit_public_surface\` is the canonical TypeScript public-surface gate for MCP tools, resources, prompts, and registered event names.
+- \`PUBLIC_SURFACE_REPORT.md\` is the durable audit artifact written by that gate.
+- \`MODULES/gates/gate-typescript-public-surface.json\` is the executable gate manifest for CI or operator use.
+
+## Provenance Contract
+
+- \`ARTIFACT_MANIFEST.json\` is mandatory and must be schema-valid.
+- Each artifact entry must include \`artifact_id\`, \`artifact_path\`, \`producer_module\`, \`spec_version\`, \`req_ids\`, \`checksum\`, \`confidence_level\`, \`evidence_ref\`, and \`timestamp\`.
+- \`PROVENANCE_LOG.md\` must mirror manifest entries with append-only evidence-linked records.
+
+## Versioning Rules
+
+- additive changes: \`minor\`
+- breaking changes: \`major\`
+- bugfix/clarification: \`patch\`
+
+## Compatibility Requirement
+
+Producer and consumer compatibility must be documented before release.
+`,
+        currentAssetRelativePath: "agent-state/INTERFACE_REGISTRY.md",
+    },
+];
+function normalizeForExactMatch(content) {
+    return content.replace(/\r\n/g, "\n").trimEnd();
+}
+function matchesLegacyPackageContent(content, legacyContent) {
+    return normalizeForExactMatch(content) === normalizeForExactMatch(legacyContent);
+}
+function matchesCurrentPackageContent(content, currentContent) {
+    return normalizeForExactMatch(content) === normalizeForExactMatch(currentContent);
+}
+function readAsset(assetsRoot, relativePath) {
+    return readFileSync(join(assetsRoot, relativePath), "utf-8");
+}
+export async function recordPackageGateContractVersion(store) {
+    await store.setJSON(PACKAGE_GATE_CONTRACT_VERSION_KEY, PACKAGE_GATE_CONTRACT_VERSION);
+}
+export async function migratePackageGateContract(store, workspaceRoot, assetsRoot) {
+    const messages = [];
+    let changed = false;
+    for (const entry of LEGACY_GATE_MIGRATIONS) {
+        const key = `knowledge/gates/${entry.fileName}`;
+        const currentContent = entry.currentAssetRelativePath
+            ? readAsset(assetsRoot, entry.currentAssetRelativePath)
+            : undefined;
+        const existing = await store.getBlob(key);
+        if (typeof existing === "string") {
+            if (matchesLegacyPackageContent(existing, entry.legacyContent)) {
+                if (entry.remove) {
+                    await store.delete(key);
+                    messages.push(`Removed legacy package gate ${key}.`);
+                }
+                else if (currentContent) {
+                    await store.setBlob(key, currentContent);
+                    messages.push(`Updated legacy package gate ${key}.`);
+                }
+                changed = true;
+            }
+            else if (!currentContent || !matchesCurrentPackageContent(existing, currentContent)) {
+                messages.push(`Skipped customized gate ${key}; content differs from known package seed.`);
+            }
+        }
+        const projectionPath = join(workspaceRoot, "agent-state", "MODULES", "gates", entry.fileName);
+        if (existsSync(projectionPath)) {
+            const projectionContent = readFileSync(projectionPath, "utf-8");
+            if (matchesLegacyPackageContent(projectionContent, entry.legacyContent)) {
+                if (entry.remove) {
+                    rmSync(projectionPath, { force: true });
+                    messages.push(`Removed legacy gate projection ${projectionPath}.`);
+                }
+                else if (currentContent) {
+                    mkdirSync(join(workspaceRoot, "agent-state", "MODULES", "gates"), { recursive: true });
+                    writeFileSync(projectionPath, currentContent, "utf-8");
+                    messages.push(`Updated legacy gate projection ${projectionPath}.`);
+                }
+                changed = true;
+            }
+            else if (!currentContent || !matchesCurrentPackageContent(projectionContent, currentContent)) {
+                messages.push(`Skipped customized gate projection ${projectionPath}; content differs from known package seed.`);
+            }
+        }
+    }
+    for (const entry of LEGACY_STATIC_ASSET_MIGRATIONS) {
+        const currentContent = readAsset(assetsRoot, entry.currentAssetRelativePath);
+        const existing = await store.getBlob(entry.key);
+        if (typeof existing !== "string")
+            continue;
+        if (matchesLegacyPackageContent(existing, entry.legacyContent)) {
+            await store.setBlob(entry.key, currentContent);
+            messages.push(`Updated legacy package asset ${entry.key}.`);
+            changed = true;
+        }
+        else if (!matchesCurrentPackageContent(existing, currentContent)) {
+            messages.push(`Skipped customized asset ${entry.key}; content differs from known package seed.`);
+        }
+    }
+    const recordedVersion = await store.getJSON(PACKAGE_GATE_CONTRACT_VERSION_KEY);
+    if (recordedVersion !== PACKAGE_GATE_CONTRACT_VERSION) {
+        await recordPackageGateContractVersion(store);
+        changed = true;
+    }
+    return { changed, messages };
+}
+//# sourceMappingURL=gate-contract-migration.js.map

package/dist/store/materializers/host-file-materializer.js

@@ -199,7 +199,7 @@ export class HostFileMaterializer {
             codex: "codex.config.toml",
             vscode: "vscode.mcp.json",
             copilot: ".mcp.json",
-            claude: "claude_desktop_config.json",
+            claude: "claude_code.mcp.json",
             cursor: "cursor.mcp.json",
             antigravity: "antigravity.mcp.json",
         };
@@ -258,6 +258,14 @@ export class HostFileMaterializer {
     async materializeMcpBundle() {
         await this.seedStorePayload();
         const paths = [];
+        // Project-root .mcp.json is the only location Claude Code CLI and GitHub
+        // Copilot CLI read for project-scoped MCP servers. Without this, the
+        // .mcp-config/ bundle alone is invisible to both — the server never loads.
+        paths.push(await this.materializeEntry({
+            absPath: this.root(".mcp.json"),
+            keyParts: [".mcp.json"],
+            fallbackContent: getMcpServerConfigSnippet("copilot"),
+        }));
         for (const entry of [...this.buildMcpBundleEntries(), ...this.buildOptionalHookBundleEntries()]) {
             paths.push(await this.materializeEntry(entry));
         }

package/dist/tools-files.js

@@ -3,7 +3,7 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { z } from "zod";
 import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, resolveWorkspaceWritePath, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
@@ -14,7 +14,7 @@ import { shouldAutoRefreshKanbanForPath, refreshKanbanArtifacts, } from "./kanba
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
 import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
-import { detectAstgrepCommand, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
+import { detectAstgrepCommand, flattenMetaVariables, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
 import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
 function reasonCodeFromError(error) {
@@ -206,8 +206,12 @@ async function compileStructuralEditPlan(input) {
         },
         validation_command: input.validationCommand,
         test_command: input.testCommand,
+        allow_multi_match: input.allowMultiMatch,
     });
 }
+function renderStructuralRewrite(template, captures) {
+    return template.replace(/\$([A-Z][A-Z0-9_]*)/g, (full, name) => captures[name] ?? full);
+}
 function previewDiffText(diffText) {
     const lines = diffText.trimEnd().split("\n");
     const limited = lines.slice(0, 80).join("\n");
@@ -378,6 +382,24 @@ async function buildStructuralPreview(plan) {
             }),
         };
     }
+    if (targetMatches.length > 1 && !plan.allow_multi_match) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "ambiguous_multi_match_in_file",
+                error: `Plan ${plan.plan_id} resolves to ${targetMatches.length} matches in ${plan.target.file}. Pass allow_multi_match=true at compile time to opt in, or narrow the pattern.`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: targetMatches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
     const astgrepCmd = detectAstgrepCommand();
     if (!astgrepCmd) {
         return {
@@ -403,7 +425,7 @@ async function buildStructuralPreview(plan) {
     mkdirSync(dirname(stagedOriginal), { recursive: true });
     writeFileSync(stagedOriginal, currentContent, "utf-8");
     writeFileSync(stagedRewrite, currentContent, "utf-8");
-    const rewriteResult = spawnSync(astgrepCmd, ["--pattern", plan.locator.pattern, "--rewrite", plan.rewrite.rewrite_template, "--lang", plan.locator.lang, stagedRewrite, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+    const rewriteResult = spawnSync(astgrepCmd, ["--pattern", plan.locator.pattern, "--rewrite", plan.rewrite.rewrite_template, "--lang", plan.locator.lang, "--json", stagedRewrite], { encoding: "utf8", cwd: WORKSPACE_ROOT });
     if (rewriteResult.status !== 0) {
         return {
             artifact: await finalize({
@@ -423,7 +445,46 @@ async function buildStructuralPreview(plan) {
             }),
         };
     }
-    const rewrittenContent = readFileSync(stagedRewrite, "utf-8");
+    let rawMatches = [];
+    try {
+        rawMatches = JSON.parse(rewriteResult.stdout || "[]");
+    }
+    catch {
+        rawMatches = [];
+    }
+    const selectedBytes = plan.target.selected_range?.byteOffset;
+    const targeted = rawMatches.find((match) => selectedBytes
+        && match.range?.byteOffset?.start === selectedBytes.start
+        && match.range?.byteOffset?.end === selectedBytes.end);
+    const replacement = targeted && (typeof targeted.replacement === "string"
+        ? targeted.replacement
+        : renderStructuralRewrite(plan.rewrite.rewrite_template, flattenMetaVariables(targeted.metaVariables)));
+    if (!selectedBytes || !targeted || typeof replacement !== "string") {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "target_byte_range_drift",
+                error: `No match at selected byte range [${selectedBytes?.start},${selectedBytes?.end}] for plan ${plan.plan_id}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: rawMatches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+                staging_path: stagingDir,
+            }),
+        };
+    }
+    const originalBuffer = Buffer.from(currentContent, "utf8");
+    const rewrittenContent = Buffer.concat([
+        originalBuffer.subarray(0, selectedBytes.start ?? 0),
+        Buffer.from(replacement, "utf8"),
+        originalBuffer.subarray(selectedBytes.end ?? 0),
+    ]).toString("utf8");
+    writeFileSync(stagedRewrite, rewrittenContent, "utf8");
     const rewriteHash = contentSha256(rewrittenContent);
     const diff = diffContents(currentContent, rewrittenContent);
     const diffProcess = spawnSync("diff", ["-u", "--label", `a/${plan.target.file}`, "--label", `b/${plan.target.file}`, stagedOriginal, stagedRewrite], { encoding: "utf8", cwd: WORKSPACE_ROOT });
@@ -1344,9 +1405,10 @@ export function registerFileTools(server) {
         max_results: z.number().int().min(1).max(200).optional().describe("Max locator matches to keep (default: 50)"),
         desired_change: z.string().describe("Plain-language edit intent; used as rewrite_template when no explicit template is provided"),
         rewrite_template: z.string().optional().describe("Explicit ast-grep rewrite template; preferred when provided"),
+        allow_multi_match: z.boolean().optional().describe("Opt into selecting and rewriting only the chosen match when multiple matches exist in the target file"),
         validation_command: z.string().optional().describe("Shell command to validate before promotion"),
         test_command: z.string().optional().describe("Shell command to run before promotion"),
-    }, async ({ match_id, pattern, lang, scope, symbol_hint, max_results, desired_change, rewrite_template, validation_command, test_command, }) => {
+    }, async ({ match_id, pattern, lang, scope, symbol_hint, max_results, desired_change, rewrite_template, allow_multi_match, validation_command, test_command, }) => {
         if (!match_id && (!pattern || !lang)) {
             return jsonResponse({
                 ok: false,
@@ -1455,6 +1517,7 @@ export function registerFileTools(server) {
             selectedMatch,
             desiredChange: desired_change,
             rewriteTemplate: rewrite_template,
+            allowMultiMatch: allow_multi_match,
             validationCommand: validation_command,
             testCommand: test_command,
         }).catch((error) => {