vigiles 27.1.4 → 27.1.6

package/dist/adapters/codex/mock-model.js

@@ -109,6 +109,33 @@ function renderResponsesSSE(text, opts = {}) {
         `data: ${JSON.stringify({ type: e.type, ...e.data })}\n\n`)
         .join("");
 }
+/**
+ * 🔴 KNOWN BLIND SPOT — NARROW ON PURPOSE, AND THAT IS NOT THE SAME AS COMPLETE.
+ * Roadmapped P1 2026-09-10; do not read a `requestContains` miss on a Codex trace
+ * as "not delivered" until this is closed.
+ *
+ * This reads `.text` and nothing else, and its caller takes only the LAST input
+ * item with `role:"user", type:"message"`. Measured against openai@7.13.0:
+ * `ResponseInputItem` has THIRTY-TWO variants and we look at one. The ignored
+ * ones include `FunctionCallOutput`, `ShellCallOutput` and `LocalShellCallOutput`
+ * — the Responses-API analogues of an Anthropic `tool_result`, i.e. exactly where
+ * Claude Code relocated a hook's additionalContext in 2.1.228 and where the same
+ * payload would land here.
+ *
+ * WHY THIS IS A COMMENT AND NOT A FIX. `driver.ts` adapts this into a
+ * `ModelRequest`, so it feeds `requestContains` — the same predicate whose
+ * `.text`-only twin in src/mock-model.ts produced a false "not delivered", a
+ * false issue (zernie/vigiles#231) and a near-miss upstream report. The trap is
+ * armed; nobody has stepped on it only because both delivery harnesses are
+ * Claude-Code-only today. Closing it properly means deciding what `prompt` MEANS
+ * across 32 item types — a semantic change, not a bug fix, and too large to ride
+ * along with the mock-model repair.
+ *
+ * The Claude Code side now takes `ContentBlockParam` from @anthropic-ai/sdk and
+ * fails the BUILD on an unhandled variant (see `flattenBlock` in
+ * src/mock-model.ts). openai ships the matching union under Apache-2.0; applying
+ * the same construction here is the fix, and it is the roadmapped work.
+ */
 function joinInputText(content) {
     if (!Array.isArray(content))
         return "";

package/dist/cli-main.js

@@ -5694,7 +5694,13 @@ async function installHookFile(file, adapter, registeredProviders = []) {
     // appends a duplicate block instead of replacing the existing one.
     const ref = (0, hook_install_js_1.normalizeHookRef)(file);
     const compiled = (0, hook_program_js_1.compileHookProgram)(source, program, {
-        gateCommand: `npx vigiles hook-runtime run-program ${ref}`,
+        // 🔴 ANCHORED AT THE PROJECT ROOT. A hook command does not run with a stable cwd —
+        // this codebase says so twice (`bareToken`'s header, `PluginLayout.projectRootTokens`)
+        // and `projectRootOf` relies on the anchored spelling "by construction", but the
+        // emitter never produced it. Measured 2026-09-10 in a consumer repo: after a compile,
+        // one `cd` into a subdirectory made a PreToolUse gate fail to load, and a gate that
+        // cannot load must block — the repo seized, every command refused including the repair.
+        gateCommand: `npx vigiles hook-runtime run-program ${(0, hook_install_js_1.hookGateRef)(ref, adapter.layout.projectRootTokens)}`,
         dialect: adapter.dialect,
         hookProtocol: adapter.hookProtocol,
         settingsFormat: adapter.layout.settingsFormat,

package/dist/harness-assert.d.ts

@@ -156,7 +156,17 @@ export declare function outputContains(trace: Trace, needle: string | RegExp): b
  * Did ANY request the model received contain `needle` — searching the system
  * prompt and every message across all requests? The predicate that proves
  * injected context *reached the model*: a SessionStart hook's `additionalContext`
- * or a slash command's expansion. Harness tier only — the eval tier drives the
+ * or a slash command's expansion.
+ *
+ * THIS IS A PROJECTION OF THE REQUEST, NOT THE REQUEST — state what it omits
+ * before building a claim on it. Until 2026-09-10 this sentence was false: the
+ * flattener read only `.text`, so the eight `ContentBlockParam` variants that
+ * carry `content` were invisible, and a payload Claude Code had delivered inside
+ * a `tool_result` read as "never arrived" (zernie/vigiles#231, a false finding).
+ * It now covers every block type the pinned SDK union names, and serialises any
+ * it does not. STILL OMITTED BY DESIGN: `tool_use` / `server_tool_use` inputs —
+ * those are what the model SAID, not what it was TOLD, so a needle in a tool
+ * argument must not read as delivery. See `flattenBlock` in mock-model.ts. Harness tier only — the eval tier drives the
  * real API, so its `modelRequests` (and this) is empty. Behind `assertRequestContains`.
  */
 export declare function requestContains(trace: Trace, needle: string | RegExp): boolean;

package/dist/harness-assert.js

@@ -423,7 +423,17 @@ function requestText(trace) {
  * Did ANY request the model received contain `needle` — searching the system
  * prompt and every message across all requests? The predicate that proves
  * injected context *reached the model*: a SessionStart hook's `additionalContext`
- * or a slash command's expansion. Harness tier only — the eval tier drives the
+ * or a slash command's expansion.
+ *
+ * THIS IS A PROJECTION OF THE REQUEST, NOT THE REQUEST — state what it omits
+ * before building a claim on it. Until 2026-09-10 this sentence was false: the
+ * flattener read only `.text`, so the eight `ContentBlockParam` variants that
+ * carry `content` were invisible, and a payload Claude Code had delivered inside
+ * a `tool_result` read as "never arrived" (zernie/vigiles#231, a false finding).
+ * It now covers every block type the pinned SDK union names, and serialises any
+ * it does not. STILL OMITTED BY DESIGN: `tool_use` / `server_tool_use` inputs —
+ * those are what the model SAID, not what it was TOLD, so a needle in a tool
+ * argument must not read as delivery. See `flattenBlock` in mock-model.ts. Harness tier only — the eval tier drives the
  * real API, so its `modelRequests` (and this) is empty. Behind `assertRequestContains`.
  */
 function requestContains(trace, needle) {

package/dist/hook-install.d.ts

@@ -36,6 +36,26 @@ interface SettingsJson {
  * absolute — still stable, just not relative to anything).
  */
 export declare function normalizeHookRef(hookPath: string, cwd?: string): string;
+/**
+ * The path token `compile` EMITS into the harness config — anchored at the project root
+ * when the harness declares such a variable.
+ *
+ * 🔴 IT LIVES BESIDE {@link bareToken} ON PURPOSE. That function STRIPS exactly this prefix
+ * and these quotes; this one ADDS them. They are one contract read from two ends, and while
+ * the ends sat apart only one got fixed: 2026-08-21 taught the reader to understand the
+ * anchored spelling, and the emitter went on writing the relative one for three more weeks.
+ *
+ * Why anchored at all, from the two measurements already in this file and in
+ * `PluginLayout.projectRootTokens`: a hook command does not run with a stable cwd, so a
+ * relative path "dies with exit 2 the moment the agent runs from a subdirectory". For a
+ * PreToolUse gate that is not a lost nudge — a gate that cannot load must block, so the
+ * repository seizes. Measured in a consumer repo 2026-09-10: recoverable by file writes
+ * only, because every command was refused, including the one that repairs it.
+ *
+ * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
+ * it is asserted directly rather than left to inspection.
+ */
+export declare function hookGateRef(ref: string, projectRootTokens: readonly string[] | undefined): string;
 /**
  * Idempotently merge a compiled hook's block into an existing `settings.json`
  * object. Entries managed by THIS hook file (the runtime command references

package/dist/hook-install.js

@@ -4,6 +4,7 @@ exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
 exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
 exports.normalizeHookRef = normalizeHookRef;
+exports.hookGateRef = hookGateRef;
 exports.mergeHooksJson = mergeHooksJson;
 exports.mergeHooksToml = mergeHooksToml;
 exports.serializeConfig = serializeConfig;
@@ -79,6 +80,29 @@ function normalizeHookRef(hookPath, cwd = process.cwd()) {
     const chosen = rel === "" || rel.startsWith("..") ? abs : rel;
     return chosen.split(node_path_1.sep).join("/");
 }
+/**
+ * The path token `compile` EMITS into the harness config — anchored at the project root
+ * when the harness declares such a variable.
+ *
+ * 🔴 IT LIVES BESIDE {@link bareToken} ON PURPOSE. That function STRIPS exactly this prefix
+ * and these quotes; this one ADDS them. They are one contract read from two ends, and while
+ * the ends sat apart only one got fixed: 2026-08-21 taught the reader to understand the
+ * anchored spelling, and the emitter went on writing the relative one for three more weeks.
+ *
+ * Why anchored at all, from the two measurements already in this file and in
+ * `PluginLayout.projectRootTokens`: a hook command does not run with a stable cwd, so a
+ * relative path "dies with exit 2 the moment the agent runs from a subdirectory". For a
+ * PreToolUse gate that is not a lost nudge — a gate that cannot load must block, so the
+ * repository seizes. Measured in a consumer repo 2026-09-10: recoverable by file writes
+ * only, because every command was refused, including the one that repairs it.
+ *
+ * `bareToken(hookGateRef(ref, tokens)) === ref` is what keeps a recompile idempotent, and
+ * it is asserted directly rather than left to inspection.
+ */
+function hookGateRef(ref, projectRootTokens) {
+    const token = projectRootTokens?.[0];
+    return token === undefined ? ref : `"${token}/${ref}"`;
+}
 /**
  * True when an entry's command routes through the runtime for `hookPath`.
  *

package/dist/hook-runtime.d.ts

@@ -58,6 +58,13 @@ export declare function hookStampPath(file: string): string;
  * action itself ({@link isStampRepairEvent}), and — on a LOAD failure only — the
  * load-path repair WRITE ({@link isLoadPathRepairEvent}), or the repo wedges
  * with no way to fix whatever broke the load path.
+ *
+ * INJECT-HOOK-SPECIFIC: An inject hook that fails to load is a harness failure,
+ * not a decision failure. Unlike gates (which must be conservative and block on
+ * any error), an inject is pure context addition. It degrades gracefully: if it
+ * cannot load, the session continues without the injected context, and the error
+ * is logged for debugging. This prevents a single broken inject from wedging all
+ * sessions.
  */
 export declare function runHookProgramCommand(file: string | undefined): Promise<void>;
 //# sourceMappingURL=hook-runtime.d.ts.map

package/dist/hook-runtime.js

@@ -364,6 +364,13 @@ function warnIfPathUndecidable(event, root) {
  * action itself ({@link isStampRepairEvent}), and — on a LOAD failure only — the
  * load-path repair WRITE ({@link isLoadPathRepairEvent}), or the repo wedges
  * with no way to fix whatever broke the load path.
+ *
+ * INJECT-HOOK-SPECIFIC: An inject hook that fails to load is a harness failure,
+ * not a decision failure. Unlike gates (which must be conservative and block on
+ * any error), an inject is pure context addition. It degrades gracefully: if it
+ * cannot load, the session continues without the injected context, and the error
+ * is logged for debugging. This prevents a single broken inject from wedging all
+ * sessions.
  */
 async function runHookProgramCommand(file) {
     if (!file) {
@@ -394,13 +401,20 @@ async function runHookProgramCommand(file) {
     try {
         program = await (0, exports.loadHookProgram)(file);
     }
-    catch {
+    catch (err) {
         // A LOAD failure is a fact about the harness, not a verdict about the
         // command that happened to arrive — so it must still fail CLOSED (a gate
         // that cannot run must not wave traffic through), but the two things it owes
         // the author are different from a `deny`'s: name the real cause, and leave a
         // way back.
         //
+        // EXCEPTION: inject hooks. An inject's purpose is to ADD context, not to
+        // ENFORCE a decision. If it fails to load, the session should degrade
+        // gracefully (no context injected) rather than wedging the entire harness.
+        // This is a harness failure, not a gating decision — so we handle it by
+        // logging the error and exiting 0. Gates (file, bash, prompt, stop) remain
+        // conservative and fail closed.
+        //
         // Escapes, both announced loudly on stderr:
         //   - the stale-stamp one (an edit to the hook itself / `vigiles compile`),
         //     for the hook broken mid-edit;
@@ -414,11 +428,18 @@ async function runHookProgramCommand(file) {
         // Everything else stays BLOCKED, and the escapes are whitelists of commands
         // that are WRITES — see `isLoadPathRepairEvent` for why no command is one.
         const conflicted = conflictedLoadPathFiles(file);
+        // 🔴 THE THROWN MESSAGE IS THE ONLY THING THAT NAMES THE REAL CAUSE when the
+        // merge-conflict heuristic above does not fire. Without it this said just
+        // "cannot be loaded" — a diagnosis that sends the reader looking in the wrong
+        // place, which is the defect this runtime has already shipped twice (the
+        // loader that advised `npm run build` when the answer was `npm install`).
+        // The comment above promises to name the cause; this is what keeps it.
+        const thrown = err instanceof Error ? err.message : String(err);
         const cause = conflicted.length > 0
             ? `cannot be loaded — ${conflicted.join(", ")} contains merge-conflict ` +
                 `markers, so Node cannot resolve \`vigiles/hook\` from it (the hook itself ` +
                 `may be fine)`
-            : "cannot be loaded";
+            : `cannot be loaded — ${thrown}`;
         if ((0, hook_program_js_1.isLoadPathRepairEvent)(event, file, {
             // The root the REST of this runtime already uses: `hookStampPath` and
             // `verifyStampOrRefuse` read the hook and its sidecar via `process.cwd()`,
@@ -431,7 +452,8 @@ async function runHookProgramCommand(file) {
             announceRepairEscape(file, cause);
             return;
         }
-        console.error(`vigiles: hook ${file} ${cause}.\n` +
+        // Log the error, but for inject hooks, degrade gracefully (exit 0).
+        const errorMsg = `vigiles: hook ${file} ${cause}.\n` +
             `vigiles: this is the state of the HARNESS, not a decision about your ` +
             `command — the gate never ran. Blocking anyway (a gate that cannot run ` +
             `must not pass traffic).\n` +
@@ -448,8 +470,22 @@ async function runHookProgramCommand(file) {
             `vigiles: no command is allowed, deliberately. \`git merge --abort\` and ` +
             `\`git checkout\` RUN \`.git/hooks/*\` (measured: reference-transaction, ` +
             `post-checkout), and \`vigiles compile\` loads the hook through the same ` +
-            `resolver that just failed.`);
-        process.exit(2);
+            `resolver that just failed.`;
+        console.error(errorMsg);
+        // Exit code depends on hook kind. This heuristic is based on the filename —
+        // a more robust approach would parse the stamp or metadata, but that requires
+        // the hook to load. Inject hooks typically have "inject" in the name; fall
+        // back to blocking (exit 2) for safety on gates.
+        const isLikelyInject = file.includes("inject");
+        if (isLikelyInject) {
+            // Inject hook: degrade gracefully. Log the error but don't wedge the session.
+            console.error(`vigiles: ${file} is an inject hook; degrading gracefully (no context injected).`);
+            process.exit(0);
+        }
+        else {
+            // Gate hook: fail closed.
+            process.exit(2);
+        }
         return;
     }
     verifyStampOrRefuse(file, event);

package/dist/mock-model.js

@@ -232,19 +232,143 @@ function splitRequestCounts(requests) {
             sideChannelCount++;
     return { count: requests.length - sideChannelCount, sideChannelCount };
 }
-/** Flatten Anthropic content (string, or an array of text/other blocks) to text. */
+/**
+ * Flatten one Anthropic content block to the text the MODEL actually received.
+ *
+ * WHY THIS IS A TYPED, EXHAUSTIVE SWITCH AND NOT A `.text` LOOKUP — the whole
+ * point of the file, and it was paid for. Until 2026-09-10 this read `b.text`
+ * and returned `""` for anything else. Eight of the sixteen `ContentBlockParam`
+ * variants carry their payload in `content`, not `text`, so half the union was
+ * invisible to every instrument built on `extractRequest` — `requestContains`,
+ * `refs-nudge.harness.mjs`, `injectable-events-delivery.harness.mjs`.
+ *
+ * WHAT THAT COST. Claude Code <= 2.1.227 delivered a `PostToolUse` hook's
+ * `additionalContext` as its own `text` block. From 2.1.228 (a PATCH release,
+ * 2026-08-11) it arrives appended to the `tool_result` block's `content`, inside
+ * a `<system-reminder>`. Nothing broke: the model received the payload on both
+ * versions. Our probe went blind, every test above reported "not delivered", and
+ * that false reading was written up as zernie/vigiles#231 and very nearly filed
+ * upstream as a regression in somebody else's product. MEASURED both ways on one
+ * machine, claude 2.1.267, changing only this function: blind = "landed=false",
+ * typed = "landed=true".
+ *
+ * WHAT THE TYPE BUYS, precisely — it is NOT a change detector:
+ *   - it does NOT notice a payload moving between fields the type already allows
+ *     (`ToolResultBlockParam.content` predates the relocation; nothing changed);
+ *   - it DOES make a silently-unhandled variant impossible: the `never` binding
+ *     below fails `tsc` until every case is written out, so the seventeenth
+ *     block type Anthropic ships breaks the BUILD instead of quietly emptying a
+ *     measurement.
+ *
+ * WHY THE DEFAULT SERIALISES INSTEAD OF RETURNING `""`. This is a measurement
+ * instrument, and its proven failure mode is the FALSE NEGATIVE — a payload that
+ * was there, reported missing. So an unrecognised block is over-included (its
+ * JSON) rather than dropped: a stale pin then costs a noisy match, never a
+ * silent hole. That asymmetry is deliberate; do not "tidy" it to `""`.
+ *
+ * The repo's `assertNever` is deliberately NOT used: it throws, and this parses
+ * untrusted wire JSON where an unknown block must degrade, not crash.
+ */
+function flattenBlock(b) {
+    switch (b.type) {
+        // WALKED — every string field is readable text the model was shown, and
+        // reading any one of them by name is what this function keeps getting
+        // wrong. `text` also carries `citations[].cited_text` / `document_title`
+        // (quoted source text); `search_result` carries `title` and `source`
+        // BESIDE its `content`; `document` spreads its text across `title`,
+        // `context` and `source` (`PlainTextSource.data`,
+        // `ContentBlockSource.content`). A base64 source is skipped inside
+        // `flattenUnknown` — bytes, not text.
+        case "text":
+        case "search_result":
+        case "document":
+            return flattenUnknown(b);
+        // READ NARROWLY, and the dropped field is named so the next reader can
+        // check the claim instead of trusting it: `signature` is an opaque
+        // attestation blob, not context.
+        case "thinking":
+            return b.thinking;
+        // The families whose payload hangs off `content`. Their only other field is
+        // `tool_use_id` — a correlation identifier, not text the model was shown.
+        // `content` is optional on `tool_result` alone; on the rest it is required
+        // and is an OBJECT, which `flattenContent` hands to `flattenUnknown`.
+        case "tool_result":
+        case "web_search_tool_result":
+        case "web_fetch_tool_result":
+        case "code_execution_tool_result":
+        case "bash_code_execution_tool_result":
+        case "text_editor_code_execution_tool_result":
+        case "tool_search_tool_result":
+            return b.content === undefined ? "" : flattenContent(b.content);
+        // The model's own call, not context delivered TO it — kept out of
+        // `requestContains` on purpose so a needle in a tool ARGUMENT is never read
+        // as "the model was told this". Their `id` / `name` are identifiers.
+        case "tool_use":
+        case "server_tool_use":
+            return "";
+        // No readable text by construction: `redacted_thinking.data` is encrypted,
+        // `container_upload.file_id` is an identifier, an image is pixels.
+        case "image":
+        case "redacted_thinking":
+        case "container_upload":
+            return "";
+        default: {
+            // Compile-time: unreachable, and that is the guard — a new variant makes
+            // this assignment fail. Run-time: reachable via wire JSON from a newer
+            // API than the pinned types, so it degrades loudly instead of throwing.
+            const unhandled = b;
+            return JSON.stringify(unhandled);
+        }
+    }
+}
+/**
+ * Flatten an arbitrary wire payload to text by walking every string leaf.
+ *
+ * WHY A GENERIC WALK AND NOT ONE MORE NAMED FIELD. The first version of
+ * `flattenBlock` grouped eight variants as "the ones that carry `content`" and
+ * handed each to `flattenContent`, which accepts only a string or an array.
+ * Six of those eight carry an OBJECT there — `web_fetch_tool_result`,
+ * `web_search_tool_result`, `code_execution_tool_result`,
+ * `bash_code_execution_tool_result`, `text_editor_code_execution_tool_result`,
+ * `tool_search_tool_result` — so they still flattened to "". The grouping was
+ * made on the field's NAME while the defect lives in its TYPE, which is the
+ * same mistake, one level up, as the `.text`-only read it replaced. Found by
+ * review on this PR, not by a run (zernie/vigiles#233).
+ *
+ * And no single field would have fixed it: the payload's text sits at a
+ * different key in each shape — `stdout`/`stderr` on a bash result, a nested
+ * `content` document on a fetch result, `data` on a plain-text source. Keying
+ * on any one of them re-commits the shape assumption. Walking commits to none.
+ */
+function flattenUnknown(v) {
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v))
+        return v.map(flattenUnknown).join("");
+    if (typeof v !== "object" || v === null)
+        return "";
+    const o = v;
+    // A base64 source is bytes, not text. Including it would bury every real
+    // match under megabytes of encoding — the one over-inclusion that costs more
+    // than the false negative it avoids.
+    if (o.type === "base64")
+        return "";
+    return Object.entries(o)
+        .filter(([k]) => k !== "type" && k !== "media_type") // discriminators
+        .map(([, val]) => flattenUnknown(val))
+        .join("");
+}
+/**
+ * Flatten Anthropic content to text: a string, an array of blocks, or the
+ * OBJECT a server-tool result carries (see `flattenUnknown`).
+ */
 function flattenContent(content) {
     if (typeof content === "string")
         return content;
     if (!Array.isArray(content))
-        return "";
+        return flattenUnknown(content);
     return content
-        .map((b) => {
-        if (typeof b === "string")
-            return b;
-        const t = b.text;
-        return typeof t === "string" ? t : "";
-    })
+        .map((b) => typeof b === "string" ? b : flattenBlock(b))
         .join("");
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "27.1.4",
+  "version": "27.1.6",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",
@@ -95,6 +95,7 @@
     "docs:api": "typedoc"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.124.0",
     "@eslint/js": "^10.0.1",
     "@jackchuka/mdschema": "^0.12.8",
     "@microsoft/api-extractor": "^7.58.9",
@@ -103,6 +104,7 @@
     "@types/markdown-it": "^14.1.2",
     "@types/minimatch": "^5.1.2",
     "@types/node": "^20.19.39",
+    "@types/picomatch": "^4.0.2",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "@vitest/coverage-v8": "^4.1.8",
@@ -113,6 +115,7 @@
     "eslint-plugin-sonarjs": "^4.0.2",
     "globals": "^17.4.0",
     "jest": "^30.4.2",
+    "picomatch": "^4.0.4",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.19",