vigiles 10.0.0 → 12.0.0

package/dist/core/CLAUDE.md.spec.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Directory-scoped guidance for working in `src/core/` (the harness-agnostic
+ * detectors + domain).
+ *
+ * The full project rule set is the ROOT `CLAUDE.md` (compiled from
+ * `CLAUDE.md.spec.ts`). This nested spec adds only the discipline that belongs
+ * next to the detectors themselves — Claude Code loads it as directory memory
+ * whenever you work in `src/core/`. Source of truth; `src/core/CLAUDE.md` is a
+ * compiled build artifact (`vigiles compile`).
+ */
+const spec_js_1 = require("./spec.js");
+exports.default = (0, spec_js_1.claude)({
+    sections: {
+        scope: `Working in \`src/core/\`? This is the harness-AGNOSTIC domain (spec, compile, linters, the lint/audit detectors). The root \`CLAUDE.md\` holds the full positioning + rule set — read it first. Two invariants live closest to this code: the core must not import an adapter (\`core ⊄ adapter\`, eslint-enforced) and must not hard-code a Claude Code literal (read it from the injected layout/dialect). This file adds the rule for ADDING or CHANGING a detector.`,
+    },
+    keyFiles: {
+        "src/core/rule-meta.ts": "The RuleMeta registry — every rule's decidability bucket + severity + detector, the single source the detector-meta rule enforces.",
+        "src/core/types.ts": "RulesConfig — the rule-name keys the registry is keyed on.",
+    },
+    rules: {
+        "detector-meta": (0, spec_js_1.guidance)("A deterministic DETECTOR here is one half of a RULE — and a rule is not done until it is DECLARED. Three things move together (sibling of one-detector-no-drift + rules-docs-in-sync): (1) the pure detector function (shared by `lint` AND `audit`, never reimplemented per surface; read the layout/dialect, never a CC literal); (2) its entry in `src/core/rule-meta.ts` — the `Record<RuleName, RuleMeta>` won't typecheck without it — declaring its DECIDABILITY BUCKET (structural-closed = a type could prevent it / external-decidable = needs the world, error-capable / heuristic-behavioral = warn-or-measure-only), surface, defaultSeverity, the detector name, and any upstreamPrevention; (3) its `docs/rules/<name>.md` (the coverage test binds the registry to the docs by an EXACT set match, so a missing meta or doc fails CI). The bucket is the CEILING, not a preference — a heuristic proxy may NEVER default to `error` (it cries wolf); a structural/external fact MAY, once proven FP-safe. Before writing a new detector, CLASSIFY the defect into a bucket — that decides whether it can ever gate. The full model + the prose behind the buckets is the root `lint-rule-calibration` rule and `research/enforcement-model.md`."),
+    },
+});
+//# sourceMappingURL=CLAUDE.md.spec.js.map

package/dist/core/delegation-trifecta.d.ts

@@ -0,0 +1,64 @@
+/**
+ * DELEGATION-TRIFECTA — the lethal trifecta SPLIT across a delegation edge.
+ *
+ * The per-unit {@link lethalTrifectaIssues} (`./lethal-trifecta.ts`) catches a
+ * single subagent / skill that holds all THREE capability legs at once. But the
+ * trifecta can EMERGE across a delegation (or inheritance) edge: a parent that
+ * can only read private data (leg A) delegates to a child that can ingest
+ * untrusted content AND exfiltrate (legs B+C). NEITHER unit trips the per-unit
+ * check, yet the CHAIN — the parent plus everything it can reach — forms the full
+ * trifecta. A prompt injection in the child's untrusted input can pivot back
+ * through the delegation and leak the parent's private data.
+ *
+ * This is CAPABILITY-DIFF ACROSS THE DELEGATION TREE: the EFFECTIVE (combined)
+ * capability of a unit is the union of its own tools plus the tools of every unit
+ * reachable through `delegatesTo`. We classify that effective set and flag a unit
+ * whose effective set is a full trifecta while its OWN set is not.
+ *
+ * NO DOUBLE-REPORT (one-detector-no-drift / don't-cry-wolf): a unit whose OWN
+ * tools already form a full trifecta is SKIPPED here — {@link lethalTrifectaIssues}
+ * owns it. This detector reports ONLY the EMERGENT case the per-unit check can't
+ * see.
+ *
+ * HIGH-PRECISION (FP-safe): if the effective set contains a wildcard (inherits-all)
+ * the unit reaches everything and would always "trifecta" — that maximal-blast-
+ * radius case is the per-unit ADVISORY detector's job, so we SKIP it. We flag ONLY
+ * concrete, explicit tool unions where every leg is supplied by a named tool.
+ *
+ * Pure, no IO. The delegation graph (nodes + directed `delegatesTo` edges) is the
+ * INPUT — this module does not decide where edges come from; a caller supplies them
+ * from the parsed harness. The dialect is injected (core ⊄ adapter), reused for the
+ * underlying leg classification.
+ */
+import type { HarnessDialect } from "./dialect.js";
+import { type TrifectaLegs } from "./lethal-trifecta.js";
+/** One unit (subagent/skill) in the delegation graph. */
+export interface CapabilityNode {
+    readonly name: string;
+    readonly kind: "skill" | "agent";
+    /** This unit's OWN declared tools. [] = none declared. ["*"] = inherits-all (wildcard). */
+    readonly tools: readonly string[];
+    /** Names of units this one can delegate to / inherits capabilities from (directed edges). */
+    readonly delegatesTo: readonly string[];
+}
+/** A trifecta that EMERGES across delegation — present in a unit's effective set but NOT its own. */
+export interface DelegationTrifectaFinding {
+    readonly name: string;
+    readonly kind: "skill" | "agent";
+    /** The delegated-to units (by name) that supplied at least one leg the unit lacks on its own. */
+    readonly via: readonly string[];
+    /** The tools that supplied each leg in the EFFECTIVE (combined) set. */
+    readonly legs: TrifectaLegs;
+    /** Ready-to-show, actionable message. */
+    readonly message: string;
+}
+/**
+ * Find units whose EFFECTIVE (own + delegated) capability set forms a full lethal
+ * trifecta that their OWN set does not — an emergent, cross-delegation exfil path.
+ *
+ * Returns findings in stable order (by node name). See the module header for the
+ * skip rules (own-set already a trifecta → owned by the per-unit detector; an
+ * effective wildcard → owned by the per-unit advisory).
+ */
+export declare function delegationTrifectaIssues(nodes: readonly CapabilityNode[], dialect: HarnessDialect): DelegationTrifectaFinding[];
+//# sourceMappingURL=delegation-trifecta.d.ts.map

package/dist/core/delegation-trifecta.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delegationTrifectaIssues = delegationTrifectaIssues;
+const lethal_trifecta_js_1 = require("./lethal-trifecta.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** A full trifecta = all three legs non-empty. */
+function isFullTrifecta(legs) {
+    return (legs.private.length > 0 &&
+        legs.untrusted.length > 0 &&
+        legs.exfil.length > 0);
+}
+/** Strips a `Tool(restriction)` suffix and returns the base tool name. */
+function baseTool(raw) {
+    return raw.split("(")[0].trim();
+}
+/** True for the wildcard sentinels that mean "inherits-all". */
+function isWildcard(tool) {
+    return tool === "" || tool === "*";
+}
+/**
+ * The set of node names reachable from `start` over `delegatesTo`, INCLUDING
+ * `start` itself. Cycle-safe (a `visited` set). An edge naming a node not in the
+ * map is skipped — its tools can't be resolved.
+ */
+function effectiveReach(start, byName) {
+    const visited = new Set();
+    const stack = [start];
+    while (stack.length > 0) {
+        const name = stack.pop();
+        if (name === undefined || visited.has(name))
+            continue;
+        visited.add(name);
+        const node = byName.get(name);
+        if (node === undefined)
+            continue;
+        for (const next of node.delegatesTo) {
+            if (!visited.has(next))
+                stack.push(next);
+        }
+    }
+    return visited;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Find units whose EFFECTIVE (own + delegated) capability set forms a full lethal
+ * trifecta that their OWN set does not — an emergent, cross-delegation exfil path.
+ *
+ * Returns findings in stable order (by node name). See the module header for the
+ * skip rules (own-set already a trifecta → owned by the per-unit detector; an
+ * effective wildcard → owned by the per-unit advisory).
+ */
+function delegationTrifectaIssues(nodes, dialect) {
+    const byName = new Map();
+    for (const node of nodes)
+        byName.set(node.name, node);
+    const findings = [];
+    for (const node of nodes) {
+        // (b) If the unit's OWN tools already form a full trifecta, the per-unit
+        // detector owns it — never double-report.
+        const ownLegs = (0, lethal_trifecta_js_1.classifyTrifectaLegs)(node.tools, dialect);
+        if (isFullTrifecta(ownLegs))
+            continue;
+        // (c) Effective tools = the de-duplicated union across the reachable set.
+        const reach = effectiveReach(node.name, byName);
+        const effSet = new Set();
+        for (const name of reach) {
+            const reached = byName.get(name);
+            if (reached === undefined)
+                continue;
+            for (const tool of reached.tools)
+                effSet.add(tool);
+        }
+        const effectiveTools = [...effSet];
+        // (d) FP-safe wildcard guard: an inherits-all unit in the reachable set
+        // would always "trifecta" — that's the per-unit advisory's job.
+        if (effectiveTools.some((t) => isWildcard(baseTool(t))))
+            continue;
+        // (e) Classify the effective set.
+        const effLegs = (0, lethal_trifecta_js_1.classifyTrifectaLegs)(effectiveTools, dialect);
+        // (f) Emit ONLY when the effective set is a full trifecta (own set wasn't).
+        if (!isFullTrifecta(effLegs))
+            continue;
+        // The tools that supplied any leg in the effective set.
+        const legTools = new Set([
+            ...effLegs.private,
+            ...effLegs.untrusted,
+            ...effLegs.exfil,
+        ]);
+        // `via` = reachable units (excluding this node) that contribute a leg tool.
+        const via = [];
+        for (const name of reach) {
+            if (name === node.name)
+                continue;
+            const reached = byName.get(name);
+            if (reached === undefined)
+                continue;
+            const contributes = reached.tools.some((t) => legTools.has(baseTool(t)));
+            if (contributes && !via.includes(name))
+                via.push(name);
+        }
+        via.sort();
+        const message = `Subagent "${node.name}" is not a data-leak risk on its own, but combined ` +
+            `with what it delegates to (${via.join(", ")}), the chain can read private ` +
+            `data (${effLegs.private.join(", ")}), ingest untrusted content ` +
+            `(${effLegs.untrusted.join(", ")}), AND exfiltrate ` +
+            `(${effLegs.exfil.join(", ")}) — a prompt injection in the untrusted input ` +
+            `could pivot through the delegation to leak data. Break the delegation or ` +
+            `drop one leg.`;
+        findings.push({
+            name: node.name,
+            kind: node.kind,
+            via,
+            legs: effLegs,
+            message,
+        });
+    }
+    findings.sort((a, b) => a.name.localeCompare(b.name));
+    return findings;
+}
+//# sourceMappingURL=delegation-trifecta.js.map

package/dist/core/dialect.d.ts

@@ -42,6 +42,24 @@ export interface HarnessDialect {
     readonly knownMcpServers?: readonly string[];
     /** Hook event names the harness fires. */
     readonly hookEvents: readonly string[];
+    /**
+     * The subset of `hookEvents` where a block decision (`exit 2` / a deny field)
+     * is SILENTLY IGNORED ENTIRELY — no veto AND no model feedback (Claude Code's
+     * SessionStart / SessionEnd / Notification / PreCompact: exit 2 there writes
+     * stderr only to the user). The basis for the `hook-block-ineffective`
+     * "wrong-event" check, which fires ONLY on these (so it stays FP-safe and never
+     * cries wolf on a PostToolUse feedback/nudge hook). Optional (additive,
+     * non-breaking) — absent ⇒ the harness's block semantics are undeclared and the
+     * check does not run for it.
+     */
+    readonly noEffectHookEvents?: readonly string[];
+    /**
+     * The subset of blocking events whose deny REQUIRES the structured
+     * `permissionDecision` field (e.g. Claude Code's `PreToolUse`), where the
+     * legacy top-level `decision` field is silently ignored. The basis for the
+     * `hook-block-ineffective` "wrong-field" check. Optional (additive).
+     */
+    readonly permissionDecisionHookEvents?: readonly string[];
     /** Instruction-file targets the harness reads (also the h1 heading). */
     readonly instructionTargets: readonly string[];
     /** The env token expanded to the plugin root in hook commands. */

package/dist/core/hook-block-ineffective.d.ts

@@ -0,0 +1,62 @@
+/** The two "looks like it blocks but doesn't" failure shapes. */
+export type HookBlockKind = "wrong-event" | "wrong-field";
+/** One false-confidence finding: a hook that appears to block but silently won't. */
+export interface HookBlockFinding {
+    readonly event: string;
+    readonly kind: HookBlockKind;
+    /** The hook script that was inspected (path if resolved from a script file, else null = inline command). */
+    readonly scriptPath: string | null;
+    readonly message: string;
+}
+/** A single hook registration to inspect. */
+export interface HookScriptEntry {
+    readonly event: string;
+    readonly matcher?: string;
+    /** The hook command line as registered. */
+    readonly command: string;
+    /** Resolved path to the script file the command runs, if known (else null → inspect `command`). */
+    readonly scriptPath?: string | null;
+}
+/** Options for {@link hookBlockIssues}. All fields are injectable for testability. */
+export interface HookBlockOptions {
+    /**
+     * Events on this harness where a block decision (`exit 2` / a deny field) is
+     * SILENTLY IGNORED ENTIRELY — no veto AND no feedback to the model (Claude
+     * Code's `SessionStart`/`SessionEnd`/`Notification`/`PreCompact`: exit 2 there
+     * only writes stderr to the user). These are the ONLY events the "wrong-event"
+     * check fires on, so it stays FP-safe.
+     *
+     * Deliberately EXCLUDES `PostToolUse`: a `PostToolUse` exit 2 feeds stderr back
+     * to the model — a legitimate FEEDBACK channel, NOT a failed block — so flagging
+     * it would cry wolf on every nudge/lint hook (the dogfood lesson: vigiles's own
+     * `refs-nudge.sh` is exactly that shape). A hook that exits 2 on `PostToolUse`
+     * intending to BLOCK is misguided, but that intent is not deterministically
+     * distinguishable from feedback, so we don't flag it.
+     */
+    readonly noEffectEvents: ReadonlySet<string>;
+    /**
+     * Events that require the structured `permissionDecision` field for a deny
+     * (e.g. `PreToolUse`). On these events the legacy top-level `"decision":"block"`
+     * field is ignored; only `hookSpecificOutput.permissionDecision:"deny"` works.
+     */
+    readonly permissionDecisionEvents: ReadonlySet<string>;
+    /**
+     * Injectable file read (default: node:fs `readFileSync(p, "utf8")`).
+     * Returns `""` on any error so a missing / unreadable script doesn't crash
+     * the detector — it simply produces no findings for that entry.
+     */
+    readonly readFileSync?: (p: string) => string;
+}
+/**
+ * Detect false-confidence "blocks" across a set of hook entries.
+ *
+ * Returns one {@link HookBlockFinding} per entry (at most one per entry —
+ * `wrong-event` takes precedence over `wrong-field`). Identical
+ * (event, kind, scriptPath) pairs are de-duped.
+ *
+ * @param entries - The hook registrations to inspect (event + command/script).
+ * @param opts    - Injected sets of blocking/permission events, and an optional
+ *                  `readFileSync` (default: node:fs).
+ */
+export declare function hookBlockIssues(entries: readonly HookScriptEntry[], opts: HookBlockOptions): HookBlockFinding[];
+//# sourceMappingURL=hook-block-ineffective.d.ts.map

package/dist/core/hook-block-ineffective.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookBlockIssues = hookBlockIssues;
+/**
+ * Hook-block-ineffective detector — the #1 verified hook pain ("false confidence").
+ *
+ * A safety hook that LOOKS like it blocks but SILENTLY DOESN'T. Two shapes:
+ *
+ * 1. **wrong-event** — the script tries to block (contains `exit 2`, a legacy
+ *    `"decision":"block"` JSON, or a `"permissionDecision":"deny"`) but is
+ *    registered on an event where a block is SILENTLY IGNORED ENTIRELY —
+ *    SessionStart / SessionEnd / Notification / PreCompact, where exit 2 writes
+ *    stderr only to the user (no veto, no model feedback). The author believes a
+ *    gate is in place; nothing happens. (#19009 names the class.) NB `PostToolUse`
+ *    is deliberately NOT flagged: there exit 2 feeds stderr back to the model — a
+ *    legitimate FEEDBACK channel (a nudge/lint hook), not a failed block, and the
+ *    block-vs-feedback intent isn't deterministically separable.
+ *
+ * 2. **wrong-field** — the hook IS on a permission-gated event (e.g. PreToolUse)
+ *    but emits the LEGACY top-level `"decision":"block"` field instead of the
+ *    required `hookSpecificOutput.permissionDecision:"deny"`. A copied template
+ *    (PostToolUse style → PreToolUse registration) is the usual cause; the deny
+ *    is silently discarded, nothing is blocked.
+ *
+ * Both shapes cause identical user-visible behaviour: the hook "works" (exits,
+ * no crash) but never actually stops anything. The only signal is "why did this
+ * run anyway?" after an incident.
+ *
+ * FP-SAFETY — conservative literal patterns only, `warn` severity by default:
+ *   - `exit 2` is matched by a shell-context regex that requires surrounding
+ *     whitespace/control chars to avoid false-positives on `exit 200` or a
+ *     `git status --exit-code 2` argument.
+ *   - JSON decision patterns are matched literally (no partial JSON walking).
+ *   - Nothing is flagged on an unknown event (we only know which events CAN
+ *     block because the caller injected that set).
+ *
+ * HARNESS-NEUTRAL — the sets of blocking events and permission-decision events
+ * are INJECTED from the dialect (never hard-coded here). The caller supplies the
+ * Claude Code sets; a Codex adapter supplies its own. This is the same
+ * dependency-injection pattern used by `verifyHookEvents` and `verifyToolContract`
+ * (core ⊄ adapter — one-detector-no-drift).
+ *
+ * ONE detector reused by scan + the `hook-block-ineffective` lint rule (two
+ * callers, no drift). See `research/hook-pain-points.md` for the verified corpus
+ * and `docs/compiled-hooks.md` for the authoritative fix (compiled hooks make
+ * this whole class unrepresentable).
+ */
+const node_fs_1 = require("node:fs");
+// ---------------------------------------------------------------------------
+// Block-mechanism patterns (conservative / FP-safe)
+// ---------------------------------------------------------------------------
+/**
+ * An `exit 2` statement.
+ *
+ * Requires a shell-context separator before `exit` (start-of-line, whitespace,
+ * `;`, `&`, `|`) and word-boundary / separator after `2` — so `exit 200` and
+ * `--exit-code 2` are NOT matched.
+ */
+const EXIT_2 = /(^|[\s;&|])exit\s+2(\s|;|$|['")])/m;
+/**
+ * A status-2 exit in a NON-shell hook script (a hook file may be `.js`/`.mjs`/
+ * `.py`/`.rb`): `process.exit(2)` (Node), `sys.exit(2)` / `exit(2)` (Python),
+ * `Process.exit(2)` / `exit(2)` (Ruby), `os._exit(2)`. So a guard written in
+ * Node/Python on a no-effect event isn't shown clean.
+ */
+const EXIT_2_CODE = /\b(?:process\.exit|sys\.exit|os\._exit|Process\.exit|exit)\s*\(\s*2\s*\)/;
+/**
+ * A legacy top-level `"decision":"block"` or `"decision":"deny"` JSON field.
+ * This is the OLD Claude Code hook output format. On permission-gated events
+ * (PreToolUse) it is ignored; on non-blocking events it never had any effect.
+ */
+const DECISION_BLOCK = /"decision"\s*:\s*"(block|deny)"/;
+/**
+ * The CORRECT structured deny for permission-gated events:
+ * `"permissionDecision":"deny"` or `"permissionDecision":"ask"`.
+ * (Both require a structured response, as opposed to the legacy field.)
+ */
+const PERMISSION_DENY = /"permissionDecision"\s*:\s*"(deny|ask)"/;
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+function defaultReadFile(p) {
+    try {
+        return (0, node_fs_1.readFileSync)(p, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Detect false-confidence "blocks" across a set of hook entries.
+ *
+ * Returns one {@link HookBlockFinding} per entry (at most one per entry —
+ * `wrong-event` takes precedence over `wrong-field`). Identical
+ * (event, kind, scriptPath) pairs are de-duped.
+ *
+ * @param entries - The hook registrations to inspect (event + command/script).
+ * @param opts    - Injected sets of blocking/permission events, and an optional
+ *                  `readFileSync` (default: node:fs).
+ */
+function hookBlockIssues(entries, opts) {
+    const { noEffectEvents, permissionDecisionEvents } = opts;
+    const readFile = opts.readFileSync ?? defaultReadFile;
+    const findings = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        // Determine the script text and the canonical "path" label for findings.
+        const scriptPath = entry.scriptPath ?? null;
+        const text = scriptPath !== null ? readFile(scriptPath) : (entry.command ?? "");
+        // Detect block mechanisms.
+        const hasExit2 = EXIT_2.test(text) || EXIT_2_CODE.test(text);
+        const hasDecisionBlock = DECISION_BLOCK.test(text);
+        const hasPermissionDeny = PERMISSION_DENY.test(text);
+        const triesBlock = hasExit2 || hasDecisionBlock || hasPermissionDeny;
+        if (!triesBlock)
+            continue;
+        let kind = null;
+        let message = "";
+        if (noEffectEvents.has(entry.event)) {
+            // wrong-event: a block on an event where it's silently ignored entirely
+            // (no veto AND no feedback — stderr goes to the user, not the model).
+            kind = "wrong-event";
+            message =
+                `This hook tries to block (exit 2 / "decision" / "permissionDecision") ` +
+                    `but on "${entry.event}" a block decision is silently ignored — it can ` +
+                    `neither veto nor feed the model back (stderr goes only to the user). ` +
+                    `Nothing is prevented. Move the gate to a blocking event (e.g. PreToolUse) ` +
+                    `so the deny fires BEFORE the action.`;
+        }
+        else if (permissionDecisionEvents.has(entry.event) &&
+            hasDecisionBlock &&
+            !hasPermissionDeny) {
+            // wrong-field: on a permission-gated event, uses the legacy field.
+            kind = "wrong-field";
+            message =
+                `On "${entry.event}" a deny must use ` +
+                    `\`hookSpecificOutput.permissionDecision:"deny"\`; this script uses the ` +
+                    `legacy top-level \`"decision"\` field, which is ignored on this event, ` +
+                    `so nothing is blocked. Update the JSON output to the structured form: ` +
+                    `\`{"hookSpecificOutput":{"permissionDecision":"deny"}}\`.`;
+        }
+        if (kind === null)
+            continue;
+        // De-dupe identical (event, kind, scriptPath) triples.
+        const dedupeKey = `${entry.event}:${kind}:${scriptPath ?? ""}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        findings.push({ event: entry.event, kind, scriptPath, message });
+    }
+    return findings;
+}
+//# sourceMappingURL=hook-block-ineffective.js.map

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

@@ -0,0 +1,66 @@
+/**
+ * Hook-matcher verification — the cross-referencing moat applied to the MATCHER
+ * string inside a hook registration. A PreToolUse hook fires only when its
+ * `matcher` equals the tool name the harness emits (or matches via glob/regex); a
+ * typo or wrong form silently prevents the hook from ever running — exactly the
+ * FALSE CONFIDENCE failure the compiled-hooks design exists to eliminate
+ * (research/hook-pain-points.md).
+ *
+ * THREE kinds of bad matcher, each verified here (one-detector-no-drift):
+ *
+ * 1. **tool-typo** — a bare token that is a CLOSE TYPO (edit distance ≤ 2) of a
+ *    real built-in tool name but not an exact match (`bash` → `Bash`, `read` →
+ *    `Read`). Suggests the correct casing. Reuses `closestTool` from
+ *    `tool-contract.ts` — same edit-distance logic, same ≤ 2 confidence bound.
+ *
+ * 2. **mcp-form** — a token that looks MCP-ish (starts with `mcp`, case-
+ *    insensitive) but is NOT the required `mcp__<server>__<tool>` double-underscore
+ *    shape (single underscores, a hyphen, a trailing `*`…). Suggests the corrected
+ *    form when the server/tool segments can be recovered.
+ *
+ * 3. **mcp-undeclared** — a correctly-formed `mcp__<server>__…` token whose server
+ *    is NOT in the plugin's declared MCP servers. Gated EXACTLY like
+ *    `mcp-tool-resolves`: (a) no declared set → skip (reaches global/project
+ *    servers); (b) built-ins allowlisted via `dialect.knownMcpServers`; (c) the
+ *    plugin-namespaced `mcp__plugin_…__…` form is skipped. Reuses `mcpToolServer`
+ *    from `mcp-tool.ts` for the extraction — one parser, no drift.
+ *
+ * FP-SAFE: only a SINGLE bare token is inspected. A matcher that is empty, a pure
+ * wildcard (`*` / `.*`), or contains alternation (`|`) or other regex meta-
+ * characters is skipped — it is a pattern/glob with legitimate broad matching, not
+ * a tool name. Same don't-cry-wolf discipline as every other vigiles detector.
+ *
+ * Pure + ONE detector reused by `scan` + the `hook-matcher` lint rule
+ * (one-detector-no-drift). The dialect is injected (core ⊄ adapter).
+ */
+import type { HarnessDialect } from "./dialect.js";
+/** Which matching failure was detected in the hook matcher string. */
+export type HookMatcherKind = "tool-typo" | "mcp-form" | "mcp-undeclared";
+/** One finding for a hook matcher that will silently never fire. */
+export interface HookMatcherFinding {
+    /** The matcher string exactly as written. */
+    readonly matcher: string;
+    /** Which class of error was detected. */
+    readonly kind: HookMatcherKind;
+    /**
+     * The corrected matcher when the intent is recoverable (e.g. `Bash` for
+     * `bash`, `mcp__memory__.*` for `mcp_memory_*`). Absent when the server
+     * segment can't be recovered from a malformed MCP form.
+     */
+    readonly suggestion?: string;
+    /** A ready-to-show, actionable message. */
+    readonly message: string;
+}
+/** A single hook registration entry — its event and matcher string. */
+export interface HookMatcherEntry {
+    readonly event: string;
+    readonly matcher: string;
+}
+/**
+ * Verify hook-matcher strings for the three forms that silently never fire.
+ * Returns one {@link HookMatcherFinding} per offending entry. De-duplicates
+ * repeated matchers. Returns `[]` when all matchers are FP-safe to skip or
+ * are correct.
+ */
+export declare function hookMatcherIssues(entries: readonly HookMatcherEntry[], declaredServers: readonly string[], dialect: HarnessDialect): HookMatcherFinding[];
+//# sourceMappingURL=hook-matcher.d.ts.map