vigiles 26.0.1 → 26.2.0

package/dist/core/hook-matcher.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hookMatcherIssues = hookMatcherIssues;
+exports.hookMatcherReach = hookMatcherReach;
 const tool_contract_js_1 = require("./tool-contract.js");
 const mcp_tool_js_1 = require("./mcp-tool.js");
 // ---------------------------------------------------------------------------
@@ -32,8 +33,31 @@ const REAL_SHAPE_PROBES = [
 ];
 /** The widest correct MCP matcher — what a too-narrow one should become. */
 const WIDE_MCP_MATCHER = "mcp__.*__.*";
-/** Match-all matchers the harness special-cases (and `*` isn't even a regex). */
-const MATCH_ALL = new Set(["", "*", "**", ".*"]);
+/**
+ * Match-all matchers the harness special-cases (and `*` isn't even a regex).
+ *
+ * 🔴 MEASURED, AND `**` IS NOT ONE OF THEM. It sat in this set on no evidence
+ * while the table at the top of this file — the measured one — never listed it.
+ * Against a real `claude` 2.1.263, one hook per run, marker file as the oracle,
+ * 3 runs of each:
+ *
+ * | matcher | a `Bash` call | fired |
+ * | ------- | ------------- | ----- |
+ * | `*`     | `Bash`        | yes   |
+ * | `.*`    | `Bash`        | yes   |
+ * | `""`    | `Bash`        | yes   |
+ * | `**`    | `Bash`        | NO    |
+ *
+ * The direction of that mistake is the expensive one: believing `**` selects
+ * everything makes a guard registered under it come back "measured, allows
+ * 0/7" — an ACCUSATION that a repo's guard let seven disasters through, when
+ * the harness never invoked it once. The mirror image of scoring a hook that
+ * could not start. `**` now falls through to the regex path, where it does not
+ * compile, and both the sweep and the `hook-matcher` rule report a hook that
+ * never fires. Pinned by `src/hook-matcher-delivery.test.ts` so the day Claude
+ * Code starts honouring it, the claim goes red instead of quietly rotting.
+ */
+const MATCH_ALL = new Set(["", "*", ".*"]);
 /** Cap on segments harvested from a matcher — bounds the probe corpus. */
 const MAX_DERIVED_SEGMENTS = 4;
 // ---------------------------------------------------------------------------
@@ -293,4 +317,55 @@ function hookMatcherIssues(entries, declaredServers, dialect) {
     }
     return findings;
 }
+/**
+ * Would this matcher select a call to `tool` — i.e. does the harness spawn the
+ * hook at all?
+ *
+ * The same two MEASURED facts the module header pins, asked as a question rather
+ * than as a defect: on a harness whose matchers are tool names (Claude Code), a
+ * matcher with no regex metacharacter is compared by string EQUALITY and one
+ * with metacharacters is an UNANCHORED regex. It lives here and not in the
+ * caller so those semantics have one home (one-detector-no-drift) —
+ * `hookMatcherIssues` judges a matcher, this one applies it.
+ *
+ * FAIL-OPEN WHERE THE HARNESS IS, AND NOT ONE STEP FURTHER. An absent matcher or
+ * a match-all really does select every tool, so answering `"selects"` there
+ * states a fact — the same direction `decideHookCondition`
+ * (`core/hook-condition.ts`) fails open, and for the same reason it gives: where
+ * Claude Code cannot tell, it RUNS the hook, so mirroring it can only ever add a
+ * run, never invent a skip.
+ *
+ * 🔴 THAT REASONING DOES NOT REACH AN UNCOMPILABLE MATCHER, and this function
+ * used to apply it there anyway. `Bash(` is what the `invalid-regex` finding
+ * above already reports as "the harness can't compile it, so the hook never
+ * fires" — the harness fails CLOSED. Answering `"selects"` therefore does not
+ * add a run the harness makes, it MANUFACTURES one: a caller feeds the hook a
+ * battery it would never have been handed, and an unconditional-deny body scores
+ * a full pass for a hook that cannot run. That is the false-confidence class
+ * this module exists to remove, so an uncompilable matcher gets its own answer
+ * and the caller declines to score it.
+ *
+ * @param matcher - the registration's matcher, or `null` when it declares none.
+ * @param tool - the tool named by the call, e.g. `"Bash"`.
+ * @param style - the active harness's `HookProtocol.matcherStyle`. `"exact"`
+ *   (the default, Claude Code) applies the literal-equality rule above;
+ *   `"regex"` (Codex) compiles EVERY matcher, so `ash` matches `Bash` and the
+ *   glob spellings `*` / `**` — which are Claude Code's documented match-all,
+ *   not regexes — come back `"uncompilable"` rather than being assumed to be
+ *   special-cased by a harness nobody measured.
+ */
+function hookMatcherReach(matcher, tool, style = "exact") {
+    if (matcher === null || matcher === "")
+        return "selects";
+    if (style === "exact") {
+        if (MATCH_ALL.has(matcher))
+            return "selects";
+        if (isLiteralMatcher(matcher))
+            return matcher === tool ? "selects" : "misses";
+    }
+    const re = compileMatcher(matcher);
+    if (re === null)
+        return "uncompilable";
+    return re.test(tool) ? "selects" : "misses";
+}
 //# sourceMappingURL=hook-matcher.js.map

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

@@ -32,12 +32,63 @@ export interface HookRegistration {
     readonly matcher: string | null;
     /** The shell command the hook runs (non-empty). */
     readonly command: string;
+    /**
+     * The hook's CONDITION as written — Claude Code's `if`, a permission-rule
+     * pattern like `"Bash(git push *--force*)"` — or `null` when unconditional.
+     *
+     * 🔴 THIS FIELD WAS SILENTLY DROPPED, and that was half a real defect. Everything
+     * downstream reads registrations, so a key this boundary discards is a key the
+     * whole tool is blind to: a published guard whose body denies unconditionally
+     * but whose `if` only ever fires on a force push was reported by
+     * `verifyGuardrail` as blocking `rm -rf /` and `cat ~/.ssh/id_rsa` too. Carrying
+     * it is parse-don't-validate doing its job — read once, here, not re-walked (or
+     * forgotten) per detector. See `core/hook-condition.ts`.
+     *
+     * The KEY is read tolerantly like `matcher`/`command`, per this module's
+     * documented no-port stance; the harness that spells it and the semantics that
+     * evaluate it live on `HookProtocol.condition`, and a test binds the two so the
+     * spelling cannot drift.
+     */
+    readonly condition: string | null;
 }
 /**
  * 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[];
+/**
+ * A declared hook action that carries no command — `prompt`, `http`, `mcp_tool`
+ * or `agent`. Real, supported actions; simply not shell processes, so no tier
+ * that drives a shell can measure one.
+ */
+export interface NonCommandHookAction {
+    /** The event it registers under. */
+    readonly event: string;
+    /** The tool/path matcher of the entry it sits in, or `null`. */
+    readonly matcher: string | null;
+    /** Its declared `type`, e.g. `"prompt"`. Never `"command"`. */
+    readonly type: string;
+}
+/**
+ * The declared actions {@link normalizeHooks} does NOT return, and why anyone
+ * should care.
+ *
+ * 🔴 SILENCE HERE READ AS "NO HOOKS DECLARED", which is the exact false-empty a
+ * guard sweep exists to prevent. Claude Code supports five action types
+ * (command / http / mcp_tool / prompt / agent) and `normalizeHooks` keeps only
+ * the first, correctly — the others are not shell processes and nothing that
+ * spawns a shell can drive them. But a repository whose PreToolUse hooks are all
+ * `prompt` actions then produced an empty registration list, and a caller that
+ * reads only the length cannot tell "this repo declared no guards" from "this
+ * repo declared four guards I cannot run". The first is an accusation; the
+ * second is a limit of the tier. So the dropped actions are RETURNED rather than
+ * discarded, and the caller reports them as declared-but-not-measured.
+ *
+ * A holder counts only when it declares a `type` that is not `"command"`. An
+ * entry with neither a type nor a command is malformed config, not an action,
+ * and calling it one would invent a hook the repository never declared.
+ */
+export declare function nonCommandHookActions(raw: unknown): NonCommandHookAction[];
 /** 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

@@ -23,7 +23,18 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeHooks = normalizeHooks;
+exports.nonCommandHookActions = nonCommandHookActions;
 exports.hookEventNames = hookEventNames;
+/**
+ * The config key a hook's condition is written under. Read here rather than from
+ * the port for the same reason `matcher` and `command` are: this reader is
+ * harness-agnostic BY TOLERANCE (see the module header), and one shared spelling
+ * is cheaper than threading a port through every caller. `hook-condition.test.ts`
+ * asserts it equals `claudeCodeHookCondition.field`, so a rename fails a test
+ * instead of quietly reading nothing. The day a harness spells it differently,
+ * this constant is the single seam to lift behind the port.
+ */
+const CONDITION_KEY = "if";
 /** True for a non-null, non-array object. */
 function isRecord(v) {
     return v !== null && typeof v === "object" && !Array.isArray(v);
@@ -51,7 +62,12 @@ function flattenEntry(event, entry) {
         const command = h.command;
         if (typeof command !== "string" || command.length === 0)
             continue;
-        out.push({ event, matcher, command });
+        // The condition may sit on the ACTION (Claude Code's nested shape) or, for a
+        // flat entry, on the entry itself — which is the same object, so one read
+        // covers both without a second branch.
+        const raw = h[CONDITION_KEY];
+        const condition = typeof raw === "string" && raw.trim().length > 0 ? raw : null;
+        out.push({ event, matcher, command, condition });
     }
     return out;
 }
@@ -71,6 +87,50 @@ function normalizeHooks(raw) {
     }
     return out;
 }
+/**
+ * The declared actions {@link normalizeHooks} does NOT return, and why anyone
+ * should care.
+ *
+ * 🔴 SILENCE HERE READ AS "NO HOOKS DECLARED", which is the exact false-empty a
+ * guard sweep exists to prevent. Claude Code supports five action types
+ * (command / http / mcp_tool / prompt / agent) and `normalizeHooks` keeps only
+ * the first, correctly — the others are not shell processes and nothing that
+ * spawns a shell can drive them. But a repository whose PreToolUse hooks are all
+ * `prompt` actions then produced an empty registration list, and a caller that
+ * reads only the length cannot tell "this repo declared no guards" from "this
+ * repo declared four guards I cannot run". The first is an accusation; the
+ * second is a limit of the tier. So the dropped actions are RETURNED rather than
+ * discarded, and the caller reports them as declared-but-not-measured.
+ *
+ * A holder counts only when it declares a `type` that is not `"command"`. An
+ * entry with neither a type nor a command is malformed config, not an action,
+ * and calling it one would invent a hook the repository never declared.
+ */
+function nonCommandHookActions(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) {
+            if (!isRecord(entry))
+                continue;
+            const matcher = entryMatcher(entry);
+            const nested = entry.hooks;
+            const holders = Array.isArray(nested) ? nested : [entry];
+            for (const h of holders) {
+                if (!isRecord(h))
+                    continue;
+                const type = h.type;
+                if (typeof type !== "string" || type === "" || type === "command")
+                    continue;
+                out.push({ event, matcher, type });
+            }
+        }
+    }
+    return out;
+}
 /** Distinct event names present in the raw hooks object (object-keyed shape). */
 function hookEventNames(raw) {
     return isRecord(raw) ? Object.keys(raw) : [];

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

@@ -26,7 +26,9 @@
  * Pure core, harness-neutral. HONEST SCOPE (kept in every doc): compile/verify fix
  * the hook's AUTHORING + LOGIC, not the harness's DELIVERY. #34692 (a subagent's
  * calls never reaching PreToolUse) is FIXED as of CC 2.1.241 — measured on a stock
- * install, pinned by src/subagent-delivery.test.ts. A gate is STILL a strong default
+ * install, pinned by src/subagent-delivery.test.ts. SCOPE of that measurement:
+ * headless `claude -p` only — interactive is unmeasured, and depth-2 subagent
+ * nesting does not occur there at all. A gate is STILL a strong default
  * rather than an unbypassable wall, because a model can route around a tool
  * entirely (#45427 / #32376). Limits (buy-in, node-startup latency) +
  * full record in research/hook-pain-points.md.
@@ -120,6 +122,65 @@ export type GateAction = {
  * Pure, so a test asserts "in observe mode this deny does NOT block" with no process.
  */
 export declare function gateAction(decision: Decision, mode?: HookMode): GateAction;
+/**
+ * WHERE A REACT'S `notice` CAN ACTUALLY ARRIVE — the react-side twin of
+ * {@link gateAction}, and pure for the same reason: the runtime and a test must
+ * agree about delivery without either of them running a harness.
+ *
+ * 🔴 THE DEFECT THIS EXISTS TO CLOSE, MEASURED 2026-09-07 BY THIS REPO'S OWN
+ * FIRST COMPILED HOOK. `notice(…)` was written to stderr and nothing else. Per
+ * Claude Code's hooks documentation, stderr from a hook that exits 0 "goes to
+ * the debug log only, never the transcript, and Claude never sees it" — and a
+ * react ALWAYS exits 0, because its type has no `deny`. So a notice reached
+ * NOBODY: not the model, not the user, not the transcript. `docs/compiled-hooks.md`
+ * stated the MECHANIC ("notice writes to stderr") and never the CONSEQUENCE, so
+ * the role looked healthy while delivering nowhere — precisely the
+ * false-confidence class compiled hooks exist to eliminate, inside the
+ * implementation of compiled hooks.
+ *
+ * The fix is the mechanism the shipped nudges already use:
+ * `hookSpecificOutput.additionalContext` on STDOUT. Two candidates were
+ * considered and one is a trap:
+ *
+ * - **exit 2.** The host's per-event table does show `PostToolUse` stderr to the
+ *   model on exit 2. But {@link HookProtocol.blockExitCode} IS 2 — it is the
+ *   DENY channel. Spending it on a role whose type-level guarantee is "can never
+ *   block" would make that guarantee a lie on every other event. Rejected.
+ * - **`additionalContext`.** Already proven on this event by the shipped refs
+ *   nudge, shape shared across harnesses, and the per-harness half is exactly
+ *   {@link HookProtocol.injectableEvents} — a fact the port already carries and
+ *   the conformance kit already checks. Chosen.
+ *
+ * `injectableEvents` is INJECTED rather than read from a Claude Code literal, so
+ * this stays harness-agnostic (`core ⊄ adapter`): a Codex react on `PostToolUse`
+ * is delivered by the same code path, and an event neither harness injects is
+ * reported `undeliverable` rather than silently dropped.
+ */
+export type NoticeDelivery = 
+/** The notice can reach the agent as injected context on this event. */
+{
+    readonly kind: "inject";
+    readonly context: string;
+}
+/**
+ * A notice on an event this harness does NOT inject. It still goes to stderr
+ * (the debug log), but nothing surfaces it — so the CALLER must say so out
+ * loud rather than treat this as success. Carrying the message means the
+ * caller never has to re-derive which reaction it was talking about.
+ */
+ | {
+    readonly kind: "undeliverable";
+    readonly message: string;
+}
+/** Not a notice (a `run` or `nothing`) — nothing to deliver. */
+ | {
+    readonly kind: "none";
+};
+/**
+ * Decide how a {@link Reaction}'s notice reaches the agent on `on`, given the
+ * events this harness injects. Pure — no I/O, no process, no harness literal.
+ */
+export declare function noticeDelivery(reaction: Reaction, on: string, injectableEvents: readonly string[]): NoticeDelivery;
 /** An AST-backed view of a Bash command — the author never writes a regex. */
 export interface CommandView {
     readonly raw: string;

package/dist/core/hook-program.js

@@ -4,6 +4,7 @@ exports.nothing = exports.notice = exports.run = exports.inject = exports.tools
 exports.matchesTool = matchesTool;
 exports.invalidToolPatterns = invalidToolPatterns;
 exports.gateAction = gateAction;
+exports.noticeDelivery = noticeDelivery;
 exports.trimTrailingSeparators = trimTrailingSeparators;
 exports.commandView = commandView;
 exports.experimental_defineHook = experimental_defineHook;
@@ -66,7 +67,9 @@ exports.isLoadPathRepairEvent = isLoadPathRepairEvent;
  * Pure core, harness-neutral. HONEST SCOPE (kept in every doc): compile/verify fix
  * the hook's AUTHORING + LOGIC, not the harness's DELIVERY. #34692 (a subagent's
  * calls never reaching PreToolUse) is FIXED as of CC 2.1.241 — measured on a stock
- * install, pinned by src/subagent-delivery.test.ts. A gate is STILL a strong default
+ * install, pinned by src/subagent-delivery.test.ts. SCOPE of that measurement:
+ * headless `claude -p` only — interactive is unmeasured, and depth-2 subagent
+ * nesting does not occur there at all. A gate is STILL a strong default
  * rather than an unbypassable wall, because a model can route around a tool
  * entirely (#45427 / #32376). Limits (buy-in, node-startup latency) +
  * full record in research/hook-pain-points.md.
@@ -168,6 +171,17 @@ function gateAction(decision, mode = "enforce") {
             return (0, hash_js_1.assertNever)(decision);
     }
 }
+/**
+ * Decide how a {@link Reaction}'s notice reaches the agent on `on`, given the
+ * events this harness injects. Pure — no I/O, no process, no harness literal.
+ */
+function noticeDelivery(reaction, on, injectableEvents) {
+    if (reaction.kind !== "notice")
+        return { kind: "none" };
+    return injectableEvents.includes(on)
+        ? { kind: "inject", context: reaction.message }
+        : { kind: "undeliverable", message: reaction.message };
+}
 const FORCE_FLAG = /^-(?:-force$|[a-z]*f[a-z]*$)/;
 const hasForce = (argv) => argv.some((a) => FORCE_FLAG.test(a));
 const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);

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

@@ -12,6 +12,7 @@
  * The Claude Code implementation is `claudeCodeHookProtocol` in
  * `src/adapters/claude-code/hook-protocol.ts`.
  */
+import type { HookConditionSupport } from "./hook-condition.js";
 export interface HookProtocol {
     /** Stable identifier, e.g. "claude-code". */
     readonly name: string;
@@ -60,5 +61,20 @@ export interface HookProtocol {
      * by `decideHook`; absent ⇒ no field halts the turn on this harness.
      */
     readonly haltsTurnField?: string;
+    /**
+     * How this harness decides whether a hook that declares a CONDITION runs at all
+     * — Claude Code's per-action `if` field. Optional (additive, non-breaking);
+     * absent ⇒ the harness has no such feature and every hook is unconditional,
+     * which is what every consumer got before this existed.
+     *
+     * 🔴 IT IS A PORT FIELD BECAUSE THE SYNTAX IS THE HARNESS'S, NOT BECAUSE THE
+     * IDEA IS. "A hook may only run on matching calls" is neutral and modelled in
+     * `core/hook-condition.ts`; `"Bash(git push *--force*)"` is Claude Code's
+     * permission-rule grammar, so the matcher lives in its adapter. Reading it here
+     * is what stops `verifyGuardrail` reporting a conditional guard as blocking
+     * things its condition means it never sees — see `core/hook-condition.ts` for
+     * the measured false green that put this field on the port.
+     */
+    readonly condition?: HookConditionSupport;
 }
 //# sourceMappingURL=hook-protocol.d.ts.map

package/dist/core/linters.js

@@ -655,37 +655,104 @@ const stylelintConfigEnabled = createCachedChecker((basePath) => {
         return null;
     }
 });
-const ruffConfigEnabled = createCachedChecker((basePath) => {
+/**
+ * Ask ruff which rule codes are enabled for `basePath`, or null when it could
+ * not be asked. THE ONE place any ruff settings probe is spelled — the three
+ * call sites (config-state, catalog enumeration, discovery) used to each carry
+ * their own copy of the command and the parse, and each copy carried the same
+ * bug.
+ *
+ * WHY the argument is a DIRECTORY and never a filename: all three call sites
+ * passed a synthesized `<basePath>/dummy.py`. `ruff check` walks the path it is
+ * given, so a filename that does not exist makes it exit 2 with "No files found
+ * under the given path" — on every repository that does not happen to contain a
+ * file called `dummy.py`, which is every real repository. Measured 2026-09-06:
+ * with the synthesized path the enabled set came back empty and every
+ * `enforce("ruff/...")` reported `enabled: "unknown"`; `touch dummy.py` in the
+ * same repo flipped the identical rule to "enabled" and an out-of-select rule
+ * to "disabled". The failure was SILENT because only "disabled" is ever
+ * surfaced as a finding (src/core/compile.ts, src/cli.ts) — "unknown" reads as
+ * clean, so a genuinely disabled rule passed its check.
+ *
+ * A directory works where a synthesized filename does not, including the case
+ * the filename was invented for: a project with NO Python files at all still
+ * resolves its settings (measured: a directory holding only a ruff config
+ * reports its full enabled set).
+ */
+function ruffEnabledCodes(basePath, timeoutMs) {
+    let output;
     try {
-        const dummyPath = (0, node_path_1.resolve)(basePath, "dummy.py");
-        const output = (0, node_child_process_1.execSync)(`ruff check --show-settings ${dummyPath}`, {
+        output = (0, node_child_process_1.execSync)("ruff check --show-settings .", {
             encoding: "utf-8",
             cwd: basePath,
             stdio: ["pipe", "pipe", "pipe"],
-            timeout: 10000,
+            ...(timeoutMs === undefined ? {} : { timeout: timeoutMs }),
         });
-        const enabledMatch = output.match(/linter\.rules\.enabled\s*=\s*\[([\s\S]*?)\]/);
-        const enabledCodes = new Set();
-        if (enabledMatch?.[1]) {
-            const codeRe = /\(([A-Z]+\d*)\)/g;
-            let m;
-            while ((m = codeRe.exec(enabledMatch[1])) !== null) {
-                enabledCodes.add(m[1]);
-            }
+    }
+    catch (e) {
+        // Two failures wear the same catch, and only ONE of them is legitimate
+        // silence. ruff not being installed (127 / ENOENT) means this project has
+        // no ruff to consult — nothing to report. Anything else means ruff RAN and
+        // REFUSED, and a caller that turns that into "unknown" is reporting a
+        // verified-clean result it never verified. That one gets said out loud.
+        const err = e;
+        if (err.status !== 127 && err.code !== "ENOENT") {
+            warnRuffUnreadable(basePath, firstLines(err.stderr));
         }
-        return (ruleName) => {
-            if (enabledCodes.has(ruleName))
-                return "enabled";
-            for (const code of enabledCodes) {
-                if (code.startsWith(ruleName))
-                    return "enabled";
-            }
-            return "disabled";
-        };
+        return null;
     }
-    catch {
+    const enabledMatch = output.match(/linter\.rules\.enabled\s*=\s*\[([\s\S]*?)\]/);
+    if (!enabledMatch?.[1]) {
+        // ruff succeeded but its output does not carry the block we parse (a
+        // format change upstream). Same reasoning as above: unreadable is not clean.
+        warnRuffUnreadable(basePath, "no linter.rules.enabled block in output");
         return null;
     }
+    const codes = new Set();
+    const codeRe = /\(([A-Z]+\d*)\)/g;
+    let m;
+    while ((m = codeRe.exec(enabledMatch[1])) !== null) {
+        codes.add(m[1]);
+    }
+    return codes;
+}
+function firstLines(stderr) {
+    // execSync hands stderr back as a string or a Buffer depending on `encoding`.
+    // Anything else is stringified as "[object Object]", which would put noise
+    // into a message whose whole job is to name the cause — so it becomes "".
+    let text = "";
+    if (typeof stderr === "string")
+        text = stderr;
+    else if (Buffer.isBuffer(stderr))
+        text = stderr.toString("utf-8");
+    return text.trim().split("\n").slice(0, 2).join(" — ").trim();
+}
+/**
+ * Loud, but once per basePath. A warning that repeats per rule would be noise,
+ * and noise is how a real signal gets muted.
+ */
+const ruffWarned = new Set();
+function warnRuffUnreadable(basePath, detail) {
+    if (ruffWarned.has(basePath))
+        return;
+    ruffWarned.add(basePath);
+    console.warn(`⚠ ruff could not report its settings in ${basePath}` +
+        (detail ? `: ${detail}` : "") +
+        `. Every ruff/* rule is UNKNOWN here — not verified, and not clean.`);
+}
+const ruffConfigEnabled = createCachedChecker((basePath) => {
+    const enabledCodes = ruffEnabledCodes(basePath, 10000);
+    if (!enabledCodes)
+        return null;
+    return (ruleName) => {
+        if (enabledCodes.has(ruleName))
+            return "enabled";
+        for (const code of enabledCodes) {
+            if (code.startsWith(ruleName))
+                return "enabled";
+        }
+        return "disabled";
+    };
 });
 const pylintConfigEnabled = createCachedChecker((basePath) => {
     try {
@@ -874,24 +941,11 @@ function cachedByBasePath(fn) {
         return rules;
     };
 }
-const enumerateRuffRules = cachedByBasePath((basePath) => {
-    const rules = new Set();
-    try {
-        const output = (0, node_child_process_1.execSync)(`ruff check --show-settings ${(0, node_path_1.resolve)(basePath, "dummy.py")}`, { encoding: "utf-8", cwd: basePath, stdio: ["pipe", "pipe", "pipe"] });
-        const enabledMatch = output.match(/linter\.rules\.enabled\s*=\s*\[([\s\S]*?)\]/);
-        if (enabledMatch?.[1]) {
-            const codeRe = /\(([A-Z]+\d*)\)/g;
-            let m;
-            while ((m = codeRe.exec(enabledMatch[1])) !== null) {
-                rules.add(m[1]);
-            }
-        }
-    }
-    catch {
-        // CLI failed — return empty set, caller will just skip suggestions
-    }
-    return rules;
-});
+const enumerateRuffRules = cachedByBasePath(
+// An unreadable settings probe yields an EMPTY suggestion catalog, which is
+// the same shape as "ruff enables nothing" — so the reason is reported by
+// ruffEnabledCodes rather than swallowed here.
+(basePath) => ruffEnabledCodes(basePath) ?? new Set());
 const enumeratePylintRules = cachedByBasePath((basePath) => {
     const rules = new Set();
     try {
@@ -1260,25 +1314,10 @@ function discoverRuffRules(basePath) {
         if (!hasRuffConfig(basePath))
             return null;
         (0, node_child_process_1.execSync)("which ruff", { stdio: "ignore" });
-        const dummyPath = (0, node_path_1.resolve)(basePath, "dummy.py");
-        const output = (0, node_child_process_1.execSync)(`ruff check --show-settings ${dummyPath}`, {
-            encoding: "utf-8",
-            cwd: basePath,
-            stdio: ["pipe", "pipe", "pipe"],
-            timeout: 10000,
-        });
-        const enabledMatch = output.match(/linter\.rules\.enabled\s*=\s*\[([\s\S]*?)\]/);
-        const rules = [];
-        if (enabledMatch?.[1]) {
-            const codeRe = /\(([A-Z]+\d*)\)/g;
-            let m;
-            while ((m = codeRe.exec(enabledMatch[1])) !== null) {
-                rules.push(m[1]);
-            }
-        }
-        if (rules.length === 0)
+        const codes = ruffEnabledCodes(basePath, 10000);
+        if (!codes || codes.size === 0)
             return null;
-        return { linter: "ruff", rules, via: "CLI" };
+        return { linter: "ruff", rules: [...codes], via: "CLI" };
     }
     catch {
         return null;

package/dist/core/shell-vars.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Which environment variables a shell command actually DEPENDS ON — the
+ * parser-backed answer to "would this command run the same program here?".
+ *
+ * 🔴 WHY A PARSER AND NOT A REGEX, measured. The caller
+ * (`experimental_verifyPluginGuards`) refuses to run a hook whose command names
+ * a variable nothing has set, because running it would measure a different
+ * program than the harness runs. Deciding that with `/\$\{?NAME\}?/` gets two
+ * ordinary shapes wrong, in the direction that costs a measurement:
+ *
+ * | command                          | the shell            | a raw regex   |
+ * | -------------------------------- | -------------------- | ------------- |
+ * | `GUARD=hooks/g.sh; "$GUARD"`     | sets it, then expands| "unset GUARD" |
+ * | `echo '$NOT_A_VAR'`              | no expansion at all  | "unset …"     |
+ *
+ * Both are self-contained commands reported as unresolvable, so a real guard
+ * goes unmeasured for a reason that is not true of it. This is the
+ * `parse-structured-input-with-a-real-parser` rule applied to the same shell
+ * grammar `core/bash-effects.ts` already parses: an ASSIGNMENT and a SINGLE-
+ * QUOTED literal are nodes, so once the command is an AST the two mistakes above
+ * are not expressible.
+ *
+ * 🔴 AND THE PARSER REMOVED TWO WAYS TO BE WRONG WHILE ADDING A THIRD, in the
+ * worse direction. Subtracting every assigned name GLOBALLY excused a read the
+ * assignment never reached, so the sweep ran a differently-configured program
+ * and gave it a score. Measured against `/bin/sh` with the name exported first:
+ *
+ * ```
+ * export X=ambient;   echo "$X"; X=1           → ambient   (read comes FIRST)
+ * export FOO=ambient; FOO=1 sh -c "echo $FOO"  → ambient   (prefix assign does
+ *                                                           not reach its own
+ *                                                           command's words)
+ * (G=inner); printf '[%s]' "$G"                → []        (subshell-scoped)
+ * G=dominates; printf '[%s]' "$G"              → dominates (this one persists)
+ * ```
+ *
+ * So the rule is DOMINANCE, not membership, and CONTROL FLOW, not source order:
+ * an assignment excuses a read only when it is an unconditional top-level
+ * statement (see {@link persistingAssigns}) AND sits before that read. A prefix,
+ * subshell, function-body, backgrounded, conditional or pipelined assignment
+ * excuses nothing at all. Where dominance is not provable, the read stands.
+ *
+ * It does NOT reach into `bash-effects.ts` for the parse: that module's `sh`
+ * handle and node types are private to it, and its types model EFFECTS
+ * (redirections, wrapper heads, flag tables) rather than expansions. The shared
+ * thing is the dependency, not the code — both `require("mvdan-sh")`.
+ *
+ * CONSERVATIVE, ON PURPOSE, IN ONE DIRECTION. Over-reporting a dependency costs
+ * a hook its measurement (the caller says so and names the variable);
+ * under-reporting one lets a differently-configured program be measured and
+ * scored. So where the parser cannot decide, this reports MORE:
+ *
+ * - a parse failure falls back to the regex scan and says `parsed: false`;
+ * - `${FOO:-default}` and `${FOO:?msg}` count as reads even though the first
+ *   always resolves — reading the expansion operator is a further step, and its
+ *   only effect would be to measure more hooks;
+ * - a `for f in …` loop variable is a read (nothing binds it in the AST the way
+ *   an `Assign` does).
+ *
+ * `$1` / `$@` / `$?` are never reads: they are positional and special
+ * parameters, not environment the caller could set.
+ */
+/** What a command reads from its environment. */
+export interface ShellVarReads {
+    /** Names it expands and does not itself assign, first-seen order. */
+    readonly reads: readonly string[];
+    /**
+     * Whether the shell parser accepted the command. `false` means `reads` came
+     * from the regex fallback and may name a variable the command sets itself.
+     */
+    readonly parsed: boolean;
+}
+export declare function shellVarReads(command: string): ShellVarReads;
+//# sourceMappingURL=shell-vars.d.ts.map