vigiles 2.6.0 → 3.0.0

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

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeEgressAvailable = probeEgressAvailable;
+exports.egressAvailable = egressAvailable;
+exports.parseGetent = parseGetent;
+exports.resolveAllow = resolveAllow;
+exports.parseResolvers = parseResolvers;
+exports.buildEgressNft = buildEgressNft;
+exports.buildEgressBwrapArgv = buildEgressBwrapArgv;
+exports.parseNftCounters = parseNftCounters;
+exports.countersToResult = countersToResult;
+/**
+ * vigiles — allowlisted, recorded egress for a confined hook (`egress: { allow }`).
+ *
+ * The deny-all wall (`--unshare-all`) and the `recordEgress` proxy both BLOCK; a
+ * hook whose setup needs a real `npm install` can't be tested under either. This
+ * is the in-between: let traffic actually reach the network, but **only to an
+ * allowlist**, and **record** it — with the boundary at the packet layer so it
+ * can't be bypassed by a raw socket (an `HTTP_PROXY` allowlist can).
+ *
+ * How it works (proven in `research/spikes/sandbox-network-allowlist.sh`):
+ * `slirp4netns --configure` attaches a `tap` to the bwrap netns (rootless egress
+ * via a userspace TCP/IP stack), then an `nft` ruleset INSIDE the netns — a
+ * `policy drop` output chain that `accept`s only the resolved allowlist IPs (plus
+ * loopback + the DNS resolver) and `log`+`drop`s the rest — is the hard wall. The
+ * per-rule `counter`s read back which allowlisted hosts were actually reached and
+ * how much was dropped.
+ *
+ * This module holds the PURE seams — resolution parsing, ruleset generation,
+ * counter parsing, result mapping — so the enforcement logic is unit-tested
+ * without a sandbox. The orchestration (`src/egress-entry.ts`) needs real bwrap +
+ * slirp4netns + nft and is covered by the gated integration test.
+ *
+ * Honest limits (see `docs/sandboxing.md`): the allowlist is resolved to IPs at
+ * launch (a host whose DNS rotates outside the run's window could miss an IP —
+ * the dynamic resolver-pinned set is the documented next layer). The record names
+ * the allowlisted hosts that were reached and counts what was dropped, but does
+ * not yet name the DROPPED hosts (that needs the in-netns DNS-query log).
+ */
+const node_child_process_1 = require("node:child_process");
+let cachedEgressAvailable;
+/** Does a binary resolve on PATH? (probe via `command -v`, no output kept.) */
+function hasBinary(name) {
+    try {
+        return ((0, node_child_process_1.spawnSync)("sh", ["-c", `command -v ${name}`], {
+            stdio: "ignore",
+            timeout: 5_000,
+        }).status === 0);
+    }
+    catch {
+        /* v8 ignore next -- spawnSync only throws on a fork failure */
+        return false;
+    }
+}
+/**
+ * Whether this host can run the allowlisted-egress sandbox: it needs the same
+ * bubblewrap confinement the other tiers use PLUS `slirp4netns` (the rootless
+ * gateway) and `nft` (the packet-layer allowlist). Cached — the answer can't
+ * change within a run. `available` is injected so the bwrap probe isn't repeated.
+ */
+function probeEgressAvailable(available) {
+    /* v8 ignore next -- non-Linux has no bwrap/slirp; CI/coverage runs on Linux */
+    if (process.platform !== "linux")
+        return false;
+    return available && hasBinary("slirp4netns") && hasBinary("nft");
+}
+/** Cached {@link probeEgressAvailable}. `available` = the bwrap-sandbox probe. */
+function egressAvailable(available) {
+    if (cachedEgressAvailable === undefined) {
+        cachedEgressAvailable = probeEgressAvailable(available);
+    }
+    return cachedEgressAvailable;
+}
+/**
+ * Parse `getent ahosts <host>` output into the unique IPs, split by family. The
+ * first whitespace token of each line is an address; `:` marks IPv6. Pure, so the
+ * resolution-parsing is unit-tested without touching DNS.
+ */
+function parseGetent(stdout) {
+    const v4 = new Set();
+    const v6 = new Set();
+    for (const line of stdout.split("\n")) {
+        const ip = line.trim().split(/\s+/)[0];
+        if (!ip)
+            continue;
+        if (ip.includes(":"))
+            v6.add(ip);
+        else if (/^\d+\.\d+\.\d+\.\d+$/.test(ip))
+            v4.add(ip);
+    }
+    return { v4: [...v4], v6: [...v6] };
+}
+/** Resolve a host to IPs via the system resolver (`getent`, synchronous). */
+function getentLookup(host) {
+    /* v8 ignore start -- shells out to the real resolver; the parse is parseGetent */
+    const res = (0, node_child_process_1.spawnSync)("getent", ["ahosts", host], {
+        encoding: "utf-8",
+        timeout: 10_000,
+    });
+    return parseGetent(res.stdout ?? "");
+    /* v8 ignore stop */
+}
+/**
+ * Resolve every allowlisted host to IPs. The lookup is injectable so the
+ * empty-result / family-split behaviour is unit-tested with a fake resolver.
+ */
+function resolveAllow(hosts, lookup = getentLookup) {
+    return hosts.map((host) => {
+        const { v4, v6 } = lookup(host);
+        return { host, v4, v6 };
+    });
+}
+/** A loopback nameserver (127.0.0.0/8 or ::1) — e.g. systemd-resolved's
+ * 127.0.0.53 stub. Unreachable from inside the slirp4netns netns (which runs
+ * with `--disable-host-loopback`), so it must never be used as the in-netns
+ * resolver. GitHub-hosted runners ship exactly this stub, which is why the
+ * egress tests saw zero packets there. */
+function isLoopbackResolver(ip) {
+    return ip === "::1" || /^127\./.test(ip);
+}
+/**
+ * Nameservers usable from INSIDE the egress netns. Parses a resolv.conf body but
+ * drops loopback stubs (see {@link isLoopbackResolver}) — they can't be reached
+ * across the namespace — and falls back to a public resolver (8.8.8.8, which
+ * slirp4netns NATs out) when nothing routable remains.
+ */
+function parseResolvers(resolvConf) {
+    const out = [];
+    for (const line of resolvConf.split("\n")) {
+        const m = /^\s*nameserver\s+(\S+)/.exec(line);
+        if (m && !isLoopbackResolver(m[1]))
+            out.push(m[1]);
+    }
+    return out.length > 0 ? out : ["8.8.8.8"];
+}
+/** Escape an nft set comment label so a hostname can't break the ruleset. */
+function nftLabel(host) {
+    return host.replace(/[^A-Za-z0-9._:-]/g, "_");
+}
+/**
+ * Build the nftables ruleset that enforces the allowlist INSIDE the netns: a
+ * `policy drop` output chain that accepts loopback, established replies, DNS to
+ * the resolvers, and each allowlisted host's resolved IPs (a per-host `counter` +
+ * `comment "allow:<host>"` so the read-back maps traffic to a name), then a
+ * catch-all `log`+`counter`+`drop`. v4 and v6 are separate rules (an `inet` set
+ * can't mix families) sharing the host's comment. Pure → the ruleset is asserted
+ * in a unit test.
+ */
+function buildEgressNft(opts) {
+    const lines = [
+        "table inet vig {",
+        "  chain output {",
+        "    type filter hook output priority 0; policy drop;",
+        '    oifname "lo" accept',
+        "    ct state established,related accept",
+    ];
+    for (const r of opts.resolvers) {
+        const fam = r.includes(":") ? "ip6" : "ip";
+        lines.push(`    ${fam} daddr ${r} udp dport 53 counter accept comment "dns"`);
+        lines.push(`    ${fam} daddr ${r} tcp dport 53 counter accept comment "dns"`);
+    }
+    for (const h of opts.allow) {
+        const label = nftLabel(h.host);
+        if (h.v4.length > 0) {
+            lines.push(`    ip daddr { ${h.v4.join(", ")} } counter accept comment "allow:${label}"`);
+        }
+        if (h.v6.length > 0) {
+            lines.push(`    ip6 daddr { ${h.v6.join(", ")} } counter accept comment "allow:${label}"`);
+        }
+    }
+    lines.push('    log prefix "vig-drop " counter drop');
+    lines.push("  }", "}");
+    return lines.join("\n") + "\n";
+}
+/**
+ * Assemble the full bwrap argv for an allowlisted-egress run: the shared
+ * confinement args, the hook's added-back env, `CAP_NET_ADMIN` (so the in-netns
+ * wrapper can load nft), `--info-fd 3` (so the orchestrator learns the child PID
+ * to hand slirp4netns), the `VIG_*` paths the wrapper reads, and the trailing
+ * `sh -c <wrapper>`. Pure (the bwrap/setenv args are computed by the caller), so
+ * the assembled shape — caps, info-fd, the VIG_* env, the wrapper payload — is
+ * asserted in a unit test.
+ */
+function buildEgressBwrapArgv(opts) {
+    return [
+        ...opts.base,
+        // Override the host's /etc/resolv.conf (often a 127.0.0.53 stub) with one
+        // listing only netns-routable resolvers — placed after `base` so it shadows
+        // the `--ro-bind / /` copy.
+        "--ro-bind",
+        opts.resolvConf,
+        "/etc/resolv.conf",
+        "--cap-add",
+        "CAP_NET_ADMIN",
+        ...opts.setenv,
+        "--setenv",
+        "VIG_NETREADY",
+        opts.files.netready,
+        "--setenv",
+        "VIG_NFT",
+        opts.files.nft,
+        "--setenv",
+        "VIG_EVENT",
+        opts.files.event,
+        "--setenv",
+        "VIG_COUNTERS",
+        opts.files.counters,
+        "--setenv",
+        "VIG_IODIR",
+        opts.files.ioDir,
+        "--setenv",
+        "VIG_HOOK",
+        opts.command,
+        "--info-fd",
+        "3",
+        "sh",
+        "-c",
+        opts.wrapper,
+    ];
+}
+const COUNTER = /counter packets (\d+) bytes (\d+)/;
+const ALLOW_COMMENT = /comment "allow:([^"]+)"/;
+/**
+ * Parse `nft list chain inet vig output` back into per-host allowed counters and
+ * the aggregate drop counter. Sums multiple rules that share a host comment (the
+ * v4 + v6 split). Pure, so the read-back is unit-tested without a sandbox.
+ */
+function parseNftCounters(nftText) {
+    const allowed = new Map();
+    let dropped = { packets: 0, bytes: 0 };
+    for (const line of nftText.split("\n")) {
+        const c = COUNTER.exec(line);
+        if (!c)
+            continue;
+        const packets = Number(c[1]);
+        const bytes = Number(c[2]);
+        const a = ALLOW_COMMENT.exec(line);
+        if (a) {
+            const prev = allowed.get(a[1]) ?? { packets: 0, bytes: 0 };
+            allowed.set(a[1], {
+                packets: prev.packets + packets,
+                bytes: prev.bytes + bytes,
+            });
+        }
+        else if (line.includes("vig-drop") || /\bdrop\b/.test(line)) {
+            dropped = {
+                packets: dropped.packets + packets,
+                bytes: dropped.bytes + bytes,
+            };
+        }
+    }
+    return {
+        allowed: [...allowed.entries()].map(([host, v]) => ({ host, ...v })),
+        dropped,
+    };
+}
+/**
+ * Map parsed counters to the run result: one {@link EgressAttempt} per
+ * allowlisted host that saw traffic (`allowed: true`, with its packet/byte
+ * counts), plus the aggregate dropped counter. `ts` is stamped once per run (the
+ * counters are end-of-run totals, not per-connection events). Pure.
+ */
+function countersToResult(counters, now) {
+    const egress = counters.allowed
+        .filter((a) => a.packets > 0)
+        .map((a) => ({
+        host: a.host,
+        port: 0,
+        ts: now,
+        allowed: true,
+        packets: a.packets,
+        bytes: a.bytes,
+    }));
+    return { egress, egressDropped: counters.dropped };
+}
+//# sourceMappingURL=egress.js.map

package/dist/{eval-cache.d.ts → adapters/claude-code/eval-cache.d.ts}

@@ -1,4 +1,4 @@
-import { type SHA256Hash } from "./hash.js";
+import { type SHA256Hash } from "../../core/hash.js";
 import type { RunOut } from "./eval.js";
 /** Cache behaviour: never touch the cache / read-only / read-and-write. */
 export type CacheMode = "off" | "read" | "readwrite";

package/dist/{eval-cache.js → adapters/claude-code/eval-cache.js}

@@ -24,7 +24,7 @@ exports.restoreDir = restoreDir;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const hash_js_1 = require("./hash.js");
+const hash_js_1 = require("../../core/hash.js");
 const MAX_SNAPSHOT_FILE_BYTES = 1024 * 1024;
 const SKIP_DIRS = new Set(["node_modules", ".git"]);
 /**

package/dist/{eval.d.ts → adapters/claude-code/eval.d.ts}

@@ -213,6 +213,14 @@ export interface TriggerRateSpec {
     readonly pluginDir: string;
     /** The varied prompts to test the trigger against. */
     readonly prompts: readonly string[];
+    /**
+     * Optional *irrelevant* prompts the skill should **not** fire on — the
+     * precision side of triggering. Firing on these is a false positive (a skill
+     * whose description is too broad and hijacks unrelated work). When given, the
+     * report adds {@link TriggerRateReport.falsePositiveRate} and
+     * {@link TriggerRateReport.precision}; `prompts` alone measures recall only.
+     */
+    readonly irrelevantPrompts?: readonly string[];
     /** Did the behaviour fire on this run? e.g. `(t) => skillResolved(t, "x:y")`. */
     readonly fired: (trace: Trace) => boolean;
     /** Trials per prompt. Default 1. */
@@ -235,17 +243,33 @@ export interface PromptTriggerStat {
     readonly rate: number;
 }
 export interface TriggerRateReport {
-    /** Overall fraction of runs in which the behaviour fired (0..1). */
+    /** Overall fraction of relevant runs in which the behaviour fired (recall, 0..1). */
     readonly rate: number;
-    /** Total runs (prompts × trials). */
+    /** Total relevant runs (prompts × trials). */
     readonly n: number;
     readonly perPrompt: readonly PromptTriggerStat[];
+    /**
+     * Fraction of *irrelevant* runs that wrongly fired (lower is better). Present
+     * only when {@link TriggerRateSpec.irrelevantPrompts} was given.
+     */
+    readonly falsePositiveRate?: number;
+    /**
+     * `relevantFired / (relevantFired + irrelevantFired)` — of all firings, the
+     * share on the right prompts. Present only when irrelevant prompts were given
+     * AND something fired (undefined when nothing fired at all). Pairs with `rate`
+     * (recall) to catch a skill that fires on everything _or_ nothing.
+     */
+    readonly precision?: number;
+    /** Per-prompt stats for the irrelevant set. Present with irrelevant prompts. */
+    readonly perIrrelevant?: readonly PromptTriggerStat[];
 }
 /**
  * Trigger-rate orchestration — every prompt × trial via `runner`, the `fired`
  * predicate evaluated per run and aggregated into an overall + per-prompt rate.
- * Exported with an injectable `runner` so the loop is unit-testable without a
- * model; `measureTriggerRate` is this with the real agent runner.
+ * With `irrelevantPrompts`, also runs the precision side (firing there is a false
+ * positive) and adds `falsePositiveRate` + `precision`. Exported with an
+ * injectable `runner` so the loop is unit-testable without a model;
+ * `measureTriggerRate` is this with the real agent runner.
  */
 export declare function measureTriggerRateWith(spec: TriggerRateSpec, runner: AgentRunner): Promise<TriggerRateReport>;
 /**

package/dist/{eval.js → adapters/claude-code/eval.js}

@@ -40,6 +40,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const plugin_loader_js_1 = require("./plugin-loader.js");
+const runtime_js_1 = require("./runtime.js");
 const harness_test_js_1 = require("./harness-test.js");
 const eval_cache_js_1 = require("./eval-cache.js");
 function writeFiles(cwd, files) {
@@ -72,7 +73,7 @@ function spawnAgent(a) {
             "--allowedTools",
             ...a.tools,
         ];
-        const child = (0, node_child_process_1.spawn)("claude", args, {
+        const child = (0, node_child_process_1.spawn)(runtime_js_1.claudeCodeRuntime.agentBinary, args, {
             cwd: a.cwd,
             env: process.env,
             stdio: ["ignore", "pipe", "pipe"],
@@ -401,53 +402,78 @@ function formatEvalReport(report) {
     }
     return lines.join("\n");
 }
-/**
- * Trigger-rate orchestration — every prompt × trial via `runner`, the `fired`
- * predicate evaluated per run and aggregated into an overall + per-prompt rate.
- * Exported with an injectable `runner` so the loop is unit-testable without a
- * model; `measureTriggerRate` is this with the real agent runner.
- */
-async function measureTriggerRateWith(spec, runner) {
-    const trials = spec.trials ?? 1;
-    const model = spec.model ?? "haiku";
-    const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash", "Skill"];
-    const timeoutMs = spec.timeoutMs ?? 240000;
-    const spacing = (spec.spacingSec ?? 4) * 1000;
+/** Run one prompt set × trials through `runner`, aggregating fired counts. */
+async function runTriggerSet(prompts, cfg, runner) {
     const perPrompt = [];
     let firedTotal = 0;
     let n = 0;
-    for (const prompt of spec.prompts) {
+    for (const prompt of prompts) {
         let fired = 0;
-        for (let t = 0; t < trials; t++) {
+        for (let t = 0; t < cfg.trials; t++) {
             const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-trigger-"));
             try {
                 const out = await runner({
                     task: prompt,
                     cwd,
-                    model,
-                    tools,
+                    model: cfg.model,
+                    tools: cfg.tools,
                     hasSettings: false,
-                    pluginDir: spec.pluginDir,
-                    timeoutMs,
+                    pluginDir: cfg.pluginDir,
+                    timeoutMs: cfg.timeoutMs,
                 });
-                if (spec.fired(makeContext(cwd, out)))
+                if (cfg.fired(makeContext(cwd, out)))
                     fired++;
             }
             finally {
                 (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
-                await sleep(spacing);
+                await sleep(cfg.spacing);
             }
         }
         perPrompt.push({
             prompt,
             fired,
-            trials,
-            rate: trials > 0 ? fired / trials : 0,
+            trials: cfg.trials,
+            rate: cfg.trials > 0 ? fired / cfg.trials : 0,
         });
         firedTotal += fired;
-        n += trials;
+        n += cfg.trials;
     }
-    return { rate: n > 0 ? firedTotal / n : 0, n, perPrompt };
+    return { perPrompt, fired: firedTotal, n };
+}
+/**
+ * Trigger-rate orchestration — every prompt × trial via `runner`, the `fired`
+ * predicate evaluated per run and aggregated into an overall + per-prompt rate.
+ * With `irrelevantPrompts`, also runs the precision side (firing there is a false
+ * positive) and adds `falsePositiveRate` + `precision`. Exported with an
+ * injectable `runner` so the loop is unit-testable without a model;
+ * `measureTriggerRate` is this with the real agent runner.
+ */
+async function measureTriggerRateWith(spec, runner) {
+    const cfg = {
+        trials: spec.trials ?? 1,
+        model: spec.model ?? "haiku",
+        tools: spec.allowedTools ?? ["Read", "Edit", "Write", "Bash", "Skill"],
+        timeoutMs: spec.timeoutMs ?? 240000,
+        spacing: (spec.spacingSec ?? 4) * 1000,
+        pluginDir: spec.pluginDir,
+        fired: spec.fired,
+    };
+    const relevant = await runTriggerSet(spec.prompts, cfg, runner);
+    const base = {
+        rate: relevant.n > 0 ? relevant.fired / relevant.n : 0,
+        n: relevant.n,
+        perPrompt: relevant.perPrompt,
+    };
+    if ((spec.irrelevantPrompts?.length ?? 0) === 0)
+        return base;
+    const irrelevant = await runTriggerSet(spec.irrelevantPrompts ?? [], cfg, runner);
+    const fires = relevant.fired + irrelevant.fired;
+    return {
+        ...base,
+        falsePositiveRate: irrelevant.n > 0 ? irrelevant.fired / irrelevant.n : 0,
+        precision: fires > 0 ? relevant.fired / fires : undefined,
+        perIrrelevant: irrelevant.perPrompt,
+    };
 }
 /* v8 ignore start -- real claude subprocess; thin wrapper over measureTriggerRateWith */
 /**
@@ -465,6 +491,16 @@ function formatTriggerRateReport(report) {
     for (const p of report.perPrompt) {
         lines.push(`  ${p.rate.toFixed(2)}  ${p.prompt.slice(0, 60)}`);
     }
+    if (report.falsePositiveRate !== undefined) {
+        const fpr = (report.falsePositiveRate * 100).toFixed(0);
+        const prec = report.precision === undefined
+            ? "n/a"
+            : `${(report.precision * 100).toFixed(0)}%`;
+        lines.push(`false-positive: ${fpr}%  precision: ${prec}`);
+        for (const p of report.perIrrelevant ?? []) {
+            lines.push(`  ${p.rate.toFixed(2)}  [irrelevant] ${p.prompt.slice(0, 48)}`);
+        }
+    }
     return lines.join("\n");
 }
 //# sourceMappingURL=eval.js.map

package/dist/{harness-test.d.ts → adapters/claude-code/harness-test.d.ts}

@@ -1,6 +1,8 @@
-import { type ModelTurn, type ModelRequest } from "./mock-model.js";
+import type { HarnessAdapter } from "../../core/adapter.js";
+import type { HarnessTestDriver, ToolCall, HookFire, ParsedRun, ModelTurn, ModelRequest } from "../../core/harness-driver.js";
 import { type SandboxMode } from "./sandbox.js";
-export { scriptModel, type ModelTurn, type ModelRequest, } from "./mock-model.js";
+export { scriptModel } from "./mock-model.js";
+export type { ModelTurn, ModelRequest, ToolCall, HookFire, HarnessTestDriver, } from "../../core/harness-driver.js";
 export { loadPlugin, resolveHarness } from "./plugin-loader.js";
 export { decideSandbox, specTrusted, sandboxAvailable, type SandboxMode, } from "./sandbox.js";
 export interface HarnessTestSpec {
@@ -54,24 +56,6 @@ export interface HarnessTestSpec {
      */
     readonly sandbox?: SandboxMode;
 }
-/**
- * A hook invocation observed during the run, recorded (not inferred) from the
- * `hook_response` system events the CLI emits in the stream — so a test can
- * assert which hook fired and whether it blocked, instead of inferring it from a
- * marker file the hook had to write.
- */
-export interface HookFire {
-    /** The hook label, e.g. `"PreToolUse:Edit"` (`Event:Matcher`). */
-    readonly name: string;
-    /** The hook event, e.g. `"PreToolUse"`, `"PostToolUse"`, `"Stop"`. */
-    readonly event: string;
-    /** The hook process exit code (2 = block), or undefined if not reported. */
-    readonly exitCode: number | undefined;
-    /** Whether the hook blocked / errored (exit ≠ 0 or outcome "error"). */
-    readonly blocked: boolean;
-    /** What the hook printed (its block reason / diagnostic), or "". */
-    readonly output: string;
-}
 /**
  * The observable record of ONE run — the unified shape produced by BOTH testing
  * tiers: `runHarnessTest`'s result and `runEval`'s `measure` ctx (`eval.ts`)
@@ -124,15 +108,6 @@ export interface HarnessTestResult extends Trace {
     /** Remove the temp working dir. */
     cleanup(): void;
 }
-/** A tool the agent invoked, paired with its result (transcript mode only). */
-export interface ToolCall {
-    readonly name: string;
-    readonly input: unknown;
-    /** The tool_result text ("" if none / not captured). */
-    readonly resultText: string;
-    /** Whether the tool_result came back flagged as an error. */
-    readonly isError: boolean;
-}
 /**
  * Parse `--output-format stream-json` (the `transcript: true` output) into the
  * tools the agent invoked, each joined to its result by id. Returns [] for the
@@ -155,16 +130,37 @@ export declare function parseHooks(stdout: string): HookFire[];
  * here. Pure, so the arg shape is unit-tested.
  */
 export declare function buildClaudeArgs(spec: HarnessTestSpec, hasSettings: boolean): string[];
-/** Whether the `claude` CLI is available — harness tests need it. */
+/** Parse the `claude` stdout/stream into the unified trace fields. */
+export declare function parseClaudeRun(stdout: string): ParsedRun;
+/** Whether the agent CLI is available — harness tests need it. */
 export declare function claudeAvailable(): boolean;
 /**
- * Run the real `claude` CLI against a scripted mock model, with the given
- * fixture and settings (hooks). Deterministic — same script, same result.
+ * The Claude Code `HarnessTestDriver`: the existing argv/mock/parse seams bundled
+ * behind the port the adapter-driven runner dispatches through. Behaviourally
+ * identical to the previous hard-wired path.
+ */
+export declare const claudeCodeDriver: HarnessTestDriver;
+/** Options for {@link runHarnessTest}. */
+export interface RunHarnessTestOptions {
+    /**
+     * Which harness to drive. Defaults to Claude Code. Pass `codexAdapter`
+     * (`vigiles/codex`) to drive real `codex exec` against its Responses mock.
+     * The adapter must support pillar 2 (`capabilities.harnessTesting`) and carry
+     * a `harnessTestDriver`.
+     */
+    readonly adapter?: HarnessAdapter;
+}
+/**
+ * Run the real agent CLI against a scripted mock model, with the given fixture
+ * and settings (hooks). Deterministic — same script, same result. Adapter-driven
+ * (`opts.adapter`, default Claude Code): the Claude Code path is unchanged
+ * (incl. the safe-by-default sandbox); pass `codexAdapter` to drive real codex.
  *
- * Safe by default: an external `plugin` / `pluginDir` brings in untrusted
- * third-party hooks and is confined under bubblewrap (`spec.sandbox`, default
- * `"auto"`); if no sandbox is available the run REFUSES rather than executing
- * unconfined. See `src/sandbox.ts`.
+ * Safe by default (Claude Code): an external `plugin` / `pluginDir` brings in
+ * untrusted third-party hooks and is confined under bubblewrap (`spec.sandbox`,
+ * default `"auto"`); if no sandbox is available the run REFUSES rather than
+ * executing unconfined. See `src/sandbox.ts`. The sandbox path is Claude Code
+ * only — requesting confinement for another harness throws.
  */
-export declare function runHarnessTest(spec: HarnessTestSpec): Promise<HarnessTestResult>;
+export declare function runHarnessTest(spec: HarnessTestSpec, opts?: RunHarnessTestOptions): Promise<HarnessTestResult>;
 //# sourceMappingURL=harness-test.d.ts.map