vigiles 10.0.0 → 11.0.0

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

package/dist/core/hook-matcher.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hookMatcherIssues = hookMatcherIssues;
+const tool_contract_js_1 = require("./tool-contract.js");
+const mcp_tool_js_1 = require("./mcp-tool.js");
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Whether a matcher token should be skipped for FP-safety. We ONLY inspect
+ * a SINGLE bare token that could plausibly be a literal tool name or MCP
+ * reference. Anything with regex / glob meta-characters, alternation, a
+ * trailing glob wildcard alone, or an empty string is a pattern — skip it.
+ *
+ * Conservative by design: an unrecognized form → skip, never flag.
+ */
+function isInspectableToken(token) {
+    if (token.length === 0)
+        return false;
+    // Pure wildcard forms used as "match-all" matchers.
+    if (token === "*" || token === ".*" || token === "**")
+        return false;
+    // Contains regex alternation — a combined matcher, not a single tool name.
+    if (token.includes("|"))
+        return false;
+    // Contains a parenthesised group `(…)` — regex, not a tool name.
+    if (token.includes("(") || token.includes(")"))
+        return false;
+    // Contains a `[` — character class; skip.
+    if (token.includes("["))
+        return false;
+    // A leading `^` or trailing `$` — anchored regex.
+    if (token.startsWith("^") || token.endsWith("$"))
+        return false;
+    // Leading `.*` — regex prefix; always a pattern.
+    if (token.startsWith(".*"))
+        return false;
+    // A trailing `.*`/`*` is a glob/regex suffix on a plain TOOL matcher (`Bash.*`,
+    // `Read*`) → skip. But for an MCP-ish token the trailing wildcard is EXACTLY
+    // what we must inspect: `mcp__server__.*` is the legitimate match-all-tools
+    // form, and `mcp_memory_*` is the classic single-underscore typo we want to
+    // catch — so do NOT skip a wildcard suffix on an `mcp`-ish token.
+    if (!looksMcpIsh(token) && (token.endsWith(".*") || token.endsWith("*")))
+        return false;
+    return true;
+}
+/**
+ * A token starts with `mcp` (case-insensitive) and contains at least one
+ * `_` (making it look like an MCP tool reference, not a harness built-in).
+ */
+function looksMcpIsh(token) {
+    return /^mcp[_-]/i.test(token);
+}
+/**
+ * Whether `token` matches the canonical `mcp__<server>__<rest>` double-
+ * underscore shape (the valid MCP matcher form). We use the dialect's own
+ * `mcpToolPattern` extended to allow trailing `.*` for wildcard matchers,
+ * since a hook `matcher` may be `mcp__server__.*` (match-all-tools-on-server).
+ */
+function isValidMcpForm(token, dialect) {
+    // The canonical pattern from the dialect: `mcp__server__tool`.
+    if (dialect.mcpToolPattern.test(token))
+        return true;
+    // Also allow the wildcard suffix form `mcp__server__.*`.
+    if (/^mcp__[a-z0-9_-]+__\.\*$/i.test(token))
+        return true;
+    return false;
+}
+/**
+ * Attempt to recover the server segment from a malformed MCP token so we can
+ * suggest the corrected `mcp__<server>__.*` form. Returns null when no
+ * segment can be confidently recovered.
+ *
+ * Handles:
+ *   - Single-underscore: `mcp_memory_search` → server=`memory`, tool=`search`
+ *   - Hyphenated:        `mcp-memory-search` → server=`memory`, tool=`search`
+ *   - Glob suffix:       `mcp_memory_*`       → server=`memory`
+ *   - Mixed:             `mcp__memory_*`      → only one `__` segment found
+ */
+function recoverMcpServer(token) {
+    // Strip a leading `mcp` and then a separator (`__`, `_`, `-`).
+    const rest = token.replace(/^mcp(?:__|_|-)/i, "");
+    if (!rest || rest === token)
+        return null;
+    // Split on single underscores or hyphens (not `__`) to get the next segment.
+    // We want the first non-empty segment after the `mcp` prefix separator.
+    const segments = rest.split(/(?<!_)_(?!_)|(?<!-)(?:-(?!-))/);
+    const server = segments[0];
+    if (!server || server.length === 0)
+        return null;
+    // Reject segments that are clearly numeric-only or single chars (too ambiguous).
+    if (/^\d+$/.test(server))
+        return null;
+    return server;
+}
+// ---------------------------------------------------------------------------
+// Public detector
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function hookMatcherIssues(entries, declaredServers, dialect) {
+    const findings = [];
+    const seen = new Set();
+    for (const { matcher } of entries) {
+        // De-dupe repeated matchers across entries.
+        if (seen.has(matcher))
+            continue;
+        seen.add(matcher);
+        // Skip wildcards, alternation, regex patterns — FP-safety.
+        if (!isInspectableToken(matcher))
+            continue;
+        // ── kind: mcp-form ──────────────────────────────────────────────────────
+        // The token looks MCP-ish but is NOT the valid double-underscore form.
+        if (looksMcpIsh(matcher)) {
+            if (!isValidMcpForm(matcher, dialect)) {
+                const server = recoverMcpServer(matcher);
+                const suggestion = server ? `mcp__${server}__.*` : undefined;
+                const hintPart = suggestion !== undefined
+                    ? ` Did you mean "${suggestion}"?`
+                    : " Use the form `mcp__<server>__<tool>` (double underscores).";
+                findings.push({
+                    matcher,
+                    kind: "mcp-form",
+                    ...(suggestion !== undefined ? { suggestion } : {}),
+                    message: `Hook matcher "${matcher}" is not a valid MCP tool reference (requires double underscores: \`mcp__server__tool\`).${hintPart}`,
+                });
+                continue;
+            }
+            // ── kind: mcp-undeclared ──────────────────────────────────────────────
+            // A correctly-formed MCP token whose server isn't in the declared set.
+            // Guard 1: no declared set → skip (reaches global/project servers).
+            if (declaredServers.length === 0)
+                continue;
+            // `mcpToolServer` reads the `mcp__server__tool` form; a server-wide WILDCARD
+            // matcher (`mcp__server__.*`) isn't a concrete tool, so fall back to the
+            // wildcard server segment so an undeclared server is still caught.
+            const server = (0, mcp_tool_js_1.mcpToolServer)(matcher, dialect) ??
+                /^mcp__([a-z0-9_-]+)__\.\*$/i.exec(matcher)?.[1] ??
+                null;
+            if (server === null)
+                continue; // plugin-namespaced form → guard 3, skip
+            // The plugin-namespaced `mcp__plugin_<plugin>_<server>__` form is the
+            // plugin's OWN server — never an undeclared reference (mirrors mcpToolServer).
+            if (/^plugin_/i.test(server))
+                continue;
+            const known = new Set([
+                ...declaredServers,
+                ...(dialect.knownMcpServers ?? []),
+            ]);
+            // Guard 2: built-in server → skip.
+            if (known.has(server))
+                continue;
+            findings.push({
+                matcher,
+                kind: "mcp-undeclared",
+                message: `Hook matcher "${matcher}" references MCP server "${server}", which the plugin doesn't declare (declared: ${declaredServers.join(", ")}) — the hook can't fire.`,
+            });
+            continue;
+        }
+        // ── kind: tool-typo ─────────────────────────────────────────────────────
+        // A bare token that is NOT an exact built-in tool but IS a close typo of one.
+        const knownTools = new Set(dialect.builtinAgentTools);
+        if (knownTools.has(matcher))
+            continue; // exact match → no issue
+        // Reuse the same ≤ 2 edit-distance helper from tool-contract.ts.
+        const near = (0, tool_contract_js_1.closestTool)(matcher, dialect);
+        if (near === null)
+            continue; // far/unknown → likely a plugin tool, not a typo
+        findings.push({
+            matcher,
+            kind: "tool-typo",
+            suggestion: near,
+            message: `Hook matcher "${matcher}" doesn't match any built-in tool — the hook silently never fires. Did you mean "${near}"?`,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=hook-matcher.js.map

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

@@ -0,0 +1,43 @@
+/**
+ * vigiles — hook settings normalization (the typed boundary for shipped hooks).
+ *
+ * A repo's hooks ship as raw, untrusted, parsed JSON/TOML — `unknown` at the
+ * loader edge (`LoadedPlugin.settings.hooks`). Rather than have every detector
+ * re-walk that `unknown` with inline casts (parse-don't-validate violated N
+ * times), this parses it ONCE at the boundary into a typed, flattened
+ * `HookRegistration[]` that the walkers consume.
+ *
+ * HARNESS-AGNOSTIC BY TOLERANCE, NOT BY A PORT. Two shipping shapes exist:
+ *   - Claude Code (JSON):  `{ Event: [{ matcher, hooks: [{ command }] }] }`
+ *   - Codex (TOML):        `{ Event: [{ command }] }`  (`[[hooks.Event]] command=…`)
+ * A single tolerant reader absorbs both — a missing `hooks` array means the
+ * entry itself is the lone command holder. The difference is small enough that
+ * one parser covers it, so we deliberately DON'T add a per-harness port for it
+ * (rule-of-three / YAGNI: design the neutral shape first, defer the abstraction
+ * until a harness needs a genuinely divergent shape). If one ever does, this is
+ * the single seam to lift behind the layout/dialect.
+ *
+ * Pure + fully testable (no IO); the script resolution that turns a `command`
+ * into an on-disk path stays in the caller (it needs the plugin root + fs).
+ */
+/**
+ * One flattened hook registration: a single command bound to an event, with its
+ * optional matcher. The neutral form every hook detector reads — CC-nested and
+ * Codex-flat both collapse to this.
+ */
+export interface HookRegistration {
+    /** The event the hook registers under, e.g. `"PreToolUse"`. */
+    readonly event: string;
+    /** The tool/path matcher, or `null` when the entry declares none. */
+    readonly matcher: string | null;
+    /** The shell command the hook runs (non-empty). */
+    readonly command: string;
+}
+/**
+ * Parse the raw `settings.hooks` value into typed registrations. Returns `[]`
+ * for any non-object / malformed input — never throws.
+ */
+export declare function normalizeHooks(raw: unknown): HookRegistration[];
+/** Distinct event names present in the raw hooks object (object-keyed shape). */
+export declare function hookEventNames(raw: unknown): string[];
+//# sourceMappingURL=hook-normalize.d.ts.map

package/dist/core/hook-normalize.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * vigiles — hook settings normalization (the typed boundary for shipped hooks).
+ *
+ * A repo's hooks ship as raw, untrusted, parsed JSON/TOML — `unknown` at the
+ * loader edge (`LoadedPlugin.settings.hooks`). Rather than have every detector
+ * re-walk that `unknown` with inline casts (parse-don't-validate violated N
+ * times), this parses it ONCE at the boundary into a typed, flattened
+ * `HookRegistration[]` that the walkers consume.
+ *
+ * HARNESS-AGNOSTIC BY TOLERANCE, NOT BY A PORT. Two shipping shapes exist:
+ *   - Claude Code (JSON):  `{ Event: [{ matcher, hooks: [{ command }] }] }`
+ *   - Codex (TOML):        `{ Event: [{ command }] }`  (`[[hooks.Event]] command=…`)
+ * A single tolerant reader absorbs both — a missing `hooks` array means the
+ * entry itself is the lone command holder. The difference is small enough that
+ * one parser covers it, so we deliberately DON'T add a per-harness port for it
+ * (rule-of-three / YAGNI: design the neutral shape first, defer the abstraction
+ * until a harness needs a genuinely divergent shape). If one ever does, this is
+ * the single seam to lift behind the layout/dialect.
+ *
+ * Pure + fully testable (no IO); the script resolution that turns a `command`
+ * into an on-disk path stays in the caller (it needs the plugin root + fs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeHooks = normalizeHooks;
+exports.hookEventNames = hookEventNames;
+/** True for a non-null, non-array object. */
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** The string `matcher` of an entry, or `null` when absent/empty. */
+function entryMatcher(entry) {
+    const m = entry.matcher;
+    return typeof m === "string" && m.length > 0 ? m : null;
+}
+/**
+ * Flatten ONE `{ event: [...] }` group's entry into registrations. Tolerant of
+ * both shapes: a Claude Code entry nests `hooks: [{command}]`; a Codex flat
+ * entry IS the command holder (no `hooks` array), so the entry stands in for it.
+ */
+function flattenEntry(event, entry) {
+    if (!isRecord(entry))
+        return [];
+    const matcher = entryMatcher(entry);
+    const nested = entry.hooks;
+    const holders = Array.isArray(nested) ? nested : [entry];
+    const out = [];
+    for (const h of holders) {
+        if (!isRecord(h))
+            continue;
+        const command = h.command;
+        if (typeof command !== "string" || command.length === 0)
+            continue;
+        out.push({ event, matcher, command });
+    }
+    return out;
+}
+/**
+ * Parse the raw `settings.hooks` value into typed registrations. Returns `[]`
+ * for any non-object / malformed input — never throws.
+ */
+function normalizeHooks(raw) {
+    if (!isRecord(raw))
+        return [];
+    const out = [];
+    for (const [event, arr] of Object.entries(raw)) {
+        if (!Array.isArray(arr))
+            continue;
+        for (const entry of arr)
+            out.push(...flattenEntry(event, entry));
+    }
+    return out;
+}
+/** Distinct event names present in the raw hooks object (object-keyed shape). */
+function hookEventNames(raw) {
+    return isRecord(raw) ? Object.keys(raw) : [];
+}
+//# sourceMappingURL=hook-normalize.js.map