vigiles 5.0.1 → 5.2.0

package/dist/core/effects.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyToolEffect = classifyToolEffect;
+exports.effectSurface = effectSurface;
+exports.purityViolations = purityViolations;
+exports.pureContractViolations = pureContractViolations;
+exports.decidePurityGate = decidePurityGate;
+const hash_js_1 = require("./hash.js");
+const bash_effects_js_1 = require("./bash-effects.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Strips a `Tool(restriction)` suffix and returns the base tool name. */
+function baseTool(raw) {
+    return raw.split("(")[0].trim();
+}
+/** Returns true for the wildcard sentinels that mean "inherits-all". */
+function isWildcard(tool) {
+    return tool === "" || tool === "*";
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Classify the effect of ONE tool name against a dialect's known catalogs.
+ *
+ * A `Tool(restriction)` suffix (e.g. `Bash(git:*)`) is stripped first — the
+ * restriction narrows what the tool can DO but doesn't change its effect class
+ * (Bash with any restriction is still conservatively side-effecting).
+ *
+ * Classification rules (in priority order):
+ *  1. In `dialect.sideEffectingTools`  → `"side-effecting"`
+ *  2. In `dialect.builtinAgentTools` (and NOT side-effecting) → `"read-only"`
+ *  3. Matches `dialect.mcpToolPattern` → `"unknown"` (MCP tools are not
+ *     classifiable from the name alone — treated as unknown-effect)
+ *  4. Otherwise → `"unknown"` (unrecognized tool; may be a plugin tool or a typo)
+ */
+function classifyToolEffect(tool, dialect) {
+    const base = baseTool(tool);
+    const sideEffecting = dialect.sideEffectingTools ?? [];
+    if (sideEffecting.includes(base))
+        return "side-effecting";
+    if (dialect.builtinAgentTools.includes(base))
+        return "read-only";
+    if (dialect.mcpToolPattern.test(base))
+        return "unknown";
+    return "unknown";
+}
+/**
+ * Compute the static effect surface of a declared `tools:` contract.
+ *
+ * `"*"` / `""` (inherits-all) entries make purity `"unrestricted"` because the
+ * contract grants access to all tools including every side-effecting one — the
+ * full surface is unknowable statically. They are NOT listed in any bucket
+ * (they represent a wildcard, not a named tool).
+ *
+ * De-duplication: a tool name that appears more than once in `tools` is counted
+ * once in its bucket (base tool after restriction stripping).
+ */
+function effectSurface(tools, dialect) {
+    const readOnly = new Set();
+    const sideEffecting = new Set();
+    const unknown = new Set();
+    let hasWildcard = false;
+    let hasBash = false;
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base)) {
+            hasWildcard = true;
+            continue; // wildcards don't go into any named bucket
+        }
+        const effect = classifyToolEffect(raw, dialect);
+        switch (effect) {
+            case "read-only":
+                readOnly.add(base);
+                break;
+            case "side-effecting":
+                sideEffecting.add(base);
+                if (base === "Bash")
+                    hasBash = true;
+                break;
+            case "unknown":
+                unknown.add(base);
+                break;
+            default:
+                (0, hash_js_1.assertNever)(effect);
+        }
+    }
+    const purity = hasWildcard || hasBash || unknown.size > 0
+        ? "unrestricted"
+        : sideEffecting.size > 0
+            ? "bounded"
+            : "pure";
+    return {
+        readOnly: [...readOnly],
+        sideEffecting: [...sideEffecting],
+        unknown: [...unknown],
+        purity,
+    };
+}
+/**
+ * Returns the violations of a DECLARED purity floor — the tools that make the
+ * actual effect surface LOOSER than the declared level. Empty ⇒ the contract
+ * honours the declared level. The `message` on each is actionable (names the
+ * tool, the effect class, and what to do).
+ *
+ * What counts as a violation depends on `declared`:
+ * - `"pure"`:         every side-effecting tool (incl. `Bash`), every
+ *                     unknown-effect tool, and any wildcard (a pure unit may
+ *                     only observe — no `Bash`, no effects, fully static).
+ * - `"bounded"`:      only the truly UNBOUNDED tools — unknown-effect (MCP /
+ *                     unrecognized) and wildcards. Every decidable side-effecting
+ *                     tool is ALLOWED: Write/Edit confine to the boundary, and
+ *                     `Bash` is admitted because the RUNTIME gate
+ *                     (`decidePurityGate`) refines it by command (read-only Bash
+ *                     is an observation; a mutating command is denied).
+ * - `"unrestricted"`: never a violation (the rung carries no constraint).
+ *
+ * A wildcard (`"*"` / `""`) contract is a violation at every constrained level:
+ * "inherits-all" grants every tool, so neither `pure` nor `bounded` can hold.
+ */
+function purityViolations(tools, dialect, declared) {
+    if (declared === "unrestricted")
+        return []; // no constraint to violate
+    const violations = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const base = baseTool(raw);
+        if (isWildcard(base)) {
+            const key = base === "" ? '""' : '"*"';
+            if (!seen.has(key)) {
+                seen.add(key);
+                violations.push({
+                    tool: base,
+                    effect: "side-effecting",
+                    message: `${key} (inherits-all) is not allowed in a ${declared} contract — it grants access to every tool, including side-effecting ones. Declare explicit tools instead.`,
+                });
+            }
+            continue;
+        }
+        if (seen.has(base))
+            continue;
+        const effect = classifyToolEffect(raw, dialect);
+        switch (effect) {
+            case "read-only":
+                break; // allowed at every level
+            case "unknown":
+                seen.add(base);
+                violations.push({
+                    tool: base,
+                    effect,
+                    message: `"${base}" has unknown effect class (MCP or unrecognized tool); a ${declared} contract cannot declare it — its effects are unbounded from static analysis. Remove it or declare the unit dangerously-unrestricted.`,
+                });
+                break;
+            case "side-effecting":
+                // In a BOUNDED unit every decidable side-effecting tool is allowed:
+                // Write/Edit confine to the boundary, and `Bash` is admitted because the
+                // RUNTIME gate (`decidePurityGate`) refines it by command — a read-only
+                // Bash is an observation, a mutating command is denied. Only `pure` bars
+                // them (a pure unit may only observe; no `Bash`, no effects).
+                if (declared === "bounded")
+                    break;
+                seen.add(base);
+                violations.push({
+                    tool: base,
+                    effect,
+                    message: base === "Bash"
+                        ? `"Bash" is undecidable at the tool-name level; a pure unit cannot declare it. A read-only Bash belongs in a bounded unit (the runtime gate confines it by command) — declare the unit bounded or dangerously-unrestricted.`
+                        : `"${base}" is side-effecting; a pure unit cannot declare it. Remove it or declare the unit bounded.`,
+                });
+                break;
+            default:
+                (0, hash_js_1.assertNever)(effect);
+        }
+    }
+    return violations;
+}
+/**
+ * The violations of a `purity: "pure"` contract — every side-effecting,
+ * unknown-effect, or wildcard tool. A thin alias for `purityViolations(…,
+ * "pure")` kept for the common pure case.
+ */
+function pureContractViolations(tools, dialect) {
+    return purityViolations(tools, dialect, "pure");
+}
+/**
+ * The RUNTIME half of the purity contract: decide whether a single LIVE tool
+ * call is allowed under the active unit's declared purity floor.
+ *
+ * Unlike `purityViolations` (which checks the DECLARED tools contract
+ * statically), this sees the ACTUAL call — including the `Bash` command string —
+ * so it refines `Bash` by effect via `isReadOnlyBash`. That command is the whole
+ * reason the gate's home is the runtime hook: only here is the concrete command
+ * visible (the static surface sees a tool name + a `Bash(git:*)` pattern, never
+ * the command).
+ *
+ * Rules (the ladder, command-refined):
+ * - `unrestricted` → always allow (no constraint).
+ * - read-only tool → allow at every level.
+ * - `Bash` → allow iff the command is provably read-only (an observation);
+ *   otherwise deny — a mutating/undecidable command's effect must move to a
+ *   marked boundary. Same at `pure` and `bounded`.
+ * - other side-effecting tool (Write, Edit, …) → allow under `bounded`
+ *   (a decidable, boundary-confined effect), deny under `pure` (observe-only).
+ * - unknown-effect (MCP / unrecognized) → deny under `pure`/`bounded`
+ *   (unbounded from static analysis).
+ *
+ * Dialect injected (core ⊄ adapter). Reuses `classifyToolEffect` +
+ * `isReadOnlyBash` — one-detector-no-drift with compile + scan.
+ */
+function decidePurityGate(declared, tool, command, dialect) {
+    if (declared === "unrestricted")
+        return { allow: true, message: "" };
+    const base = baseTool(tool);
+    const effect = classifyToolEffect(tool, dialect);
+    if (effect === "read-only")
+        return { allow: true, message: "" };
+    if (base === "Bash") {
+        if (command !== undefined && (0, bash_effects_js_1.isReadOnlyBash)(command)) {
+            return { allow: true, message: "" };
+        }
+        const shown = command ? `"${command}" ` : "";
+        return {
+            allow: false,
+            message: `Bash command ${shown}is not provably read-only; a ${declared} unit may run only read-only Bash ` +
+                `(observation). Move the side effect into a marked boundary, or declare the unit dangerously-unrestricted.`,
+        };
+    }
+    if (effect === "side-effecting") {
+        if (declared === "bounded")
+            return { allow: true, message: "" };
+        return {
+            allow: false,
+            message: `"${base}" is side-effecting; a pure unit may only observe. ` +
+                `Declare the unit bounded (or dangerously-unrestricted) to use it.`,
+        };
+    }
+    // unknown — MCP / unrecognized tool
+    return {
+        allow: false,
+        message: `"${base}" has unknown effect class; a ${declared} unit cannot use it — its effects are unbounded. ` +
+            `Declare the unit dangerously-unrestricted to allow it.`,
+    };
+}
+//# sourceMappingURL=effects.js.map

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/layout.d.ts

@@ -29,6 +29,12 @@ export interface PluginLayout {
     readonly instructionFile: string;
     /** Surface dirs materialized into the sandbox, e.g. skills/agents/commands. */
     readonly surfaceDirs: readonly string[];
+    /** Skills dir, holding the nested `<dir>/<name>/SKILL.md`, e.g. `skills`. */
+    readonly skillDir: string;
+    /** Subagents dir, holding flat `<dir>/<name>.md`, e.g. `agents` (`""` = none). */
+    readonly agentDir: string;
+    /** Slash-commands dir, holding flat `<dir>/<name>.md`, e.g. `commands`. */
+    readonly commandDir: string;
     /** Dir the surfaces are materialized under, e.g. `.claude`. */
     readonly materializeRoot: string;
     /** Env token expanded to the plugin's absolute root in hook commands. */

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