vigiles 4.1.0 → 5.0.1

package/README.md

@@ -5,12 +5,11 @@
 <h1 align="center">vigiles</h1>
 
 <p align="center">
-  <em>Quis custodiet ipsos custodes?</em> — Who watches the watchmen?
+  <strong>Lint &amp; test the harness your AI agent runs on.</strong>
 </p>
 
 <p align="center">
-  <strong>The missing linting + testing layer for agentic coding.</strong><br />
-  vigiles <strong>lints</strong> the references your instruction files make — linter rules, file paths, scripts, code symbols — and <strong>tests</strong> whether your hooks, skills, and CLAUDE.md actually change what the agent does.
+  Your CLAUDE.md, hooks, and skills steer the agent — but nothing checks they're <em>true</em>, and nothing tests they <em>work</em>. vigiles does both.
 </p>
 
 <p align="center">
@@ -22,81 +21,17 @@
 ---
 
 `Agent = Model + Harness`. You'd never ship an app without a linter and a test
-suite — yet an AI agent steering your repo is trusted on vibes. vigiles is the
-deterministic layer for the harness: it **lints** the references your instruction
-files make and **tests** that your hooks and skills actually fire. Two independent
-pillars — adopt either, or both:
+suite — yet the harness steering your agent runs on vibes. vigiles[^name] is the
+deterministic layer for it, and does two independent things — adopt either, or both:
 
-|       | Pillar                          | What it does                                                                                                                                                                                                |
-| ----- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **①** | **Lint your instruction files** | Every linter rule, file path, script, and code symbol your CLAUDE.md cites is checked against reality, so stale references can't silently mislead the agent. → [guide](docs/verifying-instruction-files.md) |
-| **②** | **Test your harness**           | Your hooks and skills are code — vigiles tests they actually fire, **deterministically and free** (no model, no API key) before you pay for an eval. → [guide](docs/harness-testing.md)                     |
+|             |                                                                                                                                                                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **🔎 Lint** | Every file path, script, code symbol, and linter rule your CLAUDE.md cites is checked against reality — so a renamed file or a disabled rule can't silently mislead the agent. **[→](docs/verifying-instruction-files.md)**                      |
+| **🧪 Test** | Hooks, skills, and subagents are code. vigiles tests they _do their job_ — and almost all of it is **deterministic, no API key**; the real-model evals run on your **Claude subscription**, not metered tokens. **[→](docs/harness-testing.md)** |
 
-Neither pillar depends on the other — pick the one that hurts today. **Works with
-Claude Code and Codex** ([`vigiles/codex`](docs/harnesses.md)) behind a five-port
-adapter; [custom adapters welcome](docs/authoring-an-adapter.md).
-
-## ① Lint — your CLAUDE.md lies to your agent
-
-Your CLAUDE.md says _"enforce `eslint/no-console`."_ But it was switched off
-months ago — and the agent trusts the claim. (Same story for the file path it
-cites that got renamed, and the script that was deleted.)
-
-**Without vigiles:** nobody checks. The agent acts on fiction.
-
-**With vigiles:** `npx vigiles lint` resolves every reference against reality —
-
-```text
-CLAUDE.md (inline mode):
-  ✗ line 1: Rule "eslint/no-console" exists but is disabled in eslint config
-  ✓ line 2: eslint/eqeqeq
-  ✗ line 3: Rule "no-consoel" not found in eslint. Did you mean: "eslint/no-console"?
-```
-
-It resolves rule names across **7 linter catalogs** — the rule exists **and is
-enabled** — and checks file paths, scripts, and code symbols the same way. Start
-with one comment, no new files:
-
-```md
-<!-- vigiles:enforce eslint/no-console "Route output through logger.ts" -->
-```
-
-Step up to a typed `.spec.ts` (compiled to CLAUDE.md, compiler-grade) when you
-want it. **[Full guide →](docs/verifying-instruction-files.md)**
-
-## ② Test — does your harness actually fire?
-
-A hook can be wired wrong, a skill's description can fail to trigger, injected
-context can never reach the model — silently, all passing a naive "did it run?"
-check.
-
-**Without vigiles:** you assume your `--no-verify` guard blocks. You don't know.
-
-**With vigiles:** a deterministic test proves it — no model, no API key,
-milliseconds:
-
-```typescript
-import { runHook } from "vigiles/testing";
-
-const r = runHook(guard, {
-  hook_event_name: "PreToolUse",
-  tool_name: "Bash",
-  tool_input: { command: "git commit --no-verify" },
-});
-assert(r.blocked); // a red ✗ here means your hook silently lets it through
-```
-
-```text
-  ✓ guard blocks --no-verify and allows a clean commit
-
-2 passed.
-```
-
-Three tiers, cheapest first: **`runHook`** (a hook's logic), **`runHarnessTest`**
-(the real agent CLI against a scripted mock model), **`runEval`** (the real model
-A/B with a significance gate). **Testing a skill?** `measureTriggerRate` checks
-its description actually **fires** across varied prompts (recall) without
-hijacking unrelated ones (precision). **[Full guide →](docs/harness-testing.md)**
+Pick the one that hurts today. **Works with Claude Code and Codex**
+([`vigiles/codex`](docs/harnesses.md)) behind a five-port adapter;
+[custom adapters welcome](docs/authoring-an-adapter.md).
 
 ## Quick start
 
@@ -105,7 +40,7 @@ hijacking unrelated ones (precision). **[Full guide →](docs/harness-testing.md
 ```text
 Install vigiles in this repo and run it. Verify my CLAUDE.md / AGENTS.md
 references and show me what's stale, then write and run a harness test for one
-of my hooks or skills. Use good defaults (both pillars, non-interactive), but
+of my hooks or skills. Use good defaults (lint + test, non-interactive), but
 ask me first whether to gate it in CI, whether to add a real-model eval, and
 whether to enforce strictly (--strict).
 ```
@@ -113,7 +48,7 @@ whether to enforce strictly (--strict).
 Or do it yourself:
 
 ```bash
-npx vigiles init   # sets up BOTH pillars: spec + harness test + CI + plugin
+npx vigiles init   # sets up lint + test: spec + harness test + CI + plugin
 ```
 
 It's interactive in a terminal and non-interactive for agents/CI (or with
@@ -124,7 +59,7 @@ tell your agent _"test my skills"_ and it picks the tier and writes the test.
 <details>
 <summary>What <code>init</code> sets up</summary>
 
-- **Both pillars** by default; scope with `--lint` / `--test` (one or both).
+- **Both lint and test** by default; scope with `--lint` / `--test` (one or both).
 - Adds `vigiles` to your `devDependencies`.
 - Installs the Claude Code plugin (skills + hooks) via the marketplace —
   globally, never vendored into your repo.
@@ -140,6 +75,61 @@ Prefer to write tests yourself? They can be JS **or** TS
 
 </details>
 
+## ① Lint — your CLAUDE.md lies to your agent
+
+Your CLAUDE.md points the agent at `src/auth/login.ts` and tells it to run
+`npm run check`. But the file moved to `src/auth/session.ts` six commits ago, and
+the script was renamed. The agent trusts the stale claim and acts on fiction.
+
+`npx vigiles lint` resolves every reference against reality:
+
+```text
+CLAUDE.md:
+  ✗ src/auth/login.ts — no such file (renamed or moved?)
+  ✗ npm run check — not in package.json. Did you mean: "check:types"?
+  ✓ @typescript-eslint/no-floating-promises — exists and enabled in eslint config
+```
+
+File paths, scripts, and code symbols — plus linter rules across **7 catalogs**
+(the rule exists **and is enabled**). Start with one inline comment, no new files;
+step up to a typed `.spec.ts` (compiled to CLAUDE.md, compiler-grade) when you want
+it. **[Full guide →](docs/verifying-instruction-files.md)**
+
+## ② Test — does your harness do its job?
+
+A hook can be wired wrong. A skill's description can fail to trigger — or hijack
+unrelated prompts. Injected context can never reach the model. All of it passes a
+naive "did it run?" check. vigiles tests the assembled harness for real:
+
+```typescript
+import { runHook } from "vigiles/testing";
+
+const r = runHook(guard, {
+  hook_event_name: "PreToolUse",
+  tool_name: "Bash",
+  tool_input: { command: "git commit --no-verify" },
+});
+assert(r.blocked); // a red ✗ means your guard silently lets it through
+```
+
+It goes well past _"did it fire?"_:
+
+- **Hooks block** what they must — `runHook`, or the real agent CLI via `runHarnessTest`.
+- **Skills trigger** on the right prompts and stay quiet on the wrong ones — recall _and_ precision (`measureTriggerRate`).
+- **Behaviour is good** — score a skill's output directly, or A/B it on-vs-off for the real lift over no-skill (`measure` / `runEval`, with significance testing).
+- **Safety holds** — the agent _didn't_ push to the wrong branch or hit a paid API; `interceptTools` catches the attempt so the side effect never happens.
+
+**The eval you can actually afford.** Almost every tier runs with **no model and
+no API key** — milliseconds, on every commit. The rest drive your own `claude` CLI:
+
+|                        | Runs on                 | Cost                                        |
+| ---------------------- | ----------------------- | ------------------------------------------- |
+| promptfoo, DeepEval, … | metered API SDK         | billed **per token, every run**             |
+| **vigiles**            | your Claude Pro/Max sub | **$0 extra** — and most tiers need no model |
+
+That's why you can eval your harness on every change, not just once.
+**[How it works →](docs/harness-testing.md)** · **[Why it's affordable →](docs/eval-architecture.md)** · **[Safety model →](docs/safety.md)**
+
 ## More
 
 - **[CLI & GitHub Action →](docs/cli.md)** — every command, the Action (inputs / output / versioning), the Claude Code plugin, and the five `lint` rules.
@@ -150,3 +140,5 @@ Prefer to write tests yourself? They can be JS **or** TS
 ## License
 
 [MIT](LICENSE)
+
+[^name]: **vigiles** — the watchmen of ancient Rome, who guarded the city (and fought its fires) by night. _Quis custodiet ipsos custodes?_ — "who watches the watchmen?" (Juvenal, _Satire VI_).

package/dist/adapters/claude-code/agent-runtime.d.ts

@@ -3,7 +3,7 @@
  *
  * A subagent declares an allowed-tools contract in its frontmatter (`tools:`).
  * But that field is documentation, not a hard runtime boundary (Claude Code
- * issue #54898): permissions are session-wide, a subagent inherits the parent
+ * #4740/#21460, SDK #172): permissions are session-wide, a subagent inherits the parent
  * session's grants, and `tools:` only filters what's *offered* — it can't deny
  * what the session allows. The deterministic layer that actually closes the gap
  * is a **PreToolUse hook** that blocks any tool the active agent's contract

package/dist/adapters/claude-code/agent-runtime.js

@@ -4,7 +4,7 @@
  *
  * A subagent declares an allowed-tools contract in its frontmatter (`tools:`).
  * But that field is documentation, not a hard runtime boundary (Claude Code
- * issue #54898): permissions are session-wide, a subagent inherits the parent
+ * #4740/#21460, SDK #172): permissions are session-wide, a subagent inherits the parent
  * session's grants, and `tools:` only filters what's *offered* — it can't deny
  * what the session allows. The deterministic layer that actually closes the gap
  * is a **PreToolUse hook** that blocks any tool the active agent's contract

package/dist/arg-match.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `ArgMatcher` — a small, serializable matcher over a tool call's `input`.
+ *
+ * Shared by the check vocabulary (`toolWith` / `notTool` in `src/check.ts`) and
+ * the tool-interception seam (`src/tool-intercept.ts`), so "did the agent call
+ * this tool with these arguments?" means the same thing whether you're *asserting*
+ * on a captured call or *intercepting* one before it runs. Pure + model-free.
+ */
+/**
+ * A declarative matcher over a tool call's `input`, keyed by **dot-path** (e.g.
+ * `"body.prompt"`). Each value is matched against the value at that path: a
+ * `RegExp` is a pattern over the stringified value (use this for "contains"), and
+ * a `string`/`number`/`boolean` is an **exact** match (use this for "equals", e.g.
+ * a push target). All keys must match (AND). Serializable, so anything carrying
+ * one still round-trips through `toJSON`.
+ */
+export type ArgMatcher = Record<string, string | number | boolean | RegExp>;
+/** Render any tool-input value as a string for matching / messages. */
+export declare function stringifyValue(v: unknown): string;
+/** Resolve a dot-path (`"a.b.c"`) within an arbitrary value, or undefined. */
+export declare function getPath(obj: unknown, path: string): unknown;
+/** Does `input` satisfy every entry of `matcher`? (RegExp = pattern, else exact.) */
+export declare function matchesArgs(input: unknown, matcher: ArgMatcher): boolean;
+/** A human-readable form of a matcher for failure messages. */
+export declare function describeArgs(matcher: ArgMatcher): string;
+/** Serialize a matcher for `toJSON` (RegExp → its string form). */
+export declare function serializeArgs(matcher: ArgMatcher): Record<string, string | number | boolean>;
+//# sourceMappingURL=arg-match.d.ts.map

package/dist/arg-match.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * `ArgMatcher` — a small, serializable matcher over a tool call's `input`.
+ *
+ * Shared by the check vocabulary (`toolWith` / `notTool` in `src/check.ts`) and
+ * the tool-interception seam (`src/tool-intercept.ts`), so "did the agent call
+ * this tool with these arguments?" means the same thing whether you're *asserting*
+ * on a captured call or *intercepting* one before it runs. Pure + model-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringifyValue = stringifyValue;
+exports.getPath = getPath;
+exports.matchesArgs = matchesArgs;
+exports.describeArgs = describeArgs;
+exports.serializeArgs = serializeArgs;
+/** Render any tool-input value as a string for matching / messages. */
+function stringifyValue(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "object" && v !== null) {
+        try {
+            return JSON.stringify(v) ?? "[object]";
+        }
+        catch {
+            return "[object]";
+        }
+    }
+    return String(v);
+}
+/** Resolve a dot-path (`"a.b.c"`) within an arbitrary value, or undefined. */
+function getPath(obj, path) {
+    let cur = obj;
+    for (const part of path.split(".")) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+/** Does `input` satisfy every entry of `matcher`? (RegExp = pattern, else exact.) */
+function matchesArgs(input, matcher) {
+    return Object.entries(matcher).every(([key, m]) => {
+        const value = getPath(input, key);
+        return m instanceof RegExp ? m.test(stringifyValue(value)) : value === m;
+    });
+}
+/** A human-readable form of a matcher for failure messages. */
+function describeArgs(matcher) {
+    return Object.entries(matcher)
+        .map(([k, m]) => `${k}=${m instanceof RegExp ? String(m) : JSON.stringify(m)}`)
+        .join(", ");
+}
+/** Serialize a matcher for `toJSON` (RegExp → its string form). */
+function serializeArgs(matcher) {
+    const out = {};
+    for (const [k, m] of Object.entries(matcher)) {
+        out[k] = m instanceof RegExp ? String(m) : m;
+    }
+    return out;
+}
+//# sourceMappingURL=arg-match.js.map

package/dist/check.d.ts

@@ -18,6 +18,8 @@
  */
 import type { Trace } from "./harness-test.js";
 import type { HookRunResult } from "./run-hook.js";
+import { type ArgMatcher } from "./arg-match.js";
+export type { ArgMatcher };
 /** The outcome of evaluating one check against one result. */
 export interface CheckResult {
     /** Did the check hold? */
@@ -54,6 +56,28 @@ export declare function evalChecks<T>(target: T, checks: readonly Check<T>[]): C
 export declare function assertChecks<T>(target: T, checks: readonly Check<T>[]): void;
 /** The agent invoked a tool by this name (regardless of result). */
 export declare function tool(name: string): Check<Trace>;
+/**
+ * The agent used tool `name` with at least one call whose `input` matches `args`
+ * — the **argument** half of the tool-call spy. Asserts not just *that* a tool was
+ * reached but *how* it was called (the image-request body carried the style suffix,
+ * the panel spawn requested a non-expert), which a completion grader can't see.
+ *
+ * Cross-reference: ≈ promptfoo `is-valid-function-call` / DeepEval `ToolCorrectnessMetric`.
+ */
+export declare function toolWith(name: string, args: ArgMatcher): Check<Trace>;
+/**
+ * The agent did NOT use tool `name` — the **safety / negative** assertion. With
+ * `args`, only calls whose `input` matches are forbidden (so "did not push to
+ * `main`" still allows pushing elsewhere; "no paid API call" forbids it outright).
+ * This is the highest-value, most-overlooked check, and the one a
+ * completion-grading eval structurally cannot make: it sees the agent's *decision*
+ * to act, not just its final text.
+ *
+ * Cross-reference: this negative/safety assertion of a *decision not to act* has
+ * no promptfoo / DeepEval / Inspect equivalent — they grade what the agent DID,
+ * not what it correctly refrained from doing.
+ */
+export declare function notTool(name: string, args?: ArgMatcher): Check<Trace>;
 /** A skill resolved to this id (`<plugin>:<skill>`) without erroring. */
 export declare function skill(id: string): Check<Trace>;
 /** The agent's final output contains a substring / matches a RegExp. */
@@ -112,8 +136,13 @@ interface UsageTrace {
     readonly usage: {
         readonly costUsd: number;
         readonly durationMs: number;
+        /** Fresh (uncached) input tokens, billed at full input price. */
         readonly inputTokens: number;
         readonly outputTokens: number;
+        /** Tokens written to the prompt cache this run (~1.25× input price). */
+        readonly cacheCreationTokens: number;
+        /** Tokens served from the prompt cache this run (~0.1× input price). */
+        readonly cacheReadTokens: number;
     };
 }
 /** The run cost at most `maxUsd`. */
@@ -128,5 +157,27 @@ export declare function latency(opts: {
 export declare function tokens(opts: {
     max: number;
 }): Check<UsageTrace>;
-export {};
+/**
+ * The run used at most `max` **fresh (uncached) input** tokens. The honest input
+ * side of a cost claim: a skill or CLAUDE.md injection adds input every turn, so
+ * a "compression" win on output can be erased here. (Cache reads are separate —
+ * see `cacheTokens`.)
+ */
+export declare function inputTokens(opts: {
+    max: number;
+}): Check<UsageTrace>;
+/** The run used at most `max` **output** tokens — the generation side. */
+export declare function outputTokens(opts: {
+    max: number;
+}): Check<UsageTrace>;
+/**
+ * Bound the prompt-cache token classes a run uses. `maxCreation` caps tokens
+ * **written** to the cache (the ~1.25× write premium — a fresh/cold prompt);
+ * `maxRead` caps tokens **served** from cache (~0.1× input). Each constraint is
+ * checked only when provided; the check passes when every provided bound holds.
+ */
+export declare function cacheTokens(opts: {
+    maxCreation?: number;
+    maxRead?: number;
+}): Check<UsageTrace>;
 //# sourceMappingURL=check.d.ts.map

package/dist/check.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.evalChecks = evalChecks;
 exports.assertChecks = assertChecks;
 exports.tool = tool;
+exports.toolWith = toolWith;
+exports.notTool = notTool;
 exports.skill = skill;
 exports.output = output;
 exports.hookFired = hookFired;
@@ -17,7 +19,11 @@ exports.judged = judged;
 exports.cost = cost;
 exports.latency = latency;
 exports.tokens = tokens;
+exports.inputTokens = inputTokens;
+exports.outputTokens = outputTokens;
+exports.cacheTokens = cacheTokens;
 const judge_js_1 = require("./judge.js");
+const arg_match_js_1 = require("./arg-match.js");
 /** Evaluate every check against a target. Pure — the shared core of `expect`
  * (strict) and `measure` (scored). */
 function evalChecks(target, checks) {
@@ -71,6 +77,63 @@ function tool(name) {
         toJSON: () => ({ kind: "tool", name }),
     };
 }
+/**
+ * The agent used tool `name` with at least one call whose `input` matches `args`
+ * — the **argument** half of the tool-call spy. Asserts not just *that* a tool was
+ * reached but *how* it was called (the image-request body carried the style suffix,
+ * the panel spawn requested a non-expert), which a completion grader can't see.
+ *
+ * Cross-reference: ≈ promptfoo `is-valid-function-call` / DeepEval `ToolCorrectnessMetric`.
+ */
+function toolWith(name, args) {
+    return {
+        kind: "toolWith",
+        eval: (t) => {
+            const calls = t.toolCalls.filter((c) => c.name === name);
+            const want = (0, arg_match_js_1.describeArgs)(args);
+            if (calls.length === 0) {
+                return no(`expected the agent to use tool "${name}" (with ${want}), but it used ${distinctToolNames(t.toolCalls)}`);
+            }
+            return calls.some((c) => (0, arg_match_js_1.matchesArgs)(c.input, args))
+                ? ok(`agent used "${name}" with ${want}`)
+                : no(`agent used "${name}" but never with ${want} (saw ${calls
+                    .map((c) => truncate((0, arg_match_js_1.stringifyValue)(c.input), 60))
+                    .join("; ")})`);
+        },
+        toJSON: () => ({ kind: "toolWith", name, args: (0, arg_match_js_1.serializeArgs)(args) }),
+    };
+}
+/**
+ * The agent did NOT use tool `name` — the **safety / negative** assertion. With
+ * `args`, only calls whose `input` matches are forbidden (so "did not push to
+ * `main`" still allows pushing elsewhere; "no paid API call" forbids it outright).
+ * This is the highest-value, most-overlooked check, and the one a
+ * completion-grading eval structurally cannot make: it sees the agent's *decision*
+ * to act, not just its final text.
+ *
+ * Cross-reference: this negative/safety assertion of a *decision not to act* has
+ * no promptfoo / DeepEval / Inspect equivalent — they grade what the agent DID,
+ * not what it correctly refrained from doing.
+ */
+function notTool(name, args) {
+    return {
+        kind: "notTool",
+        eval: (t) => {
+            const calls = t.toolCalls.filter((c) => c.name === name);
+            const offending = args
+                ? calls.filter((c) => (0, arg_match_js_1.matchesArgs)(c.input, args))
+                : calls;
+            const what = args ? `"${name}" with ${(0, arg_match_js_1.describeArgs)(args)}` : `"${name}"`;
+            const first = offending[0];
+            if (!first)
+                return ok(`agent never used ${what}`);
+            return no(`expected the agent NOT to use ${what}, but it did (${truncate((0, arg_match_js_1.stringifyValue)(first.input), 60)})`);
+        },
+        toJSON: () => args
+            ? { kind: "notTool", name, args: (0, arg_match_js_1.serializeArgs)(args) }
+            : { kind: "notTool", name },
+    };
+}
 /** A skill resolved to this id (`<plugin>:<skill>`) without erroring. */
 function skill(id) {
     return {
@@ -315,4 +378,62 @@ function tokens(opts) {
         toJSON: () => ({ kind: "tokens", max: opts.max }),
     };
 }
+/**
+ * The run used at most `max` **fresh (uncached) input** tokens. The honest input
+ * side of a cost claim: a skill or CLAUDE.md injection adds input every turn, so
+ * a "compression" win on output can be erased here. (Cache reads are separate —
+ * see `cacheTokens`.)
+ */
+function inputTokens(opts) {
+    return {
+        kind: "inputTokens",
+        eval: (t) => {
+            const v = t.usage.inputTokens;
+            return v <= opts.max
+                ? ok(`${String(v)} input tokens ≤ ${String(opts.max)}`)
+                : no(`expected ≤ ${String(opts.max)} input tokens, got ${String(v)}`);
+        },
+        toJSON: () => ({ kind: "inputTokens", max: opts.max }),
+    };
+}
+/** The run used at most `max` **output** tokens — the generation side. */
+function outputTokens(opts) {
+    return {
+        kind: "outputTokens",
+        eval: (t) => {
+            const v = t.usage.outputTokens;
+            return v <= opts.max
+                ? ok(`${String(v)} output tokens ≤ ${String(opts.max)}`)
+                : no(`expected ≤ ${String(opts.max)} output tokens, got ${String(v)}`);
+        },
+        toJSON: () => ({ kind: "outputTokens", max: opts.max }),
+    };
+}
+/**
+ * Bound the prompt-cache token classes a run uses. `maxCreation` caps tokens
+ * **written** to the cache (the ~1.25× write premium — a fresh/cold prompt);
+ * `maxRead` caps tokens **served** from cache (~0.1× input). Each constraint is
+ * checked only when provided; the check passes when every provided bound holds.
+ */
+function cacheTokens(opts) {
+    return {
+        kind: "cacheTokens",
+        eval: (t) => {
+            const created = t.usage.cacheCreationTokens;
+            const read = t.usage.cacheReadTokens;
+            if (opts.maxCreation !== undefined && created > opts.maxCreation) {
+                return no(`expected ≤ ${String(opts.maxCreation)} cache-creation tokens, got ${String(created)}`);
+            }
+            if (opts.maxRead !== undefined && read > opts.maxRead) {
+                return no(`expected ≤ ${String(opts.maxRead)} cache-read tokens, got ${String(read)}`);
+            }
+            return ok(`cache tokens within bounds (created ${String(created)}, read ${String(read)})`);
+        },
+        toJSON: () => ({
+            kind: "cacheTokens",
+            ...(opts.maxCreation !== undefined && { maxCreation: opts.maxCreation }),
+            ...(opts.maxRead !== undefined && { maxRead: opts.maxRead }),
+        }),
+    };
+}
 //# sourceMappingURL=check.js.map

package/dist/claude-code.d.ts

@@ -7,6 +7,7 @@
  */
 export * from "./adapters/claude-code/plugin-loader.js";
 export * from "./mock-model.js";
+export { claudeCodeDriver, buildClaudeArgs, parseClaudeRun, claudeAvailable, } from "./harness-test.js";
 export * from "./adapters/claude-code/dialect.js";
 export * from "./adapters/claude-code/layout.js";
 export * from "./adapters/claude-code/runtime.js";

package/dist/claude-code.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeAvailable = exports.parseClaudeRun = exports.buildClaudeArgs = exports.claudeCodeDriver = void 0;
 /**
  * `vigiles/claude-code` — the Claude Code-specific harness pieces a *different*
  * harness would swap out: the plugin/repo loader (reads real Claude Code plugin
@@ -23,6 +24,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 __exportStar(require("./adapters/claude-code/plugin-loader.js"), exports);
 __exportStar(require("./mock-model.js"), exports);
+// The Claude-Code harness-test transport — the default driver + its argv/parse
+// helpers + the `claude` capability probe. Agnostic users never need these
+// (`runHarnessTest` defaults to the CC driver), but they're exposed here — beside
+// the Codex driver in `vigiles/codex` — for CC-specific tests/tooling. They are
+// deliberately NOT on the agnostic `vigiles/testing` surface.
+var harness_test_js_1 = require("./harness-test.js");
+Object.defineProperty(exports, "claudeCodeDriver", { enumerable: true, get: function () { return harness_test_js_1.claudeCodeDriver; } });
+Object.defineProperty(exports, "buildClaudeArgs", { enumerable: true, get: function () { return harness_test_js_1.buildClaudeArgs; } });
+Object.defineProperty(exports, "parseClaudeRun", { enumerable: true, get: function () { return harness_test_js_1.parseClaudeRun; } });
+Object.defineProperty(exports, "claudeAvailable", { enumerable: true, get: function () { return harness_test_js_1.claudeAvailable; } });
 __exportStar(require("./adapters/claude-code/dialect.js"), exports);
 __exportStar(require("./adapters/claude-code/layout.js"), exports);
 __exportStar(require("./adapters/claude-code/runtime.js"), exports);