vigiles 34.0.0 → 35.0.0

package/dist/adapters/codex/driver.js

@@ -75,7 +75,8 @@ async function startCodexMockHandle(script) {
             }));
         },
         get count() {
-            return mock.requests.length;
+            // Turns SERVED: a request past the end of the script gets a 400.
+            return Math.min(mock.requests.length, script.length);
         },
         close: () => mock.close(),
     };

package/dist/adapters/codex/mock-model.d.ts

@@ -42,8 +42,9 @@ export declare function parseResponsesRequest(body: string): {
 };
 /**
  * Start the scripted Codex Responses mock on a free port. Each
- * `POST /v1/responses` consumes the next scripted turn (the last turn repeats if
- * codex asks for more); HEAD and any other path get `{}`. Resolves to a handle
+ * `POST /v1/responses` consumes the next scripted turn; one past the end of the
+ * script is a 400, never a copy of the last turn (#340); HEAD and any other path
+ * get `{}`. Resolves to a handle
  * with the base `url`, the `port`, the recorded `requests`, and `close()`.
  */
 export declare function startCodexMock(script: readonly CodexTurn[], opts?: {

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

@@ -22,6 +22,7 @@ exports.startCodexMock = startCodexMock;
  * `src/adapters/codex/runtime.ts` (`codexMockArgs`/`codexMockEnv`).
  */
 const node_http_1 = __importDefault(require("node:http"));
+const script_overrun_js_1 = require("../../core/script-overrun.js");
 const MSG_ID = "msg_mock_1";
 const RESP_ID = "resp_mock_1";
 /**
@@ -183,8 +184,9 @@ function parseResponsesRequest(body) {
 }
 /**
  * Start the scripted Codex Responses mock on a free port. Each
- * `POST /v1/responses` consumes the next scripted turn (the last turn repeats if
- * codex asks for more); HEAD and any other path get `{}`. Resolves to a handle
+ * `POST /v1/responses` consumes the next scripted turn; one past the end of the
+ * script is a 400, never a copy of the last turn (#340); HEAD and any other path
+ * get `{}`. Resolves to a handle
  * with the base `url`, the `port`, the recorded `requests`, and `close()`.
  */
 function startCodexMock(script, opts = {}) {
@@ -204,7 +206,17 @@ function startCodexMock(script, opts = {}) {
             const parsed = parseResponsesRequest(body);
             requests.push(parsed);
             opts.onRequest?.(parsed);
-            const turn = script[Math.min(i, script.length - 1)] ?? { text: "" };
+            const turn = script[i];
+            if (turn === undefined) {
+                const message = (0, script_overrun_js_1.scriptOverrunMessage)({
+                    scripted: script.length,
+                    request: script.length + 1,
+                    lastMessage: parsed.prompt,
+                });
+                res.writeHead(400, { "content-type": "application/json" });
+                res.end(JSON.stringify({ error: { type: "invalid_request_error", message } }));
+                return;
+            }
             i++;
             const model = parsed.model || "gpt-5-codex";
             res.writeHead(200, {

package/dist/cli-main.js

@@ -2671,17 +2671,21 @@ function vigilesWorkflow(plan, harnesses, hasPackageJson) {
   eval-check:
     # Eval staleness gate — real-model evals run LOCALLY on your subscription
     # (\`npx vigiles eval --update\`, which commits a lock); this job VERIFIES those
-    # committed results against the current inputs with NO model call. It stays a
-    # green no-op until you commit your first lock. See docs/harness-testing.md.
+    # committed results against the current inputs with NO model call.
+    # \`--min=0\` is deliberate: a repo with no eval file yet matches nothing, and
+    # \`vigiles eval --check\` fails on an empty match by default (a gate that
+    # verified nothing must not read as a pass). With \`--min=0\` this job is green
+    # until the first \`*.eval.*\` file exists; from then on it is red until that
+    # eval's lock is committed. Raise the floor (\`--min=N\`) once you want
+    # a vanished eval file to fail it. See docs/harness-testing.md.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
-      - uses: zernie/vigiles@v1
-        with:
-          command: eval-check
+      - run: npm install
+      - run: npx vigiles eval --check --min=0
 `
         : "";
     // No selectable jobs (e.g. `--no-lint --no-test`, or `--test` on a repo with no
@@ -5195,10 +5199,11 @@ async function promptYesNo(question) {
  * Resolve the eval LOCK env from the `eval` flags. `--update` records each named
  * eval's report to a committed `.vigiles/eval-locks/<name>.lock.json` (run locally
  * on your subscription); `--check` (CI) verifies the committed result against the
- * current inputs WITHOUT a model call. `--check` is a green NO-OP until the first
- * lock is committed (smooth adoption). Returns the env to thread, or `"skip"` to
- * exit green now. `--check`+`--update` together is a usage error (exit 2). The
- * behavior epoch comes from `.vigilesrc.json` `eval.apiVersion` (committed).
+ * current inputs WITHOUT a model call. `--check` with no lock committed at all is
+ * a FAILURE, not a green no-op ({@link refuseEvalCheckWithoutLocks}, #197): a gate
+ * that has verified nothing must not read as one that passed.
+ * `--check`+`--update` together is a usage error (exit 2). The behavior epoch
+ * comes from `.vigilesrc.json` `eval.apiVersion` (committed).
  */
 function resolveEvalLockEnv(args) {
     const wantCheck = args.includes("--check");
@@ -5207,13 +5212,6 @@ function resolveEvalLockEnv(args) {
         console.error("vigiles eval: --check and --update are mutually exclusive (one verifies, one records).");
         process.exit(2);
     }
-    if (wantCheck &&
-        !(0, eval_lock_js_1.anyLocksCommitted)((0, node_path_1.resolve)(process.cwd(), eval_lock_js_1.DEFAULT_LOCK_DIR))) {
-        console.log("ℹ vigiles eval --check: no committed eval locks found — nothing to verify.\n" +
-            "  Run `vigiles eval --update` locally (on your subscription) and commit the\n" +
-            "  lock to enable the CI staleness gate.");
-        return "skip";
-    }
     const env = {};
     if (wantCheck)
         env.VIGILES_EVAL_LOCK = "check";
@@ -5226,6 +5224,22 @@ function resolveEvalLockEnv(args) {
     }
     return env;
 }
+/**
+ * `eval --check` over eval files when no lock is committed anywhere: every one of
+ * them has no recorded result to compare the current inputs against, so the gate
+ * would verify nothing and pass. It used to return green BEFORE discovery, which
+ * also bypassed the empty-match failure. Once any lock exists, a file without one
+ * already fails as "lock missing" in the eval itself. Exits 1; returns otherwise.
+ */
+function refuseEvalCheckWithoutLocks(args, evalCount) {
+    if (!args.includes("--check"))
+        return;
+    if ((0, eval_lock_js_1.anyLocksCommitted)((0, node_path_1.resolve)(process.cwd(), eval_lock_js_1.DEFAULT_LOCK_DIR)))
+        return;
+    console.error(`✗ vigiles eval --check: ${String(evalCount)} eval file(s) have no recorded result — no eval lock is committed, so there is nothing to verify the current inputs against.\n` +
+        "  Run `vigiles eval --update` locally (on your subscription) and commit the lock(s).");
+    process.exit(1);
+}
 /**
  * Turn a completed run into `.vigiles/coverage.json` — the composition root for
  * the execution tier of coverage (`coverage-artifact.ts`).
@@ -5400,6 +5414,31 @@ function gitHead(cwd) {
         return "";
     }
 }
+/**
+ * Why a `vigiles test` / `vigiles eval` run matched no file — the message names
+ * what was looked for, so a stale path, a wrong glob and an empty default
+ * discovery each say so. A DIRECTORY is the one stale-looking target whose cause
+ * we actually know, so it is said instead of the three guesses: `vigiles test .`
+ * used to reach `spawn("node", ["."])` and surface Node's module-resolution stack.
+ */
+function emptyMatchMessage(kind, targets, defaultGlob) {
+    const dirs = targets.filter((a) => (0, node_fs_1.lstatSync)(a, { throwIfNoEntry: false })?.isDirectory() === true);
+    if (dirs.length > 0) {
+        return (`✗ vigiles ${kind}: ${dirs.join(", ")} ${dirs.length === 1 ? "is a directory" : "are directories"} — ` +
+            `pass a file, or a glob like "${defaultGlob}".\n` +
+            `  A directory is not a script; nothing ran.`);
+    }
+    const expected = `  If an empty match is expected here, say so with --min=0.`;
+    if (targets.length === 0) {
+        return (`✗ vigiles ${kind}: NOTHING matched the default glob ${defaultGlob}\n` +
+            `  Nothing ran. An empty run is not a pass: a renamed or moved file looks like this.\n` +
+            expected);
+    }
+    return (`✗ vigiles ${kind}: ${String(targets.length)} target(s) given and NOTHING matched — ` +
+        `${targets.join(", ")}\n` +
+        `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
+        expected);
+}
 async function handleRunScripts(kind, args, restArgs, excludes) {
     const cwd = process.cwd();
     // The ignore file keeps NEW copies of `.vigiles/` local files out of git, but
@@ -5420,14 +5459,10 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
     // Harness/eval scripts may be authored in JS or TS (see run-scripts.ts).
     const defaultGlob = (0, run_scripts_js_1.scriptGlob)(kind === "test" ? "harness" : "eval");
     // The eval LOCK flags (`--check`/`--update`) are resolved BEFORE file discovery
-    // so mutual-exclusion + the cold-start no-op are honored regardless of file
-    // count. Returns the env to thread to scripts, or `"skip"` to exit green now.
+    // so mutual-exclusion (exit 2) is honored regardless of file count.
     let lockEnv = {};
     if (kind === "eval") {
-        const r = resolveEvalLockEnv(args);
-        if (r === "skip")
-            return;
-        lockEnv = r;
+        lockEnv = resolveEvalLockEnv(args);
     }
     // A script under an excluded path is not DISCOVERED (a vendored corpus's own
     // harness must not run as ours), but a script you NAME still runs (#192).
@@ -5449,44 +5484,33 @@ async function handleRunScripts(kind, args, restArgs, excludes) {
         process.exit(1);
     }
     if (files.length === 0) {
-        // 🔴 ASKING FOR SOMETHING AND GETTING NOTHING IS A FAILURE; FINDING NOTHING IS NOT.
-        // The two cases were collapsed into one silent exit 0, and the collapse cost a real
-        // repository three days of green CI verifying zero files: a named step ran
+        // 🔴 A RUN THAT MATCHES NO FILE IS A FAILURE, NAMED OR NOT.
+        // An empty match used to be one silent exit 0, and it cost a real repository three
+        // days of green CI verifying zero files: a named step ran
         // `vigiles test .claude/pipeline/skills.harness.mjs` after that file had been split
         // into one-per-skill, printed "No **/*.harness.* files found" and passed, right next
-        // to a step that was red for the same root cause.
-        //
-        // They are different states. A POSITIONAL argument is a claim that something is there —
-        // when nothing matches it, the path is stale, the glob is wrong, or the run never
-        // reached its target, and every one of those is a defect. Bare discovery finding
-        // nothing is just an empty repository, which is a legitimate place to stand and must
-        // stay quiet.
+        // to a step that was red for the same root cause. The first repair failed only the
+        // NAMED case and kept bare discovery quiet ("an empty repository is a legitimate
+        // place to stand") — and bare `vigiles test` is the line `init` writes into CI, so
+        // the same green no-op was one rename away from the default setup (#197).
         //
-        // This is the default the field settled on: Jest and Vitest FAIL on no tests found and
-        // make you opt in with `--passWithNoTests`; pytest exits 5. `--min=0` remains the
-        // explicit opt-out here, so no new flag is introduced by this change.
-        // `minFlag`, not `minRequired`: 0 is both the DEFAULT and the explicit opt-out, so the
-        // VALUE cannot tell them apart — only the flag's presence can. (Caught by a control:
-        // the first version read `minRequired === 0` and made `--min=0` do nothing.)
-        if (restArgs.length > 0 && minFlag === undefined) {
-            // A DIRECTORY is the one stale-looking target whose cause we actually know,
-            // so say it instead of listing the three guesses. `vigiles test .` used to
-            // reach `spawn("node", ["."])` and surface Node's module-resolution stack;
-            // the generic message above would now be true but unhelpful.
-            const dirs = restArgs.filter((a) => (0, node_fs_1.lstatSync)(a, { throwIfNoEntry: false })?.isDirectory() === true);
-            console.error(dirs.length > 0
-                ? `✗ vigiles ${kind}: ${dirs.join(", ")} ${dirs.length === 1 ? "is a directory" : "are directories"} — ` +
-                    `pass a file, or a glob like "${defaultGlob}".\n` +
-                    `  A directory is not a script; nothing ran.`
-                : `✗ vigiles ${kind}: ${String(restArgs.length)} target(s) given and NOTHING matched — ` +
-                    `${restArgs.join(", ")}\n` +
-                    `  Nothing ran. A stale path, a wrong glob, or a moved file all look like this.\n` +
-                    `  If an empty match is expected here, say so with --min=0.`);
+        // This is the default the field settled on: Jest and Vitest FAIL on no tests found
+        // and make you opt in with `--passWithNoTests`; pytest exits 5. Here there is no
+        // such flag (a person who wants an empty run does not call the command), and
+        // `--min=0` — the existing floor, spelled as zero — is the only way to say an empty
+        // match is expected. `minFlag`, not `minRequired`: 0 is both the DEFAULT and that
+        // explicit opt-out, so the VALUE cannot tell them apart — only the flag's presence
+        // can. (Caught by a control: the first version read `minRequired === 0` and made
+        // `--min=0` do nothing.)
+        if (minFlag === undefined) {
+            console.error(emptyMatchMessage(kind, restArgs, defaultGlob));
             process.exit(1);
         }
         console.log(`No ${defaultGlob} files found.`);
         return;
     }
+    if (kind === "eval")
+        refuseEvalCheckWithoutLocks(args, files.length);
     // Consent gate for a bare `vigiles eval`: it runs the REAL model on your
     // subscription, and a no-target run discovered the whole tree — so never fan out
     // over an unbounded glob without explicit intent. Mirrors audit's read-vs-run

package/dist/core/harness-driver.d.ts

@@ -107,8 +107,11 @@ export interface HarnessDriverContext {
     readonly cwd: string;
     /** Whether a settings file was written (CC: pass `--settings`). */
     readonly hasSettings: boolean;
-    /** Tools the agent may use. */
-    readonly tools: readonly string[];
+    /**
+     * The ONLY tools the agent has, when the spec lists them; undefined = no
+     * restriction (every tool is offered, the default four are pre-approved).
+     */
+    readonly tools?: readonly string[];
     /** Capture the full event transcript instead of just the final result. */
     readonly transcript: boolean;
     /** Path to a plugin dir to install natively, if any. */

package/dist/core/script-overrun.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Running past the end of a scripted model is an error.
+ *
+ * A harness test scripts the turns the agent should take, then asserts on what
+ * happened. When the agent asks for more turns than the script has, the mock
+ * used to answer with a copy of the LAST turn: a looping agent (a Stop hook
+ * that keeps blocking, a retry, a reaction to a tool result) then ran on turns
+ * nobody scripted, a final `{ tool }` re-ran its side effect, and the test went
+ * green over a run it never described (#340). Pure and shared by both mocks
+ * (Anthropic Messages, OpenAI Responses) and the runner that fails the test.
+ */
+import type { ModelRequest } from "./harness-driver.js";
+/** The first request the script could not answer. */
+export interface ScriptOverrun {
+    /** How many turns the script had. */
+    readonly scripted: number;
+    /** 1-based number of the agent request that had no turn left. */
+    readonly request: number;
+    /** The last message that request carried (what the agent was reacting to). */
+    readonly lastMessage: string;
+}
+/** Why a test failed because the agent outran its script. */
+export declare function scriptOverrunMessage(o: ScriptOverrun): string;
+/**
+ * The first agent request past the end of a script of `scripted` turns, read
+ * off the recorded requests (side-channel calls never consume a turn, so they
+ * do not count). Undefined when the agent stayed inside the script.
+ */
+export declare function findScriptOverrun(scripted: number, requests: readonly ModelRequest[]): ScriptOverrun | undefined;
+/** {@link findScriptOverrun} and {@link scriptOverrunMessage} in one: the message, or undefined. */
+export declare function overrunMessageFor(scripted: number, requests: readonly ModelRequest[]): string | undefined;
+//# sourceMappingURL=script-overrun.d.ts.map

package/dist/core/script-overrun.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptOverrunMessage = scriptOverrunMessage;
+exports.findScriptOverrun = findScriptOverrun;
+exports.overrunMessageFor = overrunMessageFor;
+const MAX_QUOTED = 160;
+const quote = (text) => {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > MAX_QUOTED ? `${flat.slice(0, MAX_QUOTED)}...` : flat;
+};
+/** Why a test failed because the agent outran its script. */
+function scriptOverrunMessage(o) {
+    const last = o.lastMessage.trim() === ""
+        ? ""
+        : ` The request carried this last message: "${quote(o.lastMessage)}".`;
+    return (`the agent asked for more model turns than the script has: ${String(o.scripted)} turn(s) scripted, ` +
+        `and agent request #${String(o.request)} had none left.${last} ` +
+        "The mock does not repeat the last turn, because a looping agent would then pass on turns nobody scripted. " +
+        "Script every turn the agent should take.");
+}
+/**
+ * The first agent request past the end of a script of `scripted` turns, read
+ * off the recorded requests (side-channel calls never consume a turn, so they
+ * do not count). Undefined when the agent stayed inside the script.
+ */
+function findScriptOverrun(scripted, requests) {
+    const agent = requests.filter((r) => r.sideChannel !== true);
+    const first = agent[scripted];
+    if (first === undefined)
+        return undefined;
+    return {
+        scripted,
+        request: scripted + 1,
+        lastMessage: first.messages.at(-1)?.text ?? "",
+    };
+}
+/** {@link findScriptOverrun} and {@link scriptOverrunMessage} in one: the message, or undefined. */
+function overrunMessageFor(scripted, requests) {
+    const overrun = findScriptOverrun(scripted, requests);
+    return overrun === undefined ? undefined : scriptOverrunMessage(overrun);
+}
+//# sourceMappingURL=script-overrun.js.map

package/dist/doc-test-script-coverage.d.ts

@@ -20,7 +20,7 @@
  * anywhere in the prose counts, because a name like `test:harness` cannot
  * collide with an English word the way `test` and `audit` do. The only thing the
  * lookarounds buy is that a LONGER script name is never read as a shorter one
- * (`test:cli-e2e` does not document `test:e2e`).
+ * (`test:unit-extra` does not document `test:unit`).
  *
  * Scope is the `test:` PREFIX, deliberately. Bare `npm test` is the vitest
  * suite, named in the map as prose; every other script (`build`, `lint`,

package/dist/doc-test-script-coverage.js

@@ -21,7 +21,7 @@
  * anywhere in the prose counts, because a name like `test:harness` cannot
  * collide with an English word the way `test` and `audit` do. The only thing the
  * lookarounds buy is that a LONGER script name is never read as a shorter one
- * (`test:cli-e2e` does not document `test:e2e`).
+ * (`test:unit-extra` does not document `test:unit`).
  *
  * Scope is the `test:` PREFIX, deliberately. Bare `npm test` is the vitest
  * suite, named in the map as prose; every other script (`build`, `lint`,

package/dist/eval-lock.d.ts

@@ -116,12 +116,11 @@ export declare function lockPath(dir: string, name: string): string;
  */
 export declare function readLock(dir: string, name: string): EvalLock | null;
 /**
- * Whether ANY lock has been committed under `dir`. The CI staleness gate
- * (`eval --check`) uses this to stay a NO-OP until the feature is in use: a repo
- * that has never run `eval --update` has no locks, so there is nothing to verify
- * and CI passes green. Once the first lock is committed, every named eval is held
- * to having a fresh one (a new unlocked eval then reads as stale). The graduated,
- * opt-in-by-committing behavior that keeps a fresh `init` from going red.
+ * Whether ANY lock has been committed under `dir`. `eval --check` fails when none
+ * is (#197): with no lock there is no recorded result to verify the current inputs
+ * against, so a pass would mean nothing was checked. Once the first lock is
+ * committed, every named eval is held to having a fresh one (a new unlocked eval
+ * then reads as stale). The edit-time nudge also stays silent until then.
  */
 export declare function anyLocksCommitted(dir: string): boolean;
 /**

package/dist/eval-lock.js

@@ -130,12 +130,11 @@ function readLock(dir, name) {
     return obj;
 }
 /**
- * Whether ANY lock has been committed under `dir`. The CI staleness gate
- * (`eval --check`) uses this to stay a NO-OP until the feature is in use: a repo
- * that has never run `eval --update` has no locks, so there is nothing to verify
- * and CI passes green. Once the first lock is committed, every named eval is held
- * to having a fresh one (a new unlocked eval then reads as stale). The graduated,
- * opt-in-by-committing behavior that keeps a fresh `init` from going red.
+ * Whether ANY lock has been committed under `dir`. `eval --check` fails when none
+ * is (#197): with no lock there is no recorded result to verify the current inputs
+ * against, so a pass would mean nothing was checked. Once the first lock is
+ * committed, every named eval is held to having a fresh one (a new unlocked eval
+ * then reads as stale). The edit-time nudge also stays silent until then.
  */
 function anyLocksCommitted(dir) {
     return countLocks(dir) > 0;

package/dist/harness-test.d.ts

@@ -52,7 +52,18 @@ export interface HarnessTestSpec {
     readonly model: readonly ModelTurn[];
     /** The user prompt. Default: "go". */
     readonly prompt?: string;
-    /** Tools the agent may use. Default: Read Edit Write Bash. */
+    /**
+     * The ONLY tools the agent has, when you list them: a tool left out is not
+     * offered (`claude --tools`, Claude Code 2.0.31+), `[]` is refused, and a
+     * scripted call to a tool the list leaves out throws before the run starts.
+     * Omitted, nothing is withheld: every tool is offered and Read, Edit, Write and
+     * Bash are pre-approved. Each listed tool is also pre-approved
+     * (`--allowedTools`), so it does not stop on a permission prompt; a permission
+     * rule such as `Bash(git *)` keeps its specifier for the approval and is
+     * offered as plain `Bash`. An MCP tool is not a built-in: left out, it is still
+     * offered but not approved, so a call to it is refused for permission rather
+     * than as "No such tool".
+     */
     readonly allowedTools?: readonly string[];
     /**
      * Capture the full event transcript (`--output-format stream-json`) into
@@ -119,6 +130,27 @@ export declare function parseResultEvent(stdout: string): Record<string, unknown
 /** The agent's final answer text from a transcript / result object, or "". */
 export declare function parseOutput(stdout: string): string;
 export declare function parseHooks(stdout: string): HookFire[];
+/**
+ * The names `--tools` should offer for an `allowedTools` list. `--allowedTools`
+ * takes permission rules (`Bash(git *)`); `--tools` takes tool NAMES, and a rule
+ * with a specifier there makes the CLI offer no tools at all. So the specifier is
+ * dropped (`Bash(git *)` → `Bash`) and repeats collapse. Pure.
+ */
+export declare function toolAvailabilityList(allowed: readonly string[]): readonly string[];
+/**
+ * A scripted call to a tool an EXPLICIT `allowedTools` does not offer. The CLI
+ * answers it with "No such tool available" and the run goes on, so a test that
+ * scripts the call and then asserts on something else passes over a step that
+ * never happened. Returns the message to throw, or undefined. MCP tools are not
+ * built-ins, so `--tools` does not withhold them and they are skipped. Pure.
+ */
+export declare function unofferedScriptedTool(model: readonly ModelTurn[], allowed: readonly string[] | undefined): string | undefined;
+/**
+ * A run on a `claude` that predates `--tools` exits at argument parsing, and
+ * commander's "unknown option" says nothing about WHY vigiles passed it. Returns
+ * the message to throw, or undefined when the run did not die that way. Pure.
+ */
+export declare function unsupportedToolsFlag(stderr: string): string | undefined;
 /**
  * The `claude` CLI argv for a harness run (shared by the direct and sandboxed
  * paths). `ANTHROPIC_BASE_URL` is set by the caller's environment / wrapper, not
@@ -170,6 +202,8 @@ export interface RunHarnessTestOptions {
      */
     readonly adapter?: HarnessAdapter;
 }
+/** Say so on stderr when side-channel calls arrived and no script turn was served. */
+export declare function warnUnconsumed(count: number, sideChannelCount: number): void;
 /**
  * Run the real agent CLI against a scripted mock model, with the given fixture
  * and settings (hooks). Deterministic — same script, same result. Adapter-driven

package/dist/harness-test.js

@@ -6,10 +6,14 @@ exports.parseSubagents = parseSubagents;
 exports.parseResultEvent = parseResultEvent;
 exports.parseOutput = parseOutput;
 exports.parseHooks = parseHooks;
+exports.toolAvailabilityList = toolAvailabilityList;
+exports.unofferedScriptedTool = unofferedScriptedTool;
+exports.unsupportedToolsFlag = unsupportedToolsFlag;
 exports.buildClaudeArgs = buildClaudeArgs;
 exports.parseClaudeRun = parseClaudeRun;
 exports.harnessSpawnEnv = harnessSpawnEnv;
 exports.claudeAvailable = claudeAvailable;
+exports.warnUnconsumed = warnUnconsumed;
 exports.runHarnessTest = runHarnessTest;
 exports.runHarnessTestIn = runHarnessTestIn;
 exports.runHarness = runHarness;
@@ -49,6 +53,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const adapter_conformance_js_1 = require("./adapter-conformance.js");
 const check_count_js_1 = require("./check-count.js");
+const script_overrun_js_1 = require("./core/script-overrun.js");
 const coverage_probe_js_1 = require("./coverage-probe.js");
 const runtime_js_1 = require("./adapters/claude-code/runtime.js");
 const mock_model_js_1 = require("./mock-model.js");
@@ -274,6 +279,51 @@ function parseHooks(stdout) {
     }
     return hooks;
 }
+/**
+ * The first `claude` that has `--tools` (print mode). Found by diffing the
+ * published `@anthropic-ai/claude-code` tarballs: 2.0.30 has no such option,
+ * 2.0.31 does (the changelog does not list it; its 2.1.0 entry only extends the
+ * flag to interactive mode).
+ */
+const TOOLS_FLAG_MIN_CLAUDE = "2.0.31";
+/**
+ * The names `--tools` should offer for an `allowedTools` list. `--allowedTools`
+ * takes permission rules (`Bash(git *)`); `--tools` takes tool NAMES, and a rule
+ * with a specifier there makes the CLI offer no tools at all. So the specifier is
+ * dropped (`Bash(git *)` → `Bash`) and repeats collapse. Pure.
+ */
+function toolAvailabilityList(allowed) {
+    const names = allowed.map((rule) => rule.replace(/\(.*$/, "").trim());
+    return [...new Set(names.filter((n) => n !== ""))];
+}
+/**
+ * A scripted call to a tool an EXPLICIT `allowedTools` does not offer. The CLI
+ * answers it with "No such tool available" and the run goes on, so a test that
+ * scripts the call and then asserts on something else passes over a step that
+ * never happened. Returns the message to throw, or undefined. MCP tools are not
+ * built-ins, so `--tools` does not withhold them and they are skipped. Pure.
+ */
+function unofferedScriptedTool(model, allowed) {
+    if (allowed === undefined)
+        return undefined;
+    const offered = toolAvailabilityList(allowed);
+    const at = model.findIndex((t) => t.tool !== undefined &&
+        !t.tool.startsWith("mcp__") &&
+        !offered.includes(t.tool));
+    return at < 0
+        ? undefined
+        : `scripted call to "${model[at]?.tool ?? ""}" on turn ${String(at + 1)}, but this run offers only: ${offered.join(", ")} — add it to allowedTools`;
+}
+/**
+ * A run on a `claude` that predates `--tools` exits at argument parsing, and
+ * commander's "unknown option" says nothing about WHY vigiles passed it. Returns
+ * the message to throw, or undefined when the run did not die that way. Pure.
+ */
+function unsupportedToolsFlag(stderr) {
+    return /unknown option '--tools'/.test(stderr)
+        ? `this \`claude\` does not know \`--tools\`, which runHarnessTest uses to withhold every tool not in \`allowedTools\` (#252). Update Claude Code to ${TOOLS_FLAG_MIN_CLAUDE} or newer. Running without it would hand the agent every tool while the test reads as if it were fenced.`
+        : undefined;
+}
 /**
  * The `claude` CLI argv for a harness run (shared by the direct and sandboxed
  * paths). `ANTHROPIC_BASE_URL` is set by the caller's environment / wrapper, not
@@ -293,8 +343,17 @@ function buildClaudeArgs(spec, hasSettings) {
             ? ["--plugin-dir", (0, node_path_1.resolve)(spec.pluginDir)]
             : []),
         ...(hasSettings ? ["--settings", "settings.json"] : []),
-        // A permission allowlist: an empty one approves nothing, so the flag is
-        // left out (a bare `--allowedTools` exits before any model turn).
+        // An EXPLICIT list restricts: `--tools` is the AVAILABILITY list, a tool left
+        // out is not offered at all. `--allowedTools` only PRE-APPROVES (it never
+        // restricts), so on its own it left every unnamed tool runnable (#252). An
+        // empty list is `--tools ""` = no tools. With no list, nothing is withheld:
+        // the default four are pre-approved and every other tool stays available.
+        ...(spec.allowedTools === undefined
+            ? []
+            : ["--tools", toolAvailabilityList(spec.allowedTools).join(",")]),
+        // Pre-approval for the offered tools, so none stops on a permission prompt
+        // (headless). An empty one approves nothing, so the flag is left out (a bare
+        // `--allowedTools` exits before any model turn).
         ...(tools.length === 0 ? [] : ["--allowedTools", ...tools]),
     ];
 }
@@ -415,6 +474,26 @@ exports.claudeCodeDriver = {
     parseRun: parseClaudeRun,
     available: claudeAvailable,
 };
+/** Say so on stderr when side-channel calls arrived and no script turn was served. */
+function warnUnconsumed(count, sideChannelCount) {
+    const unconsumed = (0, mock_model_js_1.scriptUnconsumedWarning)(count, sideChannelCount);
+    if (unconsumed !== undefined)
+        console.error(unconsumed);
+}
+/**
+ * A run that proves nothing about the script fails the test instead of coming
+ * back as a result: the `claude` on PATH predates `--tools` (#252), or the agent
+ * asked for a model turn the script did not have and the mock answered with an
+ * error rather than an invented turn (#340). Removes the run's directory, since
+ * no result is handed back to clean it up.
+ */
+function assertRunSound(cwd, stderr, scripted, modelRequests) {
+    const problem = unsupportedToolsFlag(stderr) ?? (0, script_overrun_js_1.overrunMessageFor)(scripted, modelRequests);
+    if (problem === undefined)
+        return;
+    (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
+    throw new Error(problem);
+}
 /* v8 ignore start -- spawns the real agent CLI + filesystem; exercised by the
    claude-backed + gated codex suites, excluded from the deterministic coverage
    gate (the parse helpers above carry the testable logic). */
@@ -457,8 +536,22 @@ function makeResult(cwd, out, parsed, turns, modelRequests) {
  * only — requesting confinement for another harness throws.
  */
 async function runHarnessTest(spec, opts = {}) {
+    refuseUnrunnableSpec(spec);
     return runHarnessTestIn(spec, opts, "inherit");
 }
+/**
+ * The scripted model tells an agent turn from the CLI's own bookkeeping calls by
+ * the tools the request declares (`isMainLoopRequest`). An agent with none is
+ * never served a script turn, and the run would decide on nothing.
+ */
+function refuseUnrunnableSpec(spec) {
+    if (spec.allowedTools?.length === 0) {
+        throw new Error("allowedTools: [] leaves the agent with no tools, and the scripted model only serves a turn to a request that declares tools — no script turn would be consumed. Name the tools the agent has.");
+    }
+    const unoffered = unofferedScriptedTool(spec.model, spec.allowedTools);
+    if (unoffered !== undefined)
+        throw new Error(unoffered);
+}
 /**
  * {@link runHarnessTest} with the run's HOME chosen by the caller — see
  * {@link HarnessRunHome}. Not on a public entry point: the one caller that needs
@@ -491,13 +584,12 @@ async function runHarnessTestIn(spec, opts, home) {
     const { files, settings, check } = fixtureFor(spec, opts.adapter);
     const cwd = (0, tmp_root_js_1.makeTmpDir)("harness");
     writeFixture(cwd, files, settings);
-    const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
     const timeoutMs = spec.timeoutMs ?? 60000;
     const buildArgs = (mockArgs) => driver.buildArgs({
         prompt: spec.prompt ?? "go",
         cwd,
         hasSettings: settings !== undefined,
-        tools,
+        tools: spec.allowedTools,
         transcript: spec.transcript ?? false,
         pluginDir: spec.pluginDir,
         mockArgs,
@@ -519,9 +611,8 @@ async function runHarnessTestIn(spec, opts, home) {
         // the direct one stays right. Same recovery feeds the unconsumed-script
         // warning, which the sandbox path could not emit at all before.
         const { count, sideChannelCount } = (0, mock_model_js_1.splitRequestCounts)(out.requests);
-        const unconsumed = (0, mock_model_js_1.scriptUnconsumedWarning)(count, sideChannelCount);
-        if (unconsumed !== undefined)
-            console.error(unconsumed);
+        warnUnconsumed(count, sideChannelCount);
+        assertRunSound(cwd, "", spec.model.length, out.requests);
         return check(makeResult(cwd, out, parseClaudeRun(out.stdout), count, out.requests));
     }
     // Direct path: mock runs in this process; the agent reaches it over localhost.
@@ -539,9 +630,8 @@ async function runHarnessTestIn(spec, opts, home) {
         // looks empty. `scriptUnconsumedWarning` names the one shape that produces
         // it (every request arriving without tool declarations, so nothing looked
         // like an agent turn) instead of leaving it to be rediscovered.
-        const unconsumed = (0, mock_model_js_1.scriptUnconsumedWarning)(mock.count, mock.sideChannelCount ?? 0);
-        if (unconsumed !== undefined)
-            console.error(unconsumed);
+        warnUnconsumed(mock.count, mock.sideChannelCount ?? 0);
+        assertRunSound(cwd, out.stderr, spec.model.length, mock.requests);
         return check(makeResult(cwd, out, driver.parseRun(out.stdout), mock.count, [
             ...mock.requests,
         ]));

package/dist/mock-model.d.ts

@@ -78,7 +78,10 @@ export declare function extractRequest(body: {
 }): ModelRequest;
 /**
  * Start the scripted mock on a free port. Each MAIN-LOOP `/v1/messages` POST
- * consumes the next turn (the last turn repeats if the client asks for more);
+ * consumes the next turn; one past the end of the script is answered with a
+ * non-retryable API error, never a copy of the last turn (#340 — a looping
+ * agent would pass on turns nobody scripted), and `runHarnessTest` then fails
+ * the test from the recorded requests ({@link findScriptOverrun});
  * a SIDE-CHANNEL POST — the CLI's own bookkeeping calls, see
  * {@link isMainLoopRequest} — is answered from outside the script and consumes
  * nothing. Resolves to a handle with the base `url` and a `close()`.

package/dist/mock-model.js

@@ -28,6 +28,7 @@ exports.startMock = startMock;
  * and echoing the requested model.
  */
 const node_http_1 = __importDefault(require("node:http"));
+const script_overrun_js_1 = require("./core/script-overrun.js");
 /** Build a scripted model from an ordered list of turns. */
 function scriptModel(turns) {
     return [...turns];
@@ -388,9 +389,41 @@ function extractRequest(body) {
         : [];
     return { system: flattenContent(body.system), messages };
 }
+/**
+ * The 400 body for an agent request past the end of the script: an API error,
+ * because the CLI retries 429/5xx and an invented turn would let the agent act on
+ * a step nobody scripted (#340). Pure.
+ */
+function pastScriptBody(scripted, request) {
+    const message = (0, script_overrun_js_1.scriptOverrunMessage)({
+        scripted,
+        request: scripted + 1,
+        lastMessage: request.messages.at(-1)?.text ?? "",
+    });
+    return JSON.stringify({
+        type: "error",
+        error: { type: "invalid_request_error", message },
+    });
+}
+/** Does a message's content carry a tool result (the agent reacting to a tool)? */
+function endsWithToolResult(content) {
+    return JSON.stringify(content ?? "").includes('"tool_result"');
+}
+/** The JSON body of a request, `{}` for the HEAD / health checks that have none. */
+function parseReqBody(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Start the scripted mock on a free port. Each MAIN-LOOP `/v1/messages` POST
- * consumes the next turn (the last turn repeats if the client asks for more);
+ * consumes the next turn; one past the end of the script is answered with a
+ * non-retryable API error, never a copy of the last turn (#340 — a looping
+ * agent would pass on turns nobody scripted), and `runHarnessTest` then fails
+ * the test from the recorded requests ({@link findScriptOverrun});
  * a SIDE-CHANNEL POST — the CLI's own bookkeeping calls, see
  * {@link isMainLoopRequest} — is answered from outside the script and consumes
  * nothing. Resolves to a handle with the base `url` and a `close()`.
@@ -406,13 +439,7 @@ function startMock(script, opts = {}) {
             const url = req.url ?? "";
             const isCount = url.includes("count_tokens");
             const isMessages = url.includes("/v1/messages") && !isCount;
-            let reqBody = {};
-            try {
-                reqBody = JSON.parse(body);
-            }
-            catch {
-                /* HEAD / health checks have no JSON body */
-            }
+            const reqBody = parseReqBody(body);
             if (req.method === "HEAD" || (!isMessages && !isCount)) {
                 res.writeHead(200, { "content-type": "application/json" });
                 res.end("{}");
@@ -445,13 +472,17 @@ function startMock(script, opts = {}) {
                     jsonTurn(res, reply, model);
                 return;
             }
-            const last = JSON.stringify(reqBody.messages?.at(-1)?.content ?? "");
+            const turn = script[i];
+            if (turn === undefined) {
+                res.writeHead(400, { "content-type": "application/json" });
+                res.end(pastScriptBody(script.length, request));
+                return;
+            }
             opts.onTurn?.({
                 n: i,
                 stream: reqBody.stream === true,
-                hasToolResult: last.includes('"tool_result"'),
+                hasToolResult: endsWithToolResult(reqBody.messages?.at(-1)?.content),
             });
-            const turn = script[Math.min(i, script.length - 1)] ?? { text: "" };
             i++;
             if (reqBody.stream === true)
                 streamTurn(res, turn, model);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "34.0.0",
+  "version": "35.0.0",
   "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",
@@ -83,7 +83,6 @@
     "test:unit": "npm run build && vitest run --project unit",
     "test:integration": "npm run build && vitest run --project integration",
     "test:e2e": "npm run build && vitest run --project e2e",
-    "test:cli-e2e": "bash test/e2e/run.sh",
     "test:harness": "npm run build && node dist/cli.js test",
     "test:eval": "npm run build && node dist/cli.js eval --all",
     "test:vitest": "npm run build && vitest run --project runners",