vigiles 26.0.1 → 26.2.0

package/README.md

@@ -182,9 +182,10 @@ A hook that blocks nothing, a skill that hijacks unrelated prompts, context that
 _"Caveman Mode cuts 65% of your tokens." Says who?_ vigiles A/Bs the claim on real coding tasks and hands you three numbers: the **token bill**, whether it hit its **target**, and whether your code still **works**.
 
 ```text
-caveman vs verbose · haiku · $0 on your subscription
-  output tokens   762 → 842   (+11% — the "saving" reversed)
-  correctness     1.0 → 1.0   (the fact survived)
+caveman vs baseline · sonnet · 7 tasks × 5 trials · $0 on your subscription
+  output tokens   6% lower on average   (the claim was 65% — and it GREW on 2 of 7 tasks)
+  bill            $0.5396 → $0.5334     (flat — output is only ~20% of the cost)
+  correctness     1.0 → 1.0             (nothing broke)
 ```
 
 Point it at any harness change that claims a number — does a compression skill pay for itself, is a subagent worth its cost, which model is cheapest here. promptfoo and DeepEval bill **per token, every run**; vigiles runs on your own Claude Pro/Max subscription, so you measure on every change, not once. A committed lock file (like `package-lock`) keeps CI honest without re-calling the model. (Claude Code today; Codex landing.)
@@ -268,7 +269,7 @@ Targets Claude Code and Codex out of the box, or [your own harness](docs/authori
 > signal you need to look for, since it is on every call site rather than on an
 > import line you scrolled past. See [Stability](STABILITY.md).
 
-**Project** — [Stability](STABILITY.md) · [Related tools](docs/comparison.md#what-vigiles-composes-with) · ships as an [Agent Plugins](https://agent-plugins.org) 1.0.0 plugin ([how to do the same](docs/for-plugin-authors.md#6-ship-it-in-the-portable-agent-plugins-format))
+**Project** — [Stability](STABILITY.md) · [Contributing](CONTRIBUTING.md) · [Related tools](docs/comparison.md#what-vigiles-composes-with) · ships as an [Agent Plugins](https://agent-plugins.org) 1.0.0 plugin ([how to do the same](docs/for-plugin-authors.md#6-ship-it-in-the-portable-agent-plugins-format))
 
 <!-- The "companion to [Feedback Loop Is All You Need](https://zernie.com/blog/feedback-loop-is-all-you-need)"
      link is temporarily removed while AgenticDev paper #1 is under blind review: repo → blog is a

package/dist/adapters/claude-code/hook-condition.d.ts

@@ -0,0 +1,46 @@
+/**
+ * claudeCodeHookCondition — Claude Code's hook `if` field, evaluated.
+ *
+ * A CC hook action may carry `if: "Bash(git push *--force*)"`. The hook command
+ * runs ONLY when the tool call matches; otherwise it is never spawned. The syntax
+ * is CC's permission-rule grammar, which is why this lives in the adapter and not
+ * in core. Reached through `HookProtocol.condition`; the neutral shape and the
+ * event rule live in `src/core/hook-condition.ts`.
+ *
+ * SOURCE OF THE SEMANTICS. Every rule below is transcribed from Claude Code's own
+ * hooks documentation (the `if` row of the common-fields table + its "Bash if
+ * matching" table) and cross-checked against the installed binary, whose bundled
+ * schema carries the string verbatim: "Permission rule syntax to filter when this
+ * hook runs (e.g., \"Bash(git *)\"). Only runs if the tool call matches the
+ * pattern. Avoids spawning hooks for non-matching commands." Measured on
+ * @anthropic-ai/claude-code 2.1.263.
+ *
+ * 🔴 THE MATCHER IS DELIBERATELY CONSERVATIVE IN ONE DIRECTION ONLY, and that is
+ * the whole safety argument. CC itself fails OPEN — where it cannot tell what a
+ * command name expands to, it runs the hook — so mirroring that means every
+ * uncertain input yields `runs: true`. A wrong answer can therefore only ever
+ * make a guardrail report say "this hook ran and did not block", never "this hook
+ * was skipped". The first is a real finding about the hook; the second would be a
+ * false alarm invented by us, and this file must not be able to produce one.
+ *
+ * THE SEVEN DOCUMENTED BASH CASES, all pinned in hook-condition.test.ts:
+ *
+ *   | pattern            | command                     | runs | why                                  |
+ *   | ------------------ | --------------------------- | ---- | ------------------------------------ |
+ *   | `Bash(git *)`      | `FOO=bar git push`          | yes  | leading assignments stripped         |
+ *   | `Bash(git *)`      | `npm test && git push`      | yes  | each subcommand is checked           |
+ *   | `Bash(rm *)`       | `echo $(rm -rf /)`          | yes  | commands inside `$()`/`` ` `` too    |
+ *   | `Bash(rm *)`       | `echo $(date)`              | no   | no subcommand matches                |
+ *   | `Bash(cat *)`      | `echo before $(date) after` | no   | full command and `date` both checked |
+ *   | `Bash(git *)`      | `$TOOL git push`            | yes  | the command name is unknowable       |
+ *   | `Bash(git push *)` | `echo $(date)`              | yes  | argument-bearing pattern + dynamic   |
+ *
+ * The last two rows are the fail-open half, and they are why a blanket "contains a
+ * `$` ⇒ run" shortcut is wrong: rows 4 and 5 also contain `$(` and must say NO.
+ * CC resolves command NAMES through substitution (it can see `date`, `rm`) but not
+ * ARGUMENTS, so a command-name-only pattern (`rm *`) is decided precisely while an
+ * argument-bearing one (`git push *`) gives up on any dynamic command.
+ */
+import type { HookConditionSupport } from "../../core/hook-condition.js";
+export declare const claudeCodeHookCondition: HookConditionSupport;
+//# sourceMappingURL=hook-condition.d.ts.map

package/dist/adapters/claude-code/hook-condition.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeHookCondition = void 0;
+const bash_effects_js_1 = require("../../core/bash-effects.js");
+/** The events Claude Code evaluates `if` on. On any other, a hook with `if` never runs. */
+const EVALUATED_ON = [
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "PermissionDenied",
+];
+/**
+ * Parse `Tool(pattern)` / `Tool`. Returns `null` on anything else, which the
+ * caller treats as "cannot decide" ⇒ run the hook.
+ */
+function parseRule(condition) {
+    const text = condition.trim();
+    if (text === "")
+        return null;
+    const open = text.indexOf("(");
+    if (open === -1)
+        return /^[\w.-]+$/.test(text) ? { tool: text, pattern: null } : null;
+    if (!text.endsWith(")"))
+        return null;
+    const tool = text.slice(0, open).trim();
+    if (!/^[\w.-]+$/.test(tool))
+        return null;
+    return { tool, pattern: text.slice(open + 1, -1) };
+}
+/** A permission-rule glob (`*` is the only metacharacter) as a whole-string regex. */
+function globToRegExp(pattern) {
+    const body = pattern
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[\\s\\S]*");
+    return new RegExp(`^${body}$`);
+}
+/**
+ * Does the pattern constrain more than the command NAME?
+ *
+ * `git *` names only the command; `git push *` and `git push *--force*` constrain
+ * arguments too. The distinction is exactly the documented fail-open boundary:
+ * CC resolves command names through `$()` but not arguments, so only the second
+ * kind gives up on a dynamic command.
+ */
+function specifiesMoreThanCommandName(pattern) {
+    return /\s/.test(pattern.replace(/\*+$/, "").trim());
+}
+/** `$(…)`, a backtick, or a `$VAR`/`${VAR}` expansion — content CC cannot resolve. */
+function hasDynamicContent(command) {
+    return /\$\(|`|\$\{?[A-Za-z_]/.test(command);
+}
+/**
+ * Every spelling of the command a pattern is tried against: the raw string, plus
+ * each leaf command however nested (`&&` chains, pipelines, `$()`, backticks).
+ *
+ * BOTH leaf extractors are used on purpose. `leafCommands` keeps literal words
+ * only; `leafCommandsNormalized` additionally unwraps quotes, so
+ * `git commit -m 'skip hooks'` keeps its quoted operand instead of dropping it.
+ * More candidates can only make a pattern MATCH, which is the fail-open direction.
+ */
+function candidateCommands(command) {
+    const out = new Set([command.trim()]);
+    for (const argv of (0, bash_effects_js_1.leafCommands)(command))
+        out.add(argv.join(" "));
+    for (const leaf of (0, bash_effects_js_1.leafCommandsNormalized)(command))
+        out.add(leaf.argv.join(" "));
+    return [...out];
+}
+/**
+ * True when at least one leaf could not be normalized — in practice a leaf whose
+ * HEAD is a `$VAR`/substitution, so the command name is unknowable. CC runs the
+ * hook in that case (`$TOOL git push` against `Bash(git *)`), so we do too.
+ */
+function hasUnresolvableCommandName(command) {
+    return (0, bash_effects_js_1.leafCommandsNormalized)(command).length < (0, bash_effects_js_1.leafCommands)(command).length;
+}
+function matchBash(pattern, input) {
+    const command = input["command"];
+    if (typeof command !== "string")
+        return { runs: true, why: "no command to match against — hook runs" };
+    const re = globToRegExp(pattern);
+    const hit = candidateCommands(command).find((c) => re.test(c));
+    if (hit !== undefined)
+        return { runs: true, why: `matches \`${pattern}\` via \`${hit}\`` };
+    if (hasUnresolvableCommandName(command))
+        return {
+            runs: true,
+            why: `the command name is an expansion, so \`${pattern}\` cannot be ruled out — hook runs`,
+        };
+    if (specifiesMoreThanCommandName(pattern) && hasDynamicContent(command))
+        return {
+            runs: true,
+            why: `\`${pattern}\` constrains arguments and the command is dynamic — hook runs`,
+        };
+    return {
+        runs: false,
+        why: `does not match \`${pattern}\` — Claude Code would not run this hook`,
+    };
+}
+/** The string inputs a non-Bash pattern (`Edit(*.ts)`) is matched against. */
+const PATH_KEYS = ["file_path", "path", "notebook_path", "pattern"];
+function matchNonBash(pattern, input) {
+    const re = globToRegExp(pattern);
+    const values = PATH_KEYS.map((k) => input[k]).filter((v) => typeof v === "string");
+    if (values.length === 0)
+        return { runs: true, why: "no path input to match against — hook runs" };
+    const hit = values.find((v) => re.test(v));
+    return hit !== undefined
+        ? { runs: true, why: `matches \`${pattern}\` via \`${hit}\`` }
+        : {
+            runs: false,
+            why: `does not match \`${pattern}\` — Claude Code would not run this hook`,
+        };
+}
+exports.claudeCodeHookCondition = {
+    field: "if",
+    evaluatedOn: [...EVALUATED_ON],
+    matches(condition, call) {
+        const rule = parseRule(condition);
+        if (!rule)
+            return {
+                runs: true,
+                why: `\`${condition}\` is not a permission rule we can read — hook runs`,
+            };
+        if (rule.tool !== call.tool)
+            return {
+                runs: false,
+                why: `\`${condition}\` names ${rule.tool}, the call is ${call.tool} — the hook never runs`,
+            };
+        if (rule.pattern === null)
+            return {
+                runs: true,
+                why: `\`${condition}\` matches any ${rule.tool} call`,
+            };
+        return rule.tool === "Bash"
+            ? matchBash(rule.pattern, call.input)
+            : matchNonBash(rule.pattern, call.input);
+    },
+};
+//# sourceMappingURL=hook-condition.js.map

package/dist/adapters/claude-code/hook-protocol.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeCodeHookProtocol = void 0;
+const hook_condition_js_1 = require("./hook-condition.js");
 exports.claudeCodeHookProtocol = {
     name: "claude-code",
     blockExitCode: 2,
@@ -13,5 +14,9 @@ exports.claudeCodeHookProtocol = {
     // injection). Covers vigiles's shipped inject hooks: the SessionStart lint
     // summary and the PostToolUse refs / eval-lock nudges.
     injectableEvents: ["SessionStart", "UserPromptSubmit", "PostToolUse"],
+    // The `if` field: a permission-rule pattern deciding whether the hook is spawned
+    // at all. See ./hook-condition.ts — without it a conditional guard was reported
+    // as blocking every disaster in the battery.
+    condition: hook_condition_js_1.claudeCodeHookCondition,
 };
 //# sourceMappingURL=hook-protocol.js.map