vigiles 2.5.0 → 2.6.0

package/dist/eval-baseline.d.ts

@@ -0,0 +1,68 @@
+import type { EvalReport } from "./eval.js";
+import { type Comparison } from "./stats.js";
+/** Bumped only on a breaking change to the on-disk shape. */
+export declare const BASELINE_VERSION = 1;
+/** The committed baseline: the recorded `EvalReport`s, keyed by report name. */
+export interface BaselineFile {
+    readonly version: number;
+    /** ISO-8601 timestamp the baseline was recorded (provenance / future trend). */
+    readonly recordedAt: string;
+    /** Recorded reports, keyed by `report.name` (so multiple eval files coexist). */
+    readonly reports: Record<string, EvalReport>;
+}
+/** How a metric moved between baseline and current run. */
+export type DiffStatus = "regressed" | "improved" | "unchanged";
+/** One arm×metric comparison of a current run against the baseline. */
+export interface MetricDiff {
+    /** The `report.name` this entry belongs to. */
+    readonly report: string;
+    readonly arm: string;
+    readonly metric: string;
+    readonly status: DiffStatus;
+    /** Welch comparison, current vs. baseline (`delta = current − baseline`). */
+    readonly comparison: Comparison;
+}
+export interface BaselineDiff {
+    /** Every arm×metric present in BOTH the baseline and the current run. */
+    readonly entries: readonly MetricDiff[];
+    /** The subset that regressed (significant move in the bad direction). */
+    readonly regressions: readonly MetricDiff[];
+    /** The subset that improved (significant move in the good direction). */
+    readonly improvements: readonly MetricDiff[];
+    /** True when there are no regressions — the gate. */
+    readonly passed: boolean;
+}
+export interface DiffOptions {
+    /** Significance level for the Welch test. Default 0.05. */
+    readonly alpha?: number;
+    /**
+     * Metrics where a DECREASE is the improvement (e.g. `cost`, `latency`,
+     * `turns`). For these, a significant increase is the regression. Everything
+     * else is treated as higher-is-better.
+     */
+    readonly lowerIsBetter?: readonly string[];
+}
+/** Build a `BaselineFile` envelope from a run's reports (keyed by name). */
+export declare function toBaselineFile(reports: readonly EvalReport[], recordedAt?: string): BaselineFile;
+/** Parse + validate a baseline JSON string (throws on a bad version/shape). */
+export declare function parseBaselineFile(json: string): BaselineFile;
+/**
+ * Diff a current run against a committed baseline. Compares every arm×metric
+ * present in both (by report name), flagging a *significant* move in the
+ * undesired direction as a regression. Metrics absent from one side are skipped
+ * (a new arm/metric is not a regression).
+ */
+export declare function diffReports(baseline: BaselineFile, current: readonly EvalReport[], opts?: DiffOptions): BaselineDiff;
+/** Format a baseline diff as a compact console report. */
+export declare function formatBaselineDiff(diff: BaselineDiff): string;
+/**
+ * Render a baseline diff as JUnit XML — one `<testcase>` per arm×metric, a
+ * `<failure>` for each regression. Lets a CI provider show eval regressions in
+ * the same place as unit-test failures.
+ */
+export declare function diffToJUnit(diff: BaselineDiff): string;
+/** Read + parse a baseline file, or null if it doesn't exist yet. */
+export declare function readBaseline(path: string): BaselineFile | null;
+/** Write reports as the committed baseline (pretty JSON, parent dirs created). */
+export declare function writeBaseline(path: string, reports: readonly EvalReport[]): void;
+//# sourceMappingURL=eval-baseline.d.ts.map

package/dist/eval-baseline.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASELINE_VERSION = void 0;
+exports.toBaselineFile = toBaselineFile;
+exports.parseBaselineFile = parseBaselineFile;
+exports.diffReports = diffReports;
+exports.formatBaselineDiff = formatBaselineDiff;
+exports.diffToJUnit = diffToJUnit;
+exports.readBaseline = readBaseline;
+exports.writeBaseline = writeBaseline;
+/**
+ * vigiles — eval regression gating (Phase C).
+ *
+ * The eval tier reports mean ± se per arm; `src/stats.ts` turns a gap into a
+ * significance verdict. This module points that machinery at a *committed
+ * baseline*: record one run's `EvalReport`s to `.vigiles/eval-baseline.json`,
+ * then on a later run flag any arm×metric that moved **significantly in the bad
+ * direction** vs. that baseline. "jest snapshots for agent behaviour, with a real
+ * noise floor" — a bare pass-rate can't tell a true regression from sampling
+ * noise, but a Welch t-test over the two runs' summary stats can.
+ *
+ * Pure + model-free (the diff/serialize/JUnit are fully unit-tested); the only
+ * side effects are the two small fs helpers (`readBaseline` / `writeBaseline`).
+ * Reuses `welchTTest` from `src/stats.ts` — the current run is the "arm", the
+ * baseline is the "baseline", so `delta = current − baseline`.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const stats_js_1 = require("./stats.js");
+/** Bumped only on a breaking change to the on-disk shape. */
+exports.BASELINE_VERSION = 1;
+/** Build a `BaselineFile` envelope from a run's reports (keyed by name). */
+function toBaselineFile(reports, recordedAt = new Date().toISOString()) {
+    const byName = {};
+    for (const r of reports)
+        byName[r.name] = r;
+    return { version: exports.BASELINE_VERSION, recordedAt, reports: byName };
+}
+/** Parse + validate a baseline JSON string (throws on a bad version/shape). */
+function parseBaselineFile(json) {
+    const data = JSON.parse(json);
+    if (typeof data !== "object" || data === null) {
+        throw new Error("baseline: expected a JSON object");
+    }
+    const obj = data;
+    if (obj.version !== exports.BASELINE_VERSION) {
+        throw new Error(`baseline: unsupported version ${String(obj.version)} (expected ${String(exports.BASELINE_VERSION)})`);
+    }
+    if (typeof obj.reports !== "object" || obj.reports === null) {
+        throw new Error("baseline: missing `reports`");
+    }
+    return {
+        version: exports.BASELINE_VERSION,
+        recordedAt: typeof obj.recordedAt === "string" ? obj.recordedAt : "",
+        reports: obj.reports,
+    };
+}
+/** Classify one comparison given the metric's direction. */
+function classify(cmp, lowerIsBetter) {
+    if (!cmp.significant || cmp.delta === 0)
+        return "unchanged";
+    const improved = lowerIsBetter ? cmp.delta < 0 : cmp.delta > 0;
+    return improved ? "improved" : "regressed";
+}
+/** Append a diff entry for every arm×metric common to both reports. */
+function collectReportDiffs(baseline, current, cfg, out) {
+    for (const [arm, curArm] of Object.entries(current.arms)) {
+        const baseArm = baseline.arms[arm];
+        if (!baseArm)
+            continue;
+        for (const [metric, curStat] of Object.entries(curArm.stats)) {
+            const baseStat = baseArm.stats[metric];
+            if (!baseStat)
+                continue;
+            const comparison = (0, stats_js_1.welchTTest)(curStat, baseStat, cfg.alpha);
+            out.push({
+                report: current.name,
+                arm,
+                metric,
+                status: classify(comparison, cfg.lower.has(metric)),
+                comparison,
+            });
+        }
+    }
+}
+/**
+ * Diff a current run against a committed baseline. Compares every arm×metric
+ * present in both (by report name), flagging a *significant* move in the
+ * undesired direction as a regression. Metrics absent from one side are skipped
+ * (a new arm/metric is not a regression).
+ */
+function diffReports(baseline, current, opts = {}) {
+    const cfg = {
+        alpha: opts.alpha ?? 0.05,
+        lower: new Set(opts.lowerIsBetter ?? []),
+    };
+    const entries = [];
+    for (const cur of current) {
+        const base = baseline.reports[cur.name];
+        if (base)
+            collectReportDiffs(base, cur, cfg, entries);
+    }
+    const regressions = entries.filter((e) => e.status === "regressed");
+    const improvements = entries.filter((e) => e.status === "improved");
+    return {
+        entries,
+        regressions,
+        improvements,
+        passed: regressions.length === 0,
+    };
+}
+const STATUS_MARK = {
+    regressed: "✗",
+    improved: "✓",
+    unchanged: "·",
+};
+function formatDelta(c) {
+    const sign = c.delta >= 0 ? "+" : "";
+    return `Δ=${sign}${c.delta.toFixed(3)} p=${c.pValue.toFixed(3)}`;
+}
+/** Format a baseline diff as a compact console report. */
+function formatBaselineDiff(diff) {
+    const head = diff.passed
+        ? "baseline OK — no significant regressions"
+        : `baseline FAIL — ${String(diff.regressions.length)} regression(s)`;
+    const lines = [head];
+    for (const e of diff.entries) {
+        lines.push(`  ${STATUS_MARK[e.status]} ${e.report}/${e.arm}/${e.metric}  ${formatDelta(e.comparison)}`);
+    }
+    return lines.join("\n");
+}
+function xmlEscape(s) {
+    return s
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function junitCase(e) {
+    const name = xmlEscape(`${e.report}.${e.arm}.${e.metric}`);
+    const open = `  <testcase classname="${xmlEscape(e.report)}" name="${name}">`;
+    if (e.status !== "regressed")
+        return `${open}</testcase>`;
+    const msg = xmlEscape(`regression: ${formatDelta(e.comparison)}`);
+    return `${open}\n    <failure message="${msg}"/>\n  </testcase>`;
+}
+/**
+ * Render a baseline diff as JUnit XML — one `<testcase>` per arm×metric, a
+ * `<failure>` for each regression. Lets a CI provider show eval regressions in
+ * the same place as unit-test failures.
+ */
+function diffToJUnit(diff) {
+    const cases = diff.entries.map(junitCase).join("\n");
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuite name="vigiles-eval" tests="${String(diff.entries.length)}" failures="${String(diff.regressions.length)}">`,
+        cases,
+        "</testsuite>",
+        "",
+    ].join("\n");
+}
+/** Read + parse a baseline file, or null if it doesn't exist yet. */
+function readBaseline(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    return parseBaselineFile((0, node_fs_1.readFileSync)(path, "utf-8"));
+}
+/** Write reports as the committed baseline (pretty JSON, parent dirs created). */
+function writeBaseline(path, reports) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, JSON.stringify(toBaselineFile(reports), null, 2) + "\n");
+}
+//# sourceMappingURL=eval-baseline.js.map

package/dist/harness-assert.d.ts

@@ -15,11 +15,14 @@
  */
 import { type HarnessTestSpec, type HarnessTestResult, type ToolCall, type Trace } from "./harness-test.js";
 import type { EvalReport, TriggerRateReport } from "./eval.js";
-import type { HookRunResult } from "./run-hook.js";
+import type { HookRunResult, EgressAttempt } from "./run-hook.js";
 import type { OutputContract } from "./spec.js";
 import { type ParsedAgentResult } from "./agent-result.js";
+import { type BaselineFile, type DiffOptions } from "./eval-baseline.js";
 export { compareArms } from "./stats.js";
 export type { Comparison } from "./stats.js";
+export { diffReports, toBaselineFile, parseBaselineFile, readBaseline, writeBaseline, formatBaselineDiff, diffToJUnit, } from "./eval-baseline.js";
+export type { BaselineFile, BaselineDiff, MetricDiff, DiffStatus, DiffOptions, } from "./eval-baseline.js";
 /**
  * Run a harness test, hand the result to `fn`, and always clean up the sandbox.
  * Returns whatever `fn` returns. Use this instead of calling `cleanup()` by
@@ -36,6 +39,28 @@ export declare function assertServedTurns(r: HarnessTestResult, n: number): void
 export declare function assertHookBlocked(r: HookRunResult): void;
 /** Assert a `runHook` result allowed (did not block). */
 export declare function assertHookAllowed(r: HookRunResult): void;
+/** Anything carrying recorded egress attempts (a runHook recordEgress result). */
+interface HasEgress {
+    readonly egress: readonly EgressAttempt[];
+}
+/** The `host:port` strings a run attempted, e.g. `["registry.npmjs.org:443"]`. */
+export declare function egressHosts(r: HasEgress): string[];
+/** Assert the confined run made NO network egress attempt at all. */
+export declare function assertNoEgress(r: HasEgress): void;
+/**
+ * Assert every egress attempt went to an allowed host. `allowed` matches a host
+ * (exact string or regex), or a specific `host:port`. Any attempt outside the
+ * allowlist fails, naming the offender — exfil / unexpected-registry detection.
+ */
+export declare function assertEgressOnly(r: HasEgress, allowed: ReadonlyArray<string | RegExp>): void;
+/** Anything carrying recorded file writes (a confined runHook result). */
+interface HasWrites {
+    readonly filesWritten: readonly string[];
+}
+/** Assert the run wrote NO file matching `pattern` (substring or regex). */
+export declare function assertNoWrite(r: HasWrites, pattern: string | RegExp): void;
+/** Assert every file the run wrote matches one of `allowed` (substring or regex). */
+export declare function assertWroteOnly(r: HasWrites, allowed: ReadonlyArray<string | RegExp>): void;
 /**
  * Assert the worker's output is a success result, and return its `value`. With a
  * `contract`, the value is validated against the success shape (a wrong/missing
@@ -207,6 +232,15 @@ export declare function assertImproves(report: EvalReport, opts: {
     significant?: boolean;
     alpha?: number;
 }): void;
+/**
+ * Assert the current run has not *regressed* against a committed baseline — the
+ * CI gate (Phase C). A regression is an arm×metric that moved **significantly in
+ * the bad direction** vs. `baseline` (Welch t-test, so sampling noise doesn't
+ * trip it; see `src/eval-baseline.ts`). Higher is better by default; list
+ * `lowerIsBetter` metrics (cost/latency) to flip them. Load the baseline with
+ * `readBaseline(path)` and record a fresh one with `writeBaseline(path, reports)`.
+ */
+export declare function assertNoRegression(current: EvalReport | readonly EvalReport[], baseline: BaselineFile, opts?: DiffOptions): void;
 /**
  * Assert a skill/behaviour triggered on at least `min` (0..1) of its runs — the
  * reliability gate for a skill's *activation* (does its description fire on the

package/dist/harness-assert.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.vigilesMatchers = exports.compareArms = void 0;
+exports.vigilesMatchers = exports.diffToJUnit = exports.formatBaselineDiff = exports.writeBaseline = exports.readBaseline = exports.parseBaselineFile = exports.toBaselineFile = exports.diffReports = exports.compareArms = void 0;
 exports.withHarness = withHarness;
 exports.assertCreated = assertCreated;
 exports.assertNotCreated = assertNotCreated;
 exports.assertServedTurns = assertServedTurns;
 exports.assertHookBlocked = assertHookBlocked;
 exports.assertHookAllowed = assertHookAllowed;
+exports.egressHosts = egressHosts;
+exports.assertNoEgress = assertNoEgress;
+exports.assertEgressOnly = assertEgressOnly;
+exports.assertNoWrite = assertNoWrite;
+exports.assertWroteOnly = assertWroteOnly;
 exports.assertAgentOk = assertAgentOk;
 exports.assertAgentErr = assertAgentErr;
 exports.assertAgentResult = assertAgentResult;
@@ -34,6 +39,7 @@ exports.improvement = improvement;
 exports.significantlyBeats = significantlyBeats;
 exports.assertSignificant = assertSignificant;
 exports.assertImproves = assertImproves;
+exports.assertNoRegression = assertNoRegression;
 exports.assertTriggerRate = assertTriggerRate;
 /**
  * vigiles — runner-agnostic helpers for harness tests / evals.
@@ -53,10 +59,19 @@ exports.assertTriggerRate = assertTriggerRate;
 const harness_test_js_1 = require("./harness-test.js");
 const agent_result_js_1 = require("./agent-result.js");
 const stats_js_1 = require("./stats.js");
+const eval_baseline_js_1 = require("./eval-baseline.js");
 // Re-export the significance primitives so the whole eval-analysis surface lives
 // behind `vigiles/harness-assert` (no separate entry point).
 var stats_js_2 = require("./stats.js");
 Object.defineProperty(exports, "compareArms", { enumerable: true, get: function () { return stats_js_2.compareArms; } });
+var eval_baseline_js_2 = require("./eval-baseline.js");
+Object.defineProperty(exports, "diffReports", { enumerable: true, get: function () { return eval_baseline_js_2.diffReports; } });
+Object.defineProperty(exports, "toBaselineFile", { enumerable: true, get: function () { return eval_baseline_js_2.toBaselineFile; } });
+Object.defineProperty(exports, "parseBaselineFile", { enumerable: true, get: function () { return eval_baseline_js_2.parseBaselineFile; } });
+Object.defineProperty(exports, "readBaseline", { enumerable: true, get: function () { return eval_baseline_js_2.readBaseline; } });
+Object.defineProperty(exports, "writeBaseline", { enumerable: true, get: function () { return eval_baseline_js_2.writeBaseline; } });
+Object.defineProperty(exports, "formatBaselineDiff", { enumerable: true, get: function () { return eval_baseline_js_2.formatBaselineDiff; } });
+Object.defineProperty(exports, "diffToJUnit", { enumerable: true, get: function () { return eval_baseline_js_2.diffToJUnit; } });
 /**
  * Run a harness test, hand the result to `fn`, and always clean up the sandbox.
  * Returns whatever `fn` returns. Use this instead of calling `cleanup()` by
@@ -105,6 +120,46 @@ function assertHookAllowed(r) {
         fail(`expected the hook to allow, but it blocked (exit ${String(r.exitCode)}, decision ${String(r.decision)})`);
     }
 }
+const hostPort = (e) => `${e.host}:${String(e.port)}`;
+/** The `host:port` strings a run attempted, e.g. `["registry.npmjs.org:443"]`. */
+function egressHosts(r) {
+    return r.egress.map(hostPort);
+}
+/** Assert the confined run made NO network egress attempt at all. */
+function assertNoEgress(r) {
+    if (r.egress.length > 0) {
+        fail(`expected no egress, but it tried to reach: ${egressHosts(r).join(", ")}`);
+    }
+}
+/**
+ * Assert every egress attempt went to an allowed host. `allowed` matches a host
+ * (exact string or regex), or a specific `host:port`. Any attempt outside the
+ * allowlist fails, naming the offender — exfil / unexpected-registry detection.
+ */
+function assertEgressOnly(r, allowed) {
+    const ok = (e) => allowed.some((a) => typeof a === "string"
+        ? a === e.host || a === hostPort(e)
+        : a.test(e.host) || a.test(hostPort(e)));
+    const bad = r.egress.filter((e) => !ok(e));
+    if (bad.length > 0) {
+        fail(`egress to non-allowlisted host(s): ${bad.map(hostPort).join(", ")}`);
+    }
+}
+const matches = (f, p) => typeof p === "string" ? f.includes(p) : p.test(f);
+/** Assert the run wrote NO file matching `pattern` (substring or regex). */
+function assertNoWrite(r, pattern) {
+    const bad = r.filesWritten.filter((f) => matches(f, pattern));
+    if (bad.length > 0) {
+        fail(`expected no write matching ${String(pattern)}, but wrote: ${bad.join(", ")}`);
+    }
+}
+/** Assert every file the run wrote matches one of `allowed` (substring or regex). */
+function assertWroteOnly(r, allowed) {
+    const bad = r.filesWritten.filter((f) => !allowed.some((a) => matches(f, a)));
+    if (bad.length > 0) {
+        fail(`run wrote file(s) outside the allowlist: ${bad.join(", ")}`);
+    }
+}
 // --- subagent railway outcome (parse the worker's result block) ------------
 //
 // A subagent with a result() contract ends its turn with a vigiles:ok/err block.
@@ -430,6 +485,26 @@ function assertImproves(report, opts) {
         fail(`expected ${opts.arm} to beat ${opts.baseline} on ${opts.metric} by > ${String(by)}, got ${delta.toFixed(3)}`);
     }
 }
+/**
+ * Assert the current run has not *regressed* against a committed baseline — the
+ * CI gate (Phase C). A regression is an arm×metric that moved **significantly in
+ * the bad direction** vs. `baseline` (Welch t-test, so sampling noise doesn't
+ * trip it; see `src/eval-baseline.ts`). Higher is better by default; list
+ * `lowerIsBetter` metrics (cost/latency) to flip them. Load the baseline with
+ * `readBaseline(path)` and record a fresh one with `writeBaseline(path, reports)`.
+ */
+function assertNoRegression(current, baseline, opts) {
+    const reports = Array.isArray(current)
+        ? current
+        : [current];
+    const diff = (0, eval_baseline_js_1.diffReports)(baseline, reports, opts);
+    if (!diff.passed) {
+        const detail = diff.regressions
+            .map((r) => `${r.report}/${r.arm}/${r.metric} Δ=${r.comparison.delta.toFixed(3)} p=${r.comparison.pValue.toFixed(3)}`)
+            .join("; ");
+        fail(`regression vs baseline: ${detail}`);
+    }
+}
 /**
  * Assert a skill/behaviour triggered on at least `min` (0..1) of its runs — the
  * reliability gate for a skill's *activation* (does its description fire on the

package/dist/linting.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
+ * files. Re-exports the spec builders/types and the compiler under one
+ * concern-named import. The granular paths (`vigiles/spec`, `vigiles/compile`)
+ * keep working; this just groups them so the import name matches the pillar.
+ */
+export * from "./spec.js";
+export * from "./compile.js";
+//# sourceMappingURL=linting.d.ts.map

package/dist/linting.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `vigiles/linting` — Pillar 1 entry point: the **linting layer** for instruction
+ * files. Re-exports the spec builders/types and the compiler under one
+ * concern-named import. The granular paths (`vigiles/spec`, `vigiles/compile`)
+ * keep working; this just groups them so the import name matches the pillar.
+ */
+__exportStar(require("./spec.js"), exports);
+__exportStar(require("./compile.js"), exports);
+//# sourceMappingURL=linting.js.map

package/dist/run-hook.d.ts

@@ -1,3 +1,5 @@
+import { type SandboxMode, type EgressAttempt } from "./sandbox.js";
+export type { EgressAttempt };
 /** A hook event payload (the JSON Claude Code writes to the hook's stdin). */
 export interface HookInput {
     /** e.g. "PreToolUse", "PostToolUse", "Stop", "SessionStart", "PreCompact". */
@@ -38,6 +40,41 @@ export interface RunHookOptions {
     readonly env?: Record<string, string>;
     /** Per-run timeout ms. Default 10000. */
     readonly timeoutMs?: number;
+    /**
+     * Provenance of the hook command. `true` (default) means YOU authored it — the
+     * usual case at this tier, a command written inline in the test — so it runs
+     * directly. `false` marks it foreign (a vendored third-party hook script),
+     * which makes confinement the DEFAULT: with no explicit `sandbox`, an untrusted
+     * hook behaves as `sandbox: "auto"` — confined under bubblewrap, or refused if
+     * none is available — so foreign code is never run unconfined by accident. This
+     * mirrors the harness tier, where trust follows `plugin`/`pluginDir`
+     * provenance (`specTrusted` in `src/sandbox.ts`); the unit tier takes a raw
+     * command string with no provenance signal, so you declare it here.
+     */
+    readonly trusted?: boolean;
+    /**
+     * Confine the hook under bubblewrap (Linux). When unset, the mode follows
+     * {@link RunHookOptions.trusted}: a trusted hook runs directly (`false`), an
+     * untrusted one is confined-or-refused (`"auto"`). Set it explicitly to
+     * override: `"auto"`/`"strict"` force confinement (a no-egress namespace with a
+     * cleared environment — your `opts.env` is added back — or a **refusal** if no
+     * bwrap is available), and `false` is the opt-out that runs even untrusted code
+     * unconfined. macOS/Windows have no bwrap, so `"auto"`/`"strict"` throw there —
+     * see `src/sandbox.ts`.
+     */
+    readonly sandbox?: SandboxMode;
+    /**
+     * Record the hook's network egress. Implies confinement (the recorder lives in
+     * the sandbox netns, so this forces a sandboxed run and refuses if no sandbox is
+     * available). A recording proxy on loopback captures every `host:port` a
+     * proxy-honoring tool (npm/pip/curl/fetch) tries to reach — surfaced as
+     * {@link HookRunResult.egress} — while the netns still **blocks** it (nothing
+     * actually leaves). Use it to test what a hook/skill phones home to, or which
+     * registry an install would hit. Raw-socket egress is blocked but not recorded
+     * (it never reaches the proxy) — the block is the boundary, the record is
+     * best-effort observability over it.
+     */
+    readonly recordEgress?: boolean;
 }
 export interface HookRunResult {
     readonly exitCode: number;
@@ -50,6 +87,17 @@ export interface HookRunResult {
      * `permissionDecision:"deny"` all set `blocked = true`.
      */
     readonly blocked: boolean;
+    /**
+     * Network egress the hook attempted, recorded then blocked. Empty unless
+     * {@link RunHookOptions.recordEgress} was set (and the run was confined).
+     */
+    readonly egress: readonly EgressAttempt[];
+    /**
+     * Files the hook wrote to its work dir (relative paths), recorded on confined
+     * runs — what a hook touched on disk. Empty on a direct (unconfined) run.
+     * Assert over it with `assertNoWrite` / `assertWroteOnly`.
+     */
+    readonly filesWritten: readonly string[];
     /**
      * The decision the hook expressed, preferring the structured
      * `permissionDecision` ("allow"|"deny"|"ask") then legacy `decision`
@@ -67,11 +115,43 @@ export declare function decideHook(exitCode: number, json: HookOutput | null): {
     blocked: boolean;
     decision: HookRunResult["decision"];
 };
+/** The raw fields of a hook spawn that the result parser needs. */
+export interface HookSpawnResult {
+    readonly status: number | null;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Egress attempts captured by the in-sandbox recorder (recordEgress only). */
+    readonly egress?: readonly EgressAttempt[];
+    /** Files the hook wrote to its work dir (confined runs). */
+    readonly filesWritten?: readonly string[];
+}
+/** Spawn a hook (command + piped event) — the injectable seam over the real spawn. */
+export type HookSpawner = (command: string, input: HookInput, opts: RunHookOptions) => HookSpawnResult;
+/** The spawn seams `runHookWith` needs, so its decision logic is testable. */
+export interface RunHookDeps {
+    /** Whether bubblewrap confinement is available (Linux + bwrap). */
+    readonly available: boolean;
+    /** Run the command directly (unconfined). */
+    readonly direct: HookSpawner;
+    /** Run the command confined under bubblewrap. */
+    readonly sandboxed: HookSpawner;
+}
+/**
+ * The hook-run orchestration with injectable spawn seams: pick direct vs.
+ * confined via the safe-by-default policy (`decideSandbox`), then parse the exit
+ * code + stdout into a normalized decision. Exported so all three branches
+ * (direct / sandbox / refuse) are unit-tested with fake spawners — no real
+ * bwrap. `runHook` is this with the real seams.
+ */
+export declare function runHookWith(command: string, input: HookInput, opts: RunHookOptions, deps: RunHookDeps): HookRunResult;
 /**
  * Run a hook command, piping `input` as JSON to its stdin, and report the exit
  * code + parsed decision. Synchronous (so it can be used inside an eval's
  * `measure` too). `command` is run through a shell, so the same command string a
- * plugin ships (with args / env refs) works verbatim.
+ * plugin ships (with args / env refs) works verbatim. Mark a hook you didn't
+ * write with `trusted: false` and it is confined by default (or pass `sandbox:
+ * "auto"` directly) — see {@link RunHookOptions.trusted}.
  */
 export declare function runHook(command: string, input: HookInput, opts?: RunHookOptions): HookRunResult;
 //# sourceMappingURL=run-hook.d.ts.map