vigiles 15.0.2 → 15.1.0

package/dist/adapters/claude-code/layout.js

@@ -18,6 +18,9 @@ exports.claudeCodeLayout = {
     commandDir: "commands",
     materializeRoot: ".claude",
     pluginRootToken: "${CLAUDE_PLUGIN_ROOT}",
+    // Both names Claude Code uses for the project root (mirrors the
+    // `NON_PLUGIN_VARS` set in plugin-loader.ts / scan-files.ts).
+    projectRootTokens: ["${CLAUDE_PROJECT_DIR}", "${CLAUDE_PROJECT}"],
     mcpConfigFile: ".mcp.json",
     mcpManifestKey: "mcpServers",
     intraRefDirs: ["hooks", "skills", "agents", "commands"],

package/dist/adapters/claude-code/run-scripts.d.ts

@@ -1,3 +1,4 @@
+import { type SurfaceProbe } from "../../check-count.js";
 /**
  * The outcome of running one script.
  *
@@ -16,6 +17,17 @@ export interface ScriptRunResult {
      * loaded the library and used none of it.
      */
     readonly checks?: number;
+    /**
+     * The surfaces this script was seen to exercise — derived by the tiers from the
+     * command they ran and the transcripts they got back, never declared by the
+     * author (see `coverage-probe.ts`). Feeds `.vigiles/coverage.json`, which lets
+     * coverage answer "tested?" by EXECUTION instead of by file name.
+     *
+     * Absent for a script that reported nothing, and empty for one that reported a
+     * count but exercised no identifiable surface — a unit test of a pure helper,
+     * say. Neither is a finding.
+     */
+    readonly surfaces?: readonly SurfaceProbe[];
 }
 /**
  * Exit code a harness/eval script uses to report itself SKIPPED (e.g. the
@@ -54,22 +66,18 @@ export declare function statusFor(code: number, checks: number | undefined): Scr
 export declare const SCRIPT_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
 /** Glob suffix matching every accepted script extension, e.g. `harness`. */
 export declare function scriptGlob(kind: "harness" | "eval"): string;
-/** Node runtime capabilities that decide how a TypeScript script is run. */
-export interface NodeCaps {
-    /** `tsx` is installed locally (the preferred, version-agnostic TS loader). */
-    readonly tsx: boolean;
-    /** Node supports `--experimental-strip-types` (>= 22.6). */
-    readonly stripTypes: boolean;
-}
+export { detectNodeCaps, canRunTypeScript, type NodeCaps, } from "../../ts-runner-caps.js";
+import type { NodeCaps } from "../../ts-runner-caps.js";
 /**
  * The `node` argv (after the binary) to run a single script. Plain JS runs
  * directly; a TypeScript script picks `tsx` when available, else Node's native
  * type stripping. Throws a clear, actionable error when neither is available.
  * Pure — exported for testing.
+ *
+ * 🔴 The disjunction below is `canRunTypeScript` — keep them together. When they
+ * drifted, the tool recommended a `.ts` file and then refused to run it.
  */
 export declare function interpreterArgs(file: string, caps: NodeCaps): string[];
-/** Detect TS-running capabilities for a project root. */
-export declare function detectNodeCaps(cwd: string): NodeCaps;
 /**
  * Expand the given path/glob patterns into concrete script files. A pattern
  * that is an existing file passes through unchanged; anything else is treated
@@ -87,6 +95,10 @@ export declare function discoverScripts(patterns: readonly string[], defaultGlob
  * "ran nothing" distinguishable from "ran and passed" (see check-count.ts). It
  * has to be a file: stdio is inherited so the script's report streams live,
  * which leaves no stream to parse.
+ *
+ * The same channel carries WHICH SURFACES the script exercised, so the caller can
+ * record them (`.vigiles/coverage.json`) and coverage can answer "tested?" from
+ * execution rather than from a matching file name.
  */
 export declare function runScripts(files: readonly string[], cwd: string, env?: NodeJS.ProcessEnv): ScriptRunResult[];
 /**

package/dist/adapters/claude-code/run-scripts.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCRIPT_EXTS = exports.SKIP_EXIT_CODE = void 0;
+exports.canRunTypeScript = exports.detectNodeCaps = exports.SCRIPT_EXTS = exports.SKIP_EXIT_CODE = void 0;
 exports.statusFor = statusFor;
 exports.scriptGlob = scriptGlob;
 exports.interpreterArgs = interpreterArgs;
-exports.detectNodeCaps = detectNodeCaps;
 exports.discoverScripts = discoverScripts;
 exports.runScripts = runScripts;
 exports.anyFailed = anyFailed;
@@ -74,11 +73,23 @@ function scriptGlob(kind) {
     return `**/*.${kind}.{${exports.SCRIPT_EXTS.join(",")}}`;
 }
 const TS_EXT = /\.(?:m|c)?ts$/;
+// The capability probe lives in `src/ts-runner-caps.ts` so the SUGGESTER
+// (`testFileExt`, harness-agnostic) can ask the same question this runner
+// answers. It used to recommend `.ts` from a `tsconfig.json` alone, on a Node 20
+// box with no `tsx` — a file `interpreterArgs` then refused to run. Re-exported
+// here so every existing importer of `run-scripts.js` is unchanged.
+var ts_runner_caps_js_1 = require("../../ts-runner-caps.js");
+Object.defineProperty(exports, "detectNodeCaps", { enumerable: true, get: function () { return ts_runner_caps_js_1.detectNodeCaps; } });
+Object.defineProperty(exports, "canRunTypeScript", { enumerable: true, get: function () { return ts_runner_caps_js_1.canRunTypeScript; } });
+const ts_runner_caps_js_2 = require("../../ts-runner-caps.js");
 /**
  * The `node` argv (after the binary) to run a single script. Plain JS runs
  * directly; a TypeScript script picks `tsx` when available, else Node's native
  * type stripping. Throws a clear, actionable error when neither is available.
  * Pure — exported for testing.
+ *
+ * 🔴 The disjunction below is `canRunTypeScript` — keep them together. When they
+ * drifted, the tool recommended a `.ts` file and then refused to run it.
  */
 function interpreterArgs(file, caps) {
     if (!TS_EXT.test(file))
@@ -90,13 +101,6 @@ function interpreterArgs(file, caps) {
     throw new Error(`Cannot run TypeScript test script "${file}": install tsx ` +
         `(npm i -D tsx) or use Node >= 22.6, or author it as a .mjs file.`);
 }
-/** Detect TS-running capabilities for a project root. */
-function detectNodeCaps(cwd) {
-    const tsx = (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/tsx/package.json")) ||
-        (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, "node_modules/.bin/tsx"));
-    const stripTypes = process.allowedNodeEnvironmentFlags.has("--experimental-strip-types");
-    return { tsx, stripTypes };
-}
 /**
  * Expand the given path/glob patterns into concrete script files. A pattern
  * that is an existing file passes through unchanged; anything else is treated
@@ -133,24 +137,21 @@ function discoverScripts(patterns, defaultGlob, cwd) {
     return [...found].sort();
 }
 /**
- * The count a script left behind, or `undefined` if it left none (it never
- * imported `vigiles/testing`, or died before its exit handler). Anything that
- * isn't a non-negative integer is treated as no report — a corrupt scratch file
- * must not invent a verdict.
+ * What a script left behind, or `undefined` if it left nothing (it never
+ * imported `vigiles/testing`, or died before its exit handler). The parse itself
+ * lives beside the writer in `check-count.ts` so the two cannot drift; anything
+ * malformed is treated as no report — a corrupt scratch file must not invent a
+ * verdict.
  */
-function readCheckCount(path) {
+function readCheckReport(path) {
     if (!(0, node_fs_1.existsSync)(path))
         return undefined;
-    let raw;
     try {
-        raw = (0, node_fs_1.readFileSync)(path, "utf8").trim();
+        return (0, check_count_js_1.parseCheckReport)((0, node_fs_1.readFileSync)(path, "utf8"));
     }
     catch {
         return undefined;
     }
-    if (!/^\d+$/.test(raw))
-        return undefined;
-    return Number(raw);
 }
 /**
  * Run each script as `node <file>`, inheriting stdio so the script's own report
@@ -162,9 +163,13 @@ function readCheckCount(path) {
  * "ran nothing" distinguishable from "ran and passed" (see check-count.ts). It
  * has to be a file: stdio is inherited so the script's report streams live,
  * which leaves no stream to parse.
+ *
+ * The same channel carries WHICH SURFACES the script exercised, so the caller can
+ * record them (`.vigiles/coverage.json`) and coverage can answer "tested?" from
+ * execution rather than from a matching file name.
  */
 function runScripts(files, cwd, env = {}) {
-    const caps = detectNodeCaps(cwd);
+    const caps = (0, ts_runner_caps_js_2.detectNodeCaps)(cwd);
     const results = [];
     const countDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-checks-"));
     try {
@@ -185,8 +190,14 @@ function runScripts(files, cwd, env = {}) {
                 env: { ...process.env, ...env, [check_count_js_1.CHECK_COUNT_ENV]: countFile },
             });
             const code = res.status ?? 1;
-            const checks = readCheckCount(countFile);
-            results.push({ file, code, status: statusFor(code, checks), checks });
+            const report = readCheckReport(countFile);
+            results.push({
+                file,
+                code,
+                status: statusFor(code, report?.checks),
+                checks: report?.checks,
+                ...(report ? { surfaces: report.surfaces } : {}),
+            });
         });
     }
     finally {

package/dist/adapters/codex/driver.js

@@ -53,7 +53,9 @@ function parseCodexRun(stdout) {
    codex-backed suite, the pure helpers above carry the testable logic. */
 function codexAvailable() {
     try {
-        return ((0, node_child_process_1.spawnSync)(runtime_js_1.codexRuntime.agentBinary, ["--version"], {
+        return (
+        // vigiles:free-tier — availability probe; `--version` prints and exits.
+        (0, node_child_process_1.spawnSync)(runtime_js_1.codexRuntime.agentBinary, ["--version"], {
             stdio: "ignore",
         }).status === 0);
     }

package/dist/adapters/codex/eval.js

@@ -35,6 +35,7 @@ exports.installCodexSkills = installCodexSkills;
 exports.codexEvalAgentRunner = codexEvalAgentRunner;
 exports.codexEvalRunner = codexEvalRunner;
 const node_child_process_1 = require("node:child_process");
+const foreign_runner_js_1 = require("../../core/foreign-runner.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const str = (v) => (typeof v === "string" ? v : "");
@@ -225,6 +226,10 @@ exports.codexEvalDriver = {
  * network egress to the model backend.
  */
 function codexEvalRunner(args) {
+    // The DOCUMENTED alternative to the default Claude runner, and the one the
+    // untested-skill nudge now recommends — so it is exactly as able to be
+    // collected by a stray `npx vitest run`, and exactly as expensive.
+    (0, foreign_runner_js_1.refuseUnderForeignRunner)("driving `codex exec`");
     const r = (0, node_child_process_1.spawnSync)("codex", [
         "exec",
         "--json",

package/dist/audit-score.js

@@ -82,6 +82,15 @@ function truthfulness(r) {
             weight: score_core_js_1.W_DANGLING_REF,
             label: "broken intra-plugin reference(s)",
         },
+        {
+            // Same weight and same category as the path-shaped one above: both are a
+            // reference that resolves to nothing. Counted separately only because the
+            // labels must read differently — "a path that isn't there" and "a skill
+            // that isn't there" send the reader to different fixes.
+            n: r.skillRefIssues?.length ?? 0,
+            weight: score_core_js_1.W_DANGLING_REF,
+            label: "skill(s) naming a sibling skill that does not exist",
+        },
         {
             n: missingHooks,
             weight: score_core_js_1.W_MISSING_HOOK,
@@ -198,10 +207,12 @@ function structure(r) {
 }
 /**
  * SAFETY — fed by the STATIC lethal-trifecta check (`report.trifectaFindings`), a
- * GRADED ring. EVERY unit holding all three capability legs counts, whether the
- * contract NAMED them (`"hard"`) or INHERITED them (`"advisory"` — no `tools:` /
- * `allowed-tools:` line, so it holds all three legs implicitly AND every other
- * capability besides). Grading only the explicit case made the ring non-monotone:
+ * GRADED ring. EVERY unit holding all three capability legs counts, whether a
+ * subagent's `tools:` NAMED them (`"hard"`) or the unit INHERITED them
+ * (`"advisory"` — a subagent with no `tools:` line, or a skill with no
+ * `disallowed-tools:` fence, which is every skill by default: `allowed-tools:` is
+ * a pre-approval and restricts nothing). Grading only the explicit case made the
+ * ring non-monotone:
  * declaring a tool contract — a genuine risk REDUCTION — could only ever lower the
  * score. The penalty is the shared {@link trifectaExposure} (capped against the
  * share of the surface exposed), the SAME number `reportDeductions` sums into the
@@ -230,10 +241,24 @@ function safety(r) {
     }
     // NAME the inherited ones: they're both the worst (every capability, not just
     // the three legs) and the cheapest to fix — declare a contract that drops a leg.
+    //
+    // EXCEPT the unfenced skills, which collapse into ONE line. A skill's
+    // `allowed-tools:` pre-approves rather than restricts (measured 2026-08-11), so
+    // EVERY skill without a `disallowed-tools:` line is in this state — naming them
+    // one at a time would bury the subagent findings under a list as long as the
+    // skill corpus. Same reasoning as the report section; see `trifectaLines`.
+    const unfenced = r.trifectaFindings.filter((f) => f.kind === "skill" && f.finding.fence === "none");
     for (const f of r.trifectaFindings) {
         if (f.finding.severity !== "advisory")
             continue;
-        findings.push(`${f.name} inherits all tools — the "lethal trifecta" (reads data, reaches the web, runs commands) plus every other capability, so a prompt injection could exfiltrate secrets`);
+        if (unfenced.includes(f))
+            continue;
+        findings.push(f.kind === "skill"
+            ? `${f.name}: ${f.finding.message}`
+            : `${f.name} inherits all tools — the "lethal trifecta" (reads data, reaches the web, runs commands) plus every other capability, so a prompt injection could exfiltrate secrets`);
+    }
+    if (unfenced.length > 0) {
+        findings.push(`${String(unfenced.length)} skill(s) declare no \`disallowed-tools:\` fence, so each inherits every tool the session grants — reads data, reaches the web, runs commands. \`allowed-tools:\` pre-approves, it does not restrict, so narrowing it does not reduce this; one \`disallowed-tools:\` line per skill drops a leg.`);
     }
     return {
         key: "Safety",
@@ -243,7 +268,8 @@ function safety(r) {
     };
 }
 /**
- * TESTED — DETERMINISTIC harness coverage only (`*.harness.mjs`, `*.test.*`):
+ * TESTED — DETERMINISTIC harness coverage only (`*.harness.*`, plus any custom
+ * `testGlobs`):
  * free, milliseconds, every push. It answers "does this gate still catch what it
  * claims?" The real-model tier is a SEPARATE ring ({@link evaluated}) because it
  * differs on cost, on cadence AND on the question it answers — folding both into

package/dist/check-count.d.ts

@@ -3,6 +3,31 @@
  * the runner (`runScripts`), read once here at import.
  */
 export declare const CHECK_COUNT_ENV = "VIGILES_CHECK_COUNT_FILE";
+/**
+ * How a tier came to name a surface. Not a strength ranking — a statement of
+ * what the machinery went by, so a reader can tell an inference from a sighting:
+ *
+ * - `command` — the executed command line named a program file (`runScript` /
+ *   `runHook`). The strongest kind: that exact path was handed to a process.
+ * - `fired` — the surface appears in the RUN'S TRANSCRIPT as having activated (a
+ *   `Skill` tool call that resolved, a hook that reported). For a skill this is
+ *   the only honest attribution: what was INSTALLED is a set, what RAN is one.
+ *
+ * There is deliberately NO author-declared origin. A `surface:` field on a spec
+ * would be `vigiles:covers` with extra steps — a claim about a test written by
+ * whoever wrote the test — and that tier was removed after its first real use
+ * declared a conformance lint over 21 skills as coverage of all 21.
+ */
+export type ProbeOrigin = "command" | "fired" | "dispatched";
+/**
+ * One surface a run went by. `ref` is whatever the tier saw — a script path, a
+ * namespaced skill id (`plugin:skill`), a hook name — NOT a resolved repo path.
+ * Resolution happens in the runner, where discovery lives.
+ */
+export interface SurfaceProbe {
+    readonly how: ProbeOrigin;
+    readonly ref: string;
+}
 /**
  * Record `n` checks against this script's run.
  *
@@ -15,11 +40,45 @@ export declare function recordCheck(n?: number): void;
 /** How many checks this process has recorded so far. */
 export declare function checksRecorded(): number;
 /**
- * Reset the counter AND the armed flag. For vigiles's own tests, which drive
- * {@link armCheckReport} with fakes several times in one process; a harness
- * script has no use for it.
+ * Record that this run exercised the surface `ref` names. Called by the TIERS
+ * from what they were pointed at — never by a harness author, because a field an
+ * author fills in is a claim, not a measurement (that was `vigiles:covers`, and
+ * it was removed for exactly this reason).
+ *
+ * Deduped: a harness that fires the same hook forty times names it once.
+ * Empty/blank refs are dropped rather than stored as a surface called "".
+ */
+export declare function recordSurfaceProbe(how: ProbeOrigin, ref: string): void;
+/** The surfaces this process has been seen to exercise, in first-seen order. */
+export declare function surfacesRecorded(): readonly SurfaceProbe[];
+/**
+ * Reset the counter, the probes AND the armed flag. For vigiles's own tests,
+ * which drive {@link armCheckReport} with fakes several times in one process; a
+ * harness script has no use for it.
  */
 export declare function resetCheckCount(): void;
+/** What a run reported: how much it did, and what it did it against. */
+export interface CheckReport {
+    readonly checks: number;
+    readonly surfaces: readonly SurfaceProbe[];
+}
+/**
+ * Serialize a report for the scratch file. A run with no probes writes the BARE
+ * NUMBER it has always written — byte for byte, so the legacy reader and the
+ * legacy tests are describing the same thing they always were. Only a run with
+ * an attribution to make spends a JSON object on it.
+ */
+export declare function formatCheckReport(report: CheckReport): string;
+/**
+ * Parse a scratch file's contents, or `undefined` for anything that is not a
+ * report. Lives beside {@link formatCheckReport} so the two cannot drift.
+ *
+ * Tolerant in exactly one direction: a bare integer is the legacy form and is
+ * read as a report with no attribution. Anything malformed — a torn write, a
+ * negative, a JSON object with the wrong shape — is NOT a report, because
+ * "corrupt" must never be turned into a verdict about someone's tests.
+ */
+export declare function parseCheckReport(raw: string): CheckReport | undefined;
 /** Injection seam for {@link armCheckReport} — the process bits it needs. */
 export interface CheckReportEnv {
     readonly env: NodeJS.ProcessEnv;

package/dist/check-count.js

@@ -3,7 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CHECK_COUNT_ENV = void 0;
 exports.recordCheck = recordCheck;
 exports.checksRecorded = checksRecorded;
+exports.recordSurfaceProbe = recordSurfaceProbe;
+exports.surfacesRecorded = surfacesRecorded;
 exports.resetCheckCount = resetCheckCount;
+exports.formatCheckReport = formatCheckReport;
+exports.parseCheckReport = parseCheckReport;
 exports.armCheckReport = armCheckReport;
 /**
  * vigiles — the CHECK COUNTER: the channel a `*.harness.*` / `*.eval.*` script
@@ -49,6 +53,34 @@ exports.armCheckReport = armCheckReport;
  * became impossible — was rejected: it would report `0` for a hand-rolled
  * harness that spawns and asserts entirely on its own, which is a real and
  * blameless way to write one.)
+ *
+ * ## 2026-08-11 — the channel also carries WHAT was exercised
+ *
+ * 🔴 THE DEFECT. Coverage answered "is surface X tested?" from a FILE NAME —
+ * colocation. Measured on a real repo, `.claude/skills/paper-pipeline/` held six
+ * `*.eval.mjs`, exactly one of them about that skill, and the orchestrator scored
+ * as covered with no test of its own; an EMPTY `foo.eval.mjs` counts just the
+ * same. Every mature ecosystem (`go test -cover`, coverage.py, nyc, tarpaulin)
+ * answers that question from EXECUTION and uses the name only to find the file.
+ *
+ * So the tiers now also record WHICH SURFACE a run went by — a {@link SurfaceProbe}
+ * — and this channel carries it out alongside the count. Two properties matter:
+ *
+ * - **Derived, never declared.** The probe comes from what the tier already knew
+ *   it was pointed at: the command string `runScript`/`runHook` executed, the
+ *   Skill/hook events in a run's transcript. A field an AUTHOR fills in would be
+ *   the retired `vigiles:covers` marker with extra steps — a claim about a test,
+ *   made by the person who wrote the test.
+ * - **A probe is a REFERENCE, not a verdict.** Resolving `hooks/pre-edit.sh` or
+ *   `plugin:argument-arc` to a repo surface needs discovery, which this module
+ *   has no business doing inside a user's test process. The runner resolves it
+ *   (`coverage-artifact.ts`); anything unresolvable is dropped, never guessed.
+ *
+ * WIRE FORMAT, and why it is two shapes. A run with no probes writes the bare
+ * number it always wrote, byte for byte; only a run with something to say writes
+ * JSON (`{"checks":N,"surfaces":[…]}`). Readers accept both — an older runner
+ * meeting the JSON form reads "no report", i.e. the legacy branch, which is a
+ * plain pass rather than a wrong verdict. Silence stays silence.
  */
 const node_fs_1 = require("node:fs");
 /**
@@ -65,7 +97,12 @@ exports.CHECK_COUNT_ENV = "VIGILES_CHECK_COUNT_FILE";
 const STATE = Symbol.for("vigiles.check-count");
 function state() {
     const g = globalThis;
-    return (g[STATE] ??= { count: 0, armed: false });
+    const s = (g[STATE] ??= { count: 0, armed: false, surfaces: new Map() });
+    // Two copies of vigiles can share one process (a global CLI plus a local
+    // dependency), and the OLDER copy's state object has no `surfaces` at all.
+    // Without this, the newer copy's first probe throws inside a user's test run.
+    s.surfaces ??= new Map();
+    return s;
 }
 /**
  * Record `n` checks against this script's run.
@@ -83,14 +120,92 @@ function checksRecorded() {
     return state().count;
 }
 /**
- * Reset the counter AND the armed flag. For vigiles's own tests, which drive
- * {@link armCheckReport} with fakes several times in one process; a harness
- * script has no use for it.
+ * Record that this run exercised the surface `ref` names. Called by the TIERS
+ * from what they were pointed at — never by a harness author, because a field an
+ * author fills in is a claim, not a measurement (that was `vigiles:covers`, and
+ * it was removed for exactly this reason).
+ *
+ * Deduped: a harness that fires the same hook forty times names it once.
+ * Empty/blank refs are dropped rather than stored as a surface called "".
+ */
+function recordSurfaceProbe(how, ref) {
+    const trimmed = ref.trim();
+    if (!trimmed)
+        return;
+    const s = state();
+    const key = `${how}\u0000${trimmed}`;
+    if (!s.surfaces.has(key))
+        s.surfaces.set(key, { how, ref: trimmed });
+}
+/** The surfaces this process has been seen to exercise, in first-seen order. */
+function surfacesRecorded() {
+    return [...state().surfaces.values()];
+}
+/**
+ * Reset the counter, the probes AND the armed flag. For vigiles's own tests,
+ * which drive {@link armCheckReport} with fakes several times in one process; a
+ * harness script has no use for it.
  */
 function resetCheckCount() {
     const s = state();
     s.count = 0;
     s.armed = false;
+    s.surfaces = new Map();
+}
+/**
+ * Serialize a report for the scratch file. A run with no probes writes the BARE
+ * NUMBER it has always written — byte for byte, so the legacy reader and the
+ * legacy tests are describing the same thing they always were. Only a run with
+ * an attribution to make spends a JSON object on it.
+ */
+function formatCheckReport(report) {
+    if (report.surfaces.length === 0)
+        return String(report.checks);
+    return JSON.stringify({ checks: report.checks, surfaces: report.surfaces });
+}
+/**
+ * Parse a scratch file's contents, or `undefined` for anything that is not a
+ * report. Lives beside {@link formatCheckReport} so the two cannot drift.
+ *
+ * Tolerant in exactly one direction: a bare integer is the legacy form and is
+ * read as a report with no attribution. Anything malformed — a torn write, a
+ * negative, a JSON object with the wrong shape — is NOT a report, because
+ * "corrupt" must never be turned into a verdict about someone's tests.
+ */
+function parseCheckReport(raw) {
+    const trimmed = raw.trim();
+    if (/^\d+$/.test(trimmed))
+        return { checks: Number(trimmed), surfaces: [] };
+    if (!trimmed.startsWith("{"))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+    if (!value || typeof value !== "object")
+        return undefined;
+    const obj = value;
+    const checks = obj.checks;
+    if (typeof checks !== "number" || !Number.isInteger(checks) || checks < 0)
+        return undefined;
+    const surfaces = Array.isArray(obj.surfaces)
+        ? obj.surfaces.map(toProbe).filter((p) => p !== null)
+        : [];
+    return { checks, surfaces };
+}
+/** One serialized probe, or null for anything that isn't one. */
+function toProbe(entry) {
+    if (!entry || typeof entry !== "object")
+        return null;
+    const { how, ref } = entry;
+    if (how !== "command" && how !== "fired" && how !== "dispatched")
+        return null;
+    if (typeof ref !== "string" || !ref.trim())
+        return null;
+    return { how, ref };
 }
 /**
  * Arm the exit-time report, returning whether it armed (i.e. whether the runner
@@ -115,7 +230,10 @@ function armCheckReport(deps) {
     s.armed = true;
     deps.onExit(() => {
         try {
-            deps.write(file, String(s.count));
+            deps.write(file, formatCheckReport({
+                checks: s.count,
+                surfaces: [...s.surfaces.values()],
+            }));
         }
         catch {
             // An unwritable scratch path must never turn a passing harness into a

package/dist/check.d.ts

@@ -78,6 +78,61 @@ export declare function toolWith(name: string, args: ArgMatcher): Check<Trace>;
  * not what it correctly refrained from doing.
  */
 export declare function notTool(name: string, args?: ArgMatcher): Check<Trace>;
+/**
+ * The agent used **only** tools drawn from `allowed` — the white-list, and the
+ * missing half of a symmetry the file surface already has:
+ *
+ * |       | "not this one"  | "nothing but these"    |
+ * | ----- | --------------- | ---------------------- |
+ * | files | `assertNoWrite` | `assertWroteOnly`      |
+ * | tools | {@link notTool} | **`onlyTools`** (this) |
+ *
+ * Why the asymmetry mattered: `notTool` can only forbid the calls the test
+ * author thought of, and the set of undeclared tools is unbounded — so "this
+ * skill stayed inside the tools it declares" was not expressible, which is
+ * exactly the claim a `SKILL.md` frontmatter makes in prose. See
+ * `skillContract`, which builds this check from that declaration.
+ *
+ * **Fails closed on an empty trace.** A `Trace` records tool calls only when the
+ * run captured the stream (`transcript: true` on the harness tier; always on the
+ * eval tier), so an uncaptured run is indistinguishable from a tool-free one —
+ * and passing it would assert nothing. Same discipline as `assertWroteOnly`
+ * refusing a result that never recorded writes: "we didn't look" is not "it was
+ * clean".
+ *
+ * 🔴 A `Tool(restriction)` DECLARATION IS MATCHED BY ITS BASE NAME. `allowed-tools:
+ * Bash(git:*)` is the ordinary way to write a narrow grant, and `skillContract`
+ * hands that literal string here — while a trace only ever carries the base name
+ * `Bash`, because that is the tool the harness reports. Set membership therefore
+ * missed, and every legitimate `Bash` call was reported as outside the declared
+ * surface, against a declaration that literally lists Bash (measured 2026-08-11:
+ * `agent used tool(s) outside its declared set: Bash (declared: Bash(git:*),
+ * Read, Skill)`). A check that fires on its own happy path gets deleted, not
+ * debugged — and it would fire on exactly the authors who narrowed their grant.
+ *
+ * ⚠️ AND THE RESTRICTION ITSELF IS NOT VERIFIED HERE, deliberately. A trace names
+ * the tool, not the grant it was matched against, so `Bash(git:*)` can be held to
+ * "no tool outside the declared set" and no further; whether the command really
+ * was a `git` one is a claim this layer has no evidence for. Narrowing beyond the
+ * base name is `disallowed-tools:` + `lethal-trifecta`'s job (see
+ * `skill-contract.ts`), which reads the grant instead of the run. The same
+ * `split("(")` normalization the rest of the codebase already applies to tool
+ * declarations — `core/tool-contract.ts`, `core/lethal-trifecta.ts`,
+ * `core/delegation-trifecta.ts`.
+ *
+ * ⚠️ SPANS THE WHOLE TRACE, deliberately. It answers "did this RUN stay inside
+ * these tools?", which is the right question for a harness that drives one thing.
+ * It is the wrong question when the trace has setup calls before the surface
+ * under test activated, drives several skills, or dispatches a subagent whose
+ * nested calls the parser folds into the same flat list — and reporting those as
+ * a violation is an accusation about the wrong code.
+ *
+ * `skillContract` therefore does NOT use this directly: it wraps it in a window
+ * bounded by its own `Skill` activation (see `duringSkill` in
+ * `src/skill-contract.ts`). If you are checking one skill, prefer the contract;
+ * reach for this when the claim really is about the whole run.
+ */
+export declare function onlyTools(allowed: readonly string[]): 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. */