vigiles 5.0.0 → 5.1.0

package/dist/core/description-overlap.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERLAP_NCD_CUTOFF = void 0;
+exports.findDescriptionOverlaps = findDescriptionOverlaps;
+/**
+ * Description-overlap — a DETERMINISTIC proxy for a behavioral risk. Two skills
+ * whose descriptions are near-identical can't be told apart by the model's
+ * selector, so the wrong one fires (a precision collision). This catches a
+ * `--trigger`-class problem with NO model, reusing the NCD engine in proofs.ts
+ * (the same one `findSimilarRules` uses) — the bridge between the deterministic
+ * and behavioral columns, and a check no other plugin linter has.
+ *
+ * Calibrated HIGH-PRECISION against the mid-2026 sweep: across 4678 within-plugin
+ * skill-description pairs, the MOST-similar legitimately-distinct pair
+ * (`create-issue` vs `create-pr`) sits at NCD 0.25, and NOTHING falls below it.
+ * So a cutoff of NCD < 0.2 fires only on text that's essentially identical (a
+ * copy-pasted description with a word or two changed) — never on a parallel but
+ * distinct pair. Warn-level, reports the PAIR (not a unilateral defect).
+ */
+const proofs_js_1 = require("./proofs.js");
+/**
+ * The NCD cutoff below which two descriptions count as a near-duplicate. 0.2 sits
+ * safely under the sweep's most-similar legitimately-distinct pair (0.25), so
+ * only basically-identical text is flagged. Exported so a caller / test can see
+ * the calibrated value.
+ */
+exports.OVERLAP_NCD_CUTOFF = 0.2;
+/**
+ * Find near-duplicate description pairs among `surfaces`. Returns one
+ * {@link DescriptionOverlap} per pair whose NCD is below `cutoff`, most-similar
+ * first. Pure; pass only the surfaces that actually compete for auto-selection
+ * (model-invocable, described) so a user-invoked pair isn't a false alarm.
+ */
+function findDescriptionOverlaps(surfaces, cutoff = exports.OVERLAP_NCD_CUTOFF) {
+    const overlaps = [];
+    for (let i = 0; i < surfaces.length; i++) {
+        for (let j = i + 1; j < surfaces.length; j++) {
+            const d = (0, proofs_js_1.ncd)(surfaces[i].description, surfaces[j].description);
+            if (d >= cutoff)
+                continue;
+            const a = surfaces[i].name;
+            const b = surfaces[j].name;
+            overlaps.push({
+                a,
+                b,
+                similarity: Math.round((1 - d) * 100) / 100,
+                message: `skills "${a}" and "${b}" have near-identical descriptions (${String(Math.round((1 - d) * 100))}% alike) — the model can't reliably tell them apart, so the wrong one may fire. Differentiate their descriptions.`,
+            });
+        }
+    }
+    return overlaps.sort((x, y) => y.similarity - x.similarity);
+}
+//# sourceMappingURL=description-overlap.js.map

package/dist/core/dialect.d.ts

@@ -32,6 +32,14 @@ export interface HarnessDialect {
     readonly neverAvailableTools: readonly string[];
     /** Matches an MCP tool reference, e.g. `mcp__server__tool`. */
     readonly mcpToolPattern: RegExp;
+    /**
+     * MCP servers the harness provides itself, available to a contract WITHOUT the
+     * plugin declaring them — e.g. Claude Code's built-in `ide` integration
+     * (`mcp__ide__getDiagnostics`). The `mcp-tool-resolves` check allowlists these
+     * so a reference to a built-in server is never flagged as an undeclared one.
+     * Optional (additive, non-breaking for existing adapters) — defaults to none.
+     */
+    readonly knownMcpServers?: readonly string[];
     /** Hook event names the harness fires. */
     readonly hookEvents: readonly string[];
     /** Instruction-file targets the harness reads (also the h1 heading). */

package/dist/core/frontmatter-read.d.ts

@@ -0,0 +1,25 @@
+export interface FrontmatterRead {
+    /** Parsed mapping when the block is valid YAML, else null (malformed or scalar). */
+    readonly data: Record<string, unknown> | null;
+    /** Raw text inside the leading `---` fences, or null when there's no block. */
+    readonly block: string | null;
+    /** True when a leading `---` block EXISTS but is NOT valid YAML. */
+    readonly malformed: boolean;
+}
+/** Extract + parse the leading frontmatter block, never throwing. */
+export declare function readFrontmatter(markdown: string): FrontmatterRead;
+/**
+ * A top-level scalar field — from parsed YAML when valid, else a regex salvage
+ * from the raw block (handling a block scalar `>`/`|` and a quoted value that
+ * starts on the next indented line).
+ */
+export declare function frontmatterScalar(fm: FrontmatterRead, key: string): string | undefined;
+/**
+ * A tool-list field (`tools:` / `disallowedTools:`) — an array or a comma list,
+ * normalized to string[]. Returns `null` when the key is ABSENT (the "no
+ * contract / inherits all" signal the rail honors) and `[]` when the key is
+ * PRESENT but empty ("no tools"). Salvages from the raw block when YAML is
+ * malformed, so the rail still reads the contract.
+ */
+export declare function frontmatterList(fm: FrontmatterRead, key: string): string[] | null;
+//# sourceMappingURL=frontmatter-read.d.ts.map

package/dist/core/frontmatter-read.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFrontmatter = readFrontmatter;
+exports.frontmatterScalar = frontmatterScalar;
+exports.frontmatterList = frontmatterList;
+/**
+ * Lenient frontmatter reader — ONE reader for the SKILL.md / subagent `---` block,
+ * shared by `scan` and the PreToolUse rail (`agent-runtime`). It is deliberately
+ * fault-tolerant: it audits arbitrary third-party files, so it must never throw
+ * and must salvage the few scalar/list fields it needs even from a block that
+ * isn't valid YAML.
+ *
+ * The strategy is "real parser, with a safety net": try `js-yaml` (so block
+ * scalars, quoted/multi-line values, and flow arrays parse correctly for free);
+ * if the block isn't valid YAML, fall back to a regex salvage of the requested
+ * field and record `malformed: true` (the signal the `frontmatter-valid` rule
+ * reports). A single bad line therefore never blanks out a whole file's metadata.
+ *
+ * This replaces three divergent hand-parsers (the old `readField` in scan.ts and
+ * the regex parse in agent-runtime.ts); `core/frontmatter.ts` is a DIFFERENT
+ * concern (the Level-1 `vigiles:` rule block) and is untouched.
+ */
+const js_yaml_1 = require("js-yaml");
+// Frontmatter is the very first thing in the file. Anchoring at the start — not
+// `(?:^|\n)` — means a `---` horizontal rule in the BODY is never mistaken for
+// frontmatter (which matters for the malformed-YAML verdict). A leading BOM is
+// stripped first; an optional leading HTML comment is allowed too — vigiles
+// stamps a compiled file with `<!-- vigiles:sha256:… -->` before the `---`.
+const BLOCK_RE = /^\uFEFF?(?:<!--[\s\S]*?-->\s*)?---\r?\n([\s\S]*?)\r?\n---/;
+/** A YAML block-scalar indicator: `>`/`|` with optional chomp (`+`/`-`) + indent digit. */
+const BLOCK_SCALAR_RE = /^[|>][+-]?\d*$/;
+/** Extract + parse the leading frontmatter block, never throwing. */
+function readFrontmatter(markdown) {
+    const m = BLOCK_RE.exec(markdown);
+    if (!m)
+        return { data: null, block: null, malformed: false };
+    const block = m[1];
+    try {
+        const parsed = (0, js_yaml_1.load)(block);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed)) {
+            return {
+                data: parsed,
+                block,
+                malformed: false,
+            };
+        }
+        // Valid YAML but not a mapping (e.g. a bare scalar) — usable as no data, but
+        // not "malformed": it parsed fine. Salvage will read fields from the block.
+        return { data: null, block, malformed: false };
+    }
+    catch (e) {
+        if (e instanceof js_yaml_1.YAMLException)
+            return { data: null, block, malformed: true };
+        throw e;
+    }
+}
+/**
+ * A top-level scalar field — from parsed YAML when valid, else a regex salvage
+ * from the raw block (handling a block scalar `>`/`|` and a quoted value that
+ * starts on the next indented line).
+ */
+function frontmatterScalar(fm, key) {
+    if (fm.data && Object.prototype.hasOwnProperty.call(fm.data, key)) {
+        const v = fm.data[key];
+        if (typeof v === "string")
+            return v.trim() || undefined;
+        if (typeof v === "number" || typeof v === "boolean")
+            return String(v);
+        return undefined; // an array/object/null isn't a scalar field
+    }
+    return fm.block === null ? undefined : salvageField(fm.block, key);
+}
+/**
+ * A tool-list field (`tools:` / `disallowedTools:`) — an array or a comma list,
+ * normalized to string[]. Returns `null` when the key is ABSENT (the "no
+ * contract / inherits all" signal the rail honors) and `[]` when the key is
+ * PRESENT but empty ("no tools"). Salvages from the raw block when YAML is
+ * malformed, so the rail still reads the contract.
+ */
+function frontmatterList(fm, key) {
+    if (fm.data && Object.prototype.hasOwnProperty.call(fm.data, key)) {
+        const v = fm.data[key];
+        if (v === null)
+            return []; // `key:` with nothing after it → empty contract
+        if (Array.isArray(v))
+            return v.map((x) => String(x).trim()).filter((s) => s.length > 0);
+        if (typeof v === "string")
+            return splitList(v);
+        return [];
+    }
+    return fm.block === null ? null : salvageList(fm.block, key);
+}
+// --- salvage (the malformed-YAML / no-data fallback) ------------------------
+/** Old `readField`: gather a possibly multi-line scalar value from the raw block. */
+function salvageField(block, key) {
+    const lines = block.split(/\r?\n/);
+    const idx = lines.findIndex((l) => new RegExp(`^${key}:`).test(l));
+    if (idx === -1)
+        return undefined;
+    const keyIndent = /^(\s*)/.exec(lines[idx])?.[1].length ?? 0;
+    const inline = (new RegExp(`^${key}:[ \\t]*(.*)$`).exec(lines[idx])?.[1] ?? "").trim();
+    if (inline && !BLOCK_SCALAR_RE.test(inline)) {
+        return inline.replace(/^["']|["']$/g, "").trim() || undefined;
+    }
+    const collected = [];
+    for (let i = idx + 1; i < lines.length; i++) {
+        if (lines[i].trim() === "")
+            continue;
+        const indent = /^(\s*)/.exec(lines[i])?.[1].length ?? 0;
+        if (indent <= keyIndent)
+            break;
+        collected.push(lines[i].trim());
+    }
+    return (collected
+        .join(" ")
+        .trim()
+        .replace(/^["']/, "")
+        .replace(/["']$/, "")
+        .trim() || undefined);
+}
+/** Salvage a list field from the raw block (single-line key only). */
+function salvageList(block, key) {
+    const match = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(block);
+    if (!match)
+        return null;
+    return splitList(match[1]);
+}
+/** Split a comma list or inline-array string into trimmed, de-quoted tokens. */
+function splitList(raw) {
+    return raw
+        .replace(/^\[|\]$/g, "")
+        .split(",")
+        .map((t) => t.trim().replace(/^["']|["']$/g, ""))
+        .filter((t) => t.length > 0);
+}
+//# sourceMappingURL=frontmatter-read.js.map

package/dist/core/hook-events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Hook-event verification — the cross-referencing moat applied to the EVENT a
+ * hook registers under. A `hooks` block keys each entry by event name
+ * (`PreToolUse`, `SessionStart`, …); a TYPO (`PreToolUSe`) means the hook
+ * silently never fires — a dead registration no generic JSON linter catches.
+ *
+ * Like the tool catalog, the event set is NOT closed in practice: frameworks
+ * extend it (TheBushidoCollective/han ships a custom runtime with `TeammateIdle`,
+ * `WorktreeRemove`, … in its own `hooks.json`). So the audit path (scan/lint) is
+ * HIGH-PRECISION — `confidentHookEventIssues` keeps only a close typo
+ * (a did-you-mean within edit distance 2), never a bare unrecognized event that
+ * may be a custom/future one. ONE detector (one-detector-no-drift): scan + the
+ * `hook-events` lint rule call the same code. Dialect injected (core ⊄ adapter).
+ */
+import type { HarnessDialect } from "./dialect.js";
+export interface HookEventIssue {
+    readonly event: string;
+    /** Closest known event (did-you-mean), or null. */
+    readonly suggestion: string | null;
+    readonly message: string;
+}
+/**
+ * The HIGH-CONFIDENCE subset (what scan / lint act on): only an unrecognized
+ * event that's a close typo of a real one. A bare unknown (no near match) is
+ * likely a framework/custom event, not a defect — never flagged when auditing.
+ */
+export declare function confidentHookEventIssues(issues: readonly HookEventIssue[]): HookEventIssue[];
+/**
+ * Verify hook-event names against the dialect catalog. Returns one issue per
+ * unrecognized event. Like the tool-contract check, a suggestion (edit distance
+ * ≤ 2) is the confidence signal that an unknown is really a typo of a real event.
+ */
+export declare function verifyHookEvents(events: readonly string[], dialect: HarnessDialect): HookEventIssue[];
+//# sourceMappingURL=hook-events.d.ts.map

package/dist/core/hook-events.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confidentHookEventIssues = confidentHookEventIssues;
+exports.verifyHookEvents = verifyHookEvents;
+const linters_js_1 = require("./linters.js");
+/** Closest known hook event by edit distance (≤ 2) — a confidence signal. */
+function closestEvent(event, dialect) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const known of dialect.hookEvents) {
+        const d = (0, linters_js_1.editDistance)(event.toLowerCase(), known.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = known;
+        }
+    }
+    return bestDistance <= 2 ? best : null;
+}
+/**
+ * The HIGH-CONFIDENCE subset (what scan / lint act on): only an unrecognized
+ * event that's a close typo of a real one. A bare unknown (no near match) is
+ * likely a framework/custom event, not a defect — never flagged when auditing.
+ */
+function confidentHookEventIssues(issues) {
+    return issues.filter((i) => i.suggestion !== null);
+}
+/**
+ * Verify hook-event names against the dialect catalog. Returns one issue per
+ * unrecognized event. Like the tool-contract check, a suggestion (edit distance
+ * ≤ 2) is the confidence signal that an unknown is really a typo of a real event.
+ */
+function verifyHookEvents(events, dialect) {
+    const known = new Set(dialect.hookEvents);
+    const issues = [];
+    for (const event of events) {
+        if (known.has(event))
+            continue;
+        const near = closestEvent(event, dialect);
+        const hint = near ? ` Did you mean "${near}"?` : "";
+        issues.push({
+            event,
+            suggestion: near,
+            message: `Unknown hook event "${event}" — a hook here never fires. Valid events: ${dialect.hookEvents.join(", ")}.${hint}`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=hook-events.js.map

package/dist/core/mcp-config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP-config verification — a declared MCP server that can't start. Each server
+ * entry must say HOW to reach it: a `command` (stdio server) OR a `url` (http/sse
+ * server). An entry with neither is malformed — the server silently never comes
+ * up, and the tools it was meant to provide are missing. A JSON linter sees valid
+ * JSON; only an MCP-shape-aware check knows the entry is unreachable.
+ *
+ * Pure + FP-safe: the command-or-url requirement is unambiguous (not a catalog we
+ * might have wrong). ONE detector reused by scan + the `mcp-config` lint rule.
+ */
+export interface McpIssue {
+    readonly server: string;
+    readonly message: string;
+}
+/**
+ * Validate a `mcpServers` map. Returns one issue per entry that declares neither
+ * a `command` (stdio) nor a `url` (http/sse) — the two ways to reach a server.
+ */
+export declare function verifyMcpServers(servers: Record<string, unknown>): McpIssue[];
+//# sourceMappingURL=mcp-config.d.ts.map

package/dist/core/mcp-config.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * MCP-config verification — a declared MCP server that can't start. Each server
+ * entry must say HOW to reach it: a `command` (stdio server) OR a `url` (http/sse
+ * server). An entry with neither is malformed — the server silently never comes
+ * up, and the tools it was meant to provide are missing. A JSON linter sees valid
+ * JSON; only an MCP-shape-aware check knows the entry is unreachable.
+ *
+ * Pure + FP-safe: the command-or-url requirement is unambiguous (not a catalog we
+ * might have wrong). ONE detector reused by scan + the `mcp-config` lint rule.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMcpServers = verifyMcpServers;
+/**
+ * Validate a `mcpServers` map. Returns one issue per entry that declares neither
+ * a `command` (stdio) nor a `url` (http/sse) — the two ways to reach a server.
+ */
+function verifyMcpServers(servers) {
+    const issues = [];
+    for (const [server, raw] of Object.entries(servers)) {
+        if (typeof raw !== "object" || raw === null) {
+            issues.push({
+                server,
+                message: `MCP server "${server}" is not a config object.`,
+            });
+            continue;
+        }
+        const cfg = raw;
+        const hasCommand = typeof cfg.command === "string" && cfg.command.length > 0;
+        const hasUrl = typeof cfg.url === "string" && cfg.url.length > 0;
+        if (!hasCommand && !hasUrl) {
+            issues.push({
+                server,
+                message: `MCP server "${server}" declares neither a "command" (stdio) nor a "url" (http/sse) — it can't start.`,
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=mcp-config.js.map

package/dist/core/mcp-hook.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP-hook target verification — the cross-referencing moat applied to a
+ * `type: "mcp_tool"` HOOK action. Claude Code hooks support five action types
+ * (command / http / mcp_tool / prompt / agent); an `mcp_tool` action calls a tool
+ * on an already-connected MCP server and REQUIRES a `server` + `tool` field. Two
+ * ways it silently never fires:
+ *
+ *   1. it omits `server` or `tool` — malformed, can't dispatch (unambiguous, like
+ *      mcp-config; always flagged);
+ *   2. its `server` isn't one the plugin declares — can't resolve (gated on the
+ *      plugin shipping a declared `mcpServers` set, exactly like mcp-tool-resolves;
+ *      built-in servers such as `ide` are allowlisted).
+ *
+ * Pure + high-precision. ONE detector reused by scan + the
+ * `mcp-hook-target-resolves` lint rule. The dialect is injected (core ⊄ adapter).
+ *
+ * Scope note: the matcher surface (a `mcp__server__.*` matcher naming an
+ * undeclared server) is a DIFFERENT, regex-shaped check left to a future
+ * `hook-matcher` rule — this one is the literal `mcp_tool` action target only.
+ */
+import type { HarnessDialect } from "./dialect.js";
+export type McpHookIssueKind = "incomplete" | "undeclared-server";
+export interface McpHookIssue {
+    readonly server: string | null;
+    readonly kind: McpHookIssueKind;
+    readonly message: string;
+}
+/**
+ * Verify every `type: "mcp_tool"` hook action against the plugin's declared MCP
+ * servers. Returns an {@link McpHookIssue} for each incomplete action (no
+ * `server`/`tool`) and — when the plugin declares a server set — each action
+ * whose `server` is neither declared nor a known built-in.
+ */
+export declare function verifyMcpHookTargets(hooks: unknown, declaredServers: readonly string[], dialect: HarnessDialect): McpHookIssue[];
+//# sourceMappingURL=mcp-hook.d.ts.map

package/dist/core/mcp-hook.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyMcpHookTargets = verifyMcpHookTargets;
+/**
+ * Collect the action objects from a hooks config. The canonical Claude Code shape
+ * is `{ <event>: [ { matcher?, hooks: [ <action>, … ] }, … ] }`; we also tolerate
+ * an entry that IS an action (a `type` field directly). Non-object input → none.
+ */
+function collectHookActions(hooks) {
+    const actions = [];
+    if (hooks === null || typeof hooks !== "object")
+        return actions;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (group === null || typeof group !== "object")
+                continue;
+            const g = group;
+            if (Array.isArray(g.hooks)) {
+                for (const a of g.hooks)
+                    if (a !== null && typeof a === "object")
+                        actions.push(a);
+            }
+            else if (typeof g.type === "string") {
+                actions.push(g);
+            }
+        }
+    }
+    return actions;
+}
+/**
+ * Verify every `type: "mcp_tool"` hook action against the plugin's declared MCP
+ * servers. Returns an {@link McpHookIssue} for each incomplete action (no
+ * `server`/`tool`) and — when the plugin declares a server set — each action
+ * whose `server` is neither declared nor a known built-in.
+ */
+function verifyMcpHookTargets(hooks, declaredServers, dialect) {
+    const known = new Set([
+        ...declaredServers,
+        ...(dialect.knownMcpServers ?? []),
+    ]);
+    const issues = [];
+    for (const action of collectHookActions(hooks)) {
+        if (action.type !== "mcp_tool")
+            continue;
+        const server = typeof action.server === "string" ? action.server : "";
+        const tool = typeof action.tool === "string" ? action.tool : "";
+        if (server === "" || tool === "") {
+            issues.push({
+                server: server || null,
+                kind: "incomplete",
+                message: `mcp_tool hook is missing a ${server === "" ? "server" : "tool"} field — it can't dispatch.`,
+            });
+            continue;
+        }
+        // Gate: with no declared set the server may be user-global/project (unknowable).
+        if (declaredServers.length === 0)
+            continue;
+        if (known.has(server))
+            continue;
+        issues.push({
+            server,
+            kind: "undeclared-server",
+            message: `mcp_tool hook targets server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the hook can't resolve.`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=mcp-hook.js.map

package/dist/core/mcp-tool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MCP-tool resolution — the cross-referencing moat ("valid is not true") applied
+ * to an MCP tool reference's SERVER. A contract that lists `mcp__linear__search`
+ * names a server `linear`; if the plugin declares its own MCP servers (a
+ * `.mcp.json` / manifest `mcpServers` block) and `linear` isn't among them, the
+ * tool can't resolve — a dead contract entry. This completes the tool moat:
+ * `agent-tool-contract` (tool-contract.ts) verifies BUILT-IN tools but passes
+ * ANY `mcp__*` token unchecked; this verifies the MCP half.
+ *
+ * Calibrated HIGH-PRECISION — three guards, each learned from a real plugin in
+ * the mid-2026 sweep (research/plugin-structural-findings.md):
+ *
+ * 1. GATE on a declared set. Only flag when the plugin SHIPS a `mcpServers`
+ *    declaration (a non-empty `declaredServers`). A plugin that declares no
+ *    servers reaches user-global / project-level ones (the normal pattern —
+ *    ananddtyagi's agents reference `mcp__ide__*` with no `.mcp.json`), so
+ *    flagging there would cry wolf. No declared set → return nothing.
+ * 2. ALLOWLIST built-ins. A harness-provided server (`dialect.knownMcpServers`,
+ *    e.g. Claude Code's `ide`) is available without a declaration — never flag it.
+ * 3. SKIP the plugin-namespaced form. Claude Code rewrites a plugin's own MCP
+ *    tool to `mcp__plugin_<plugin>_<server>__<tool>` (observed on han's
+ *    playwright-mcp: `mcp__plugin_playwright-mcp_playwright__…`). The plugin /
+ *    server segments are joined with single underscores and are ambiguous to
+ *    split, and the ref is by construction the plugin's OWN server — so we don't
+ *    interpret it (parsing it would be a false-positive factory).
+ *
+ * Pure + ONE detector reused by `scan` + the `mcp-tool-resolves` lint rule
+ * (one-detector-no-drift). The dialect is injected (core ⊄ adapter).
+ */
+import type { HarnessDialect } from "./dialect.js";
+export interface McpToolIssue {
+    readonly tool: string;
+    readonly server: string;
+    readonly message: string;
+}
+/**
+ * The server segment of a direct `mcp__<server>__<tool>` reference, or null when
+ * the token isn't a direct MCP tool we resolve: a non-MCP tool, or the
+ * plugin-namespaced `mcp__plugin_…__…` form (guard 3 — deliberately skipped).
+ * A `Tool(restriction)` suffix is stripped first.
+ */
+export declare function mcpToolServer(raw: string, dialect: HarnessDialect): string | null;
+/**
+ * Verify the MCP tool references in a contract against the plugin's declared MCP
+ * servers. Returns one {@link McpToolIssue} per direct `mcp__<server>__<tool>`
+ * whose server is neither declared nor a known built-in. Returns `[]` when no
+ * servers are declared (guard 1 — we can't know the resolvable set).
+ */
+export declare function verifyMcpToolServers(tools: readonly string[], declaredServers: readonly string[], dialect: HarnessDialect): McpToolIssue[];
+//# sourceMappingURL=mcp-tool.d.ts.map

package/dist/core/mcp-tool.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpToolServer = mcpToolServer;
+exports.verifyMcpToolServers = verifyMcpToolServers;
+/**
+ * The server segment of a direct `mcp__<server>__<tool>` reference, or null when
+ * the token isn't a direct MCP tool we resolve: a non-MCP tool, or the
+ * plugin-namespaced `mcp__plugin_…__…` form (guard 3 — deliberately skipped).
+ * A `Tool(restriction)` suffix is stripped first.
+ */
+function mcpToolServer(raw, dialect) {
+    const tool = raw.split("(")[0].trim();
+    if (!dialect.mcpToolPattern.test(tool))
+        return null;
+    // Non-greedy first segment after `mcp__`, up to the next `__`.
+    const m = /^mcp__(.+?)__/.exec(tool);
+    if (!m)
+        return null;
+    const server = m[1];
+    // Guard 3: the plugin-namespaced form references the plugin's OWN server under
+    // an ambiguous single-underscore join — don't try to split it, don't flag it.
+    if (server.startsWith("plugin_"))
+        return null;
+    return server;
+}
+/**
+ * Verify the MCP tool references in a contract against the plugin's declared MCP
+ * servers. Returns one {@link McpToolIssue} per direct `mcp__<server>__<tool>`
+ * whose server is neither declared nor a known built-in. Returns `[]` when no
+ * servers are declared (guard 1 — we can't know the resolvable set).
+ */
+function verifyMcpToolServers(tools, declaredServers, dialect) {
+    // Guard 1: no declared set → the plugin relies on global/project servers; we
+    // can't tell a dead reference from a legitimate global one. Flag nothing.
+    if (declaredServers.length === 0)
+        return [];
+    const known = new Set([
+        ...declaredServers,
+        ...(dialect.knownMcpServers ?? []),
+    ]);
+    const issues = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const server = mcpToolServer(raw, dialect);
+        if (server === null)
+            continue; // not a direct MCP tool / plugin-namespaced
+        if (known.has(server))
+            continue;
+        const tool = raw.split("(")[0].trim();
+        if (seen.has(tool))
+            continue; // de-dupe a repeated entry
+        seen.add(tool);
+        issues.push({
+            tool,
+            server,
+            message: `MCP tool "${tool}" references server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the tool can't resolve.`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=mcp-tool.js.map