vigiles 2.5.0 → 3.0.0

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

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.resolveHarness = exports.loadPlugin = exports.scriptModel = void 0;
+exports.claudeCodeDriver = exports.sandboxAvailable = exports.specTrusted = exports.decideSandbox = exports.resolveHarness = exports.loadPlugin = exports.scriptModel = void 0;
 exports.parseToolCalls = parseToolCalls;
 exports.parseResultEvent = parseResultEvent;
 exports.parseOutput = parseOutput;
 exports.parseHooks = parseHooks;
 exports.buildClaudeArgs = buildClaudeArgs;
+exports.parseClaudeRun = parseClaudeRun;
 exports.claudeAvailable = claudeAvailable;
 exports.runHarnessTest = runHarnessTest;
 /**
@@ -42,6 +43,8 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const adapter_conformance_js_1 = require("../../adapter-conformance.js");
+const runtime_js_1 = require("./runtime.js");
 const mock_model_js_1 = require("./mock-model.js");
 const plugin_loader_js_1 = require("./plugin-loader.js");
 const sandbox_js_1 = require("./sandbox.js");
@@ -194,13 +197,33 @@ function buildClaudeArgs(spec, hasSettings) {
         ...tools,
     ];
 }
+/** Build the `claude` argv from the driver context — wraps `buildClaudeArgs`. */
+function buildClaudeArgsFromCtx(ctx) {
+    return buildClaudeArgs({
+        model: [],
+        prompt: ctx.prompt,
+        transcript: ctx.transcript,
+        pluginDir: ctx.pluginDir,
+        allowedTools: ctx.tools,
+    }, ctx.hasSettings);
+}
+/** Parse the `claude` stdout/stream into the unified trace fields. */
+function parseClaudeRun(stdout) {
+    return {
+        toolCalls: parseToolCalls(stdout),
+        hooks: parseHooks(stdout),
+        output: parseOutput(stdout),
+    };
+}
 /* v8 ignore start -- spawns the real claude CLI + filesystem; exercised by the
    claude-backed suite, excluded from the deterministic coverage gate (the parse
    helpers above carry the testable logic). */
-/** Whether the `claude` CLI is available — harness tests need it. */
+/** Whether the agent CLI is available — harness tests need it. */
 function claudeAvailable() {
     try {
-        return (0, node_child_process_1.spawnSync)("claude", ["--version"], { stdio: "ignore" }).status === 0;
+        return ((0, node_child_process_1.spawnSync)(runtime_js_1.claudeCodeRuntime.agentBinary, ["--version"], {
+            stdio: "ignore",
+        }).status === 0);
     }
     catch {
         return false;
@@ -220,16 +243,21 @@ function writeFixture(cwd, files, settings) {
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(cwd, "settings.json"), json);
     }
 }
-function spawnClaude(args, cwd, baseUrl, timeoutMs) {
+/**
+ * Spawn the agent binary against the mock. The mock-wiring *args* are already in
+ * `args` (the driver placed `wireMock(url).args` at the correct argv position
+ * via `ctx.mockArgs`); here we only layer `wireMock(url).env` over the caller's
+ * env. Driver-agnostic at the transport seam.
+ */
+function spawnAgent(runtime, args, cwd, baseUrl, timeoutMs) {
+    const wired = runtime.wireMock(baseUrl);
     return new Promise((resolvePromise) => {
-        const child = (0, node_child_process_1.spawn)("claude", args, {
+        const child = (0, node_child_process_1.spawn)(runtime.agentBinary, [...args], {
             cwd,
-            env: {
-                ...process.env,
-                ANTHROPIC_BASE_URL: baseUrl,
-                // Any value works — the mock ignores auth; this avoids needing a real key.
-                ANTHROPIC_API_KEY: "sk-vigiles-mock",
-            },
+            // Any key works — the mock ignores auth. wireMock supplies the overlay
+            // env (base-URL var + dummy key for CC; the dummy key for Codex); layer it
+            // over the caller's env.
+            env: { ...process.env, ...wired.env },
             stdio: ["ignore", "pipe", "pipe"],
         });
         let stdout = "";
@@ -244,15 +272,60 @@ function spawnClaude(args, cwd, baseUrl, timeoutMs) {
     });
 }
 /**
- * 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.
+ */
+exports.claudeCodeDriver = {
+    runtime: runtime_js_1.claudeCodeRuntime,
+    buildArgs: buildClaudeArgsFromCtx,
+    startMock: (script) => (0, mock_model_js_1.startMock)(script),
+    parseRun: parseClaudeRun,
+    available: claudeAvailable,
+};
+/* 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). */
+function makeResult(cwd, out, parsed, turns, modelRequests) {
+    return {
+        exitCode: out.code,
+        stdout: out.stdout,
+        stderr: out.stderr ?? "",
+        cwd,
+        turns,
+        toolCalls: parsed.toolCalls,
+        hooks: parsed.hooks,
+        output: parsed.output,
+        modelRequests,
+        file: (p) => {
+            const f = (0, node_path_1.resolve)(cwd, p);
+            return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
+        },
+        cleanup: () => {
+            (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
+        },
+    };
+}
+/**
+ * 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.
  */
-async function runHarnessTest(spec) {
+async function runHarnessTest(spec, opts = {}) {
+    const adapter = opts.adapter;
+    // Default (no adapter): the unchanged Claude Code driver — keeps the
+    // sandbox/confined path and behaviour byte-for-byte identical.
+    const driver = adapter
+        ? requireDriver(adapter)
+        : exports.claudeCodeDriver;
+    const isClaudeCode = driver.runtime.name === runtime_js_1.claudeCodeRuntime.name;
     const decision = (0, sandbox_js_1.decideSandbox)({
         trusted: (0, sandbox_js_1.specTrusted)(spec),
         mode: spec.sandbox ?? "auto",
@@ -260,6 +333,9 @@ async function runHarnessTest(spec) {
     });
     if (decision.action === "throw")
         throw new Error(decision.reason);
+    if (decision.action === "sandbox" && !isClaudeCode) {
+        throw new Error(`sandbox not supported for ${driver.runtime.name}: confined execution is Claude Code only. Pass sandbox: false to run ${driver.runtime.name} unconfined (you audited the code, or trust the outer container).`);
+    }
     const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
     const { files, settings } = (0, plugin_loader_js_1.resolveHarness)({
         plugin: spec.plugin,
@@ -267,45 +343,50 @@ async function runHarnessTest(spec) {
         files: spec.files,
     });
     writeFixture(cwd, files, settings);
-    const args = buildClaudeArgs(spec, settings !== undefined);
+    const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
     const timeoutMs = spec.timeoutMs ?? 60000;
-    const build = (out, turns, modelRequests) => ({
-        exitCode: out.code,
-        stdout: out.stdout,
-        stderr: out.stderr ?? "",
+    const buildArgs = (mockArgs) => driver.buildArgs({
+        prompt: spec.prompt ?? "go",
         cwd,
-        turns,
-        toolCalls: parseToolCalls(out.stdout),
-        hooks: parseHooks(out.stdout),
-        output: parseOutput(out.stdout),
-        modelRequests,
-        file: (p) => {
-            const f = (0, node_path_1.resolve)(cwd, p);
-            return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
-        },
-        cleanup: () => {
-            (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
-        },
+        hasSettings: settings !== undefined,
+        tools,
+        transcript: spec.transcript ?? false,
+        pluginDir: spec.pluginDir,
+        mockArgs,
     });
-    // Confined path: the mock is co-launched inside the sandbox's netns.
+    // Confined path (Claude Code only): the mock is co-launched in the netns, so
+    // the agent reaches it over the loopback URL the sandbox sets — Claude Code is
+    // env-only (empty mockArgs), so the argv needs no mock-wiring flags.
     if (decision.action === "sandbox") {
         const out = await (0, sandbox_js_1.runSandboxed)({
             cwd,
-            claudeArgs: args,
+            claudeArgs: [...buildArgs([])],
             script: spec.model,
             timeoutMs,
         });
-        return build(out, out.requests.length, out.requests);
+        return makeResult(cwd, out, parseClaudeRun(out.stdout), out.requests.length, out.requests);
     }
-    // Direct path: mock runs in this process; claude reaches it over localhost.
-    const mock = await (0, mock_model_js_1.startMock)(spec.model);
+    // Direct path: mock runs in this process; the agent reaches it over localhost.
+    // Start the mock first so its URL feeds the driver's mock-wiring args.
+    const mock = await driver.startMock(spec.model);
     try {
-        const out = await spawnClaude(args, cwd, mock.url, timeoutMs);
-        return build(out, mock.count, [...mock.requests]);
+        const args = buildArgs(driver.runtime.wireMock(mock.url).args);
+        const out = await spawnAgent(driver.runtime, args, cwd, mock.url, timeoutMs);
+        return makeResult(cwd, out, driver.parseRun(out.stdout), mock.count, [
+            ...mock.requests,
+        ]);
     }
     finally {
-        mock.close();
+        await mock.close();
+    }
+}
+/** Pull the pillar-2 driver off an adapter, asserting it supports testing. */
+function requireDriver(adapter) {
+    (0, adapter_conformance_js_1.assertHarnessTestable)(adapter);
+    if (!adapter.harnessTestDriver) {
+        throw new Error(`Adapter "${adapter.name}" declares harnessTesting but carries no harnessTestDriver — it cannot drive runHarnessTest.`);
     }
+    return adapter.harnessTestDriver;
 }
 /* v8 ignore stop */
 //# sourceMappingURL=harness-test.js.map

package/dist/adapters/claude-code/hook-protocol.d.ts

@@ -0,0 +1,10 @@
+/**
+ * claudeCodeHookProtocol — the Claude Code `HookProtocol`: a hook blocks via exit
+ * code 2 or a `permissionDecision: "deny"` / `decision: "block"` JSON decision;
+ * the event arrives on stdin. `decideHook` reads the block code + deny values
+ * from here. A Codex adapter's `codexHookProtocol` is nearly identical (the same
+ * decision model), adding its own `eventEnvVars` (session_id/PLUGIN_ROOT/…).
+ */
+import type { HookProtocol } from "../../core/hook-protocol.js";
+export declare const claudeCodeHookProtocol: HookProtocol;
+//# sourceMappingURL=hook-protocol.d.ts.map

package/dist/adapters/claude-code/hook-protocol.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeHookProtocol = void 0;
+exports.claudeCodeHookProtocol = {
+    name: "claude-code",
+    blockExitCode: 2,
+    denyDecisionValues: ["block", "deny"],
+    eventEnvVars: [],
+};
+//# sourceMappingURL=hook-protocol.js.map

package/dist/adapters/claude-code/layout.d.ts

@@ -0,0 +1,8 @@
+/**
+ * claudeCodeLayout — the Claude Code plugin/repo layout (the `PluginLayout`
+ * port's reference implementation). `loadPlugin` defaults to it; a Codex adapter
+ * defines a sibling `codexLayout` and passes it to the same loader.
+ */
+import type { PluginLayout } from "../../core/layout.js";
+export declare const claudeCodeLayout: PluginLayout;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeLayout = void 0;
+exports.claudeCodeLayout = {
+    name: "claude-code",
+    manifestPath: ".claude-plugin/plugin.json",
+    hooksConventionPath: "hooks/hooks.json",
+    settingsPath: ".claude/settings.json",
+    settingsFormat: "json",
+    instructionFile: "CLAUDE.md",
+    surfaceDirs: ["skills", "agents", "commands"],
+    materializeRoot: ".claude",
+    pluginRootToken: "${CLAUDE_PLUGIN_ROOT}",
+    mcpConfigFile: ".mcp.json",
+    mcpManifestKey: "mcpServers",
+    intraRefDirs: ["hooks", "skills", "agents", "commands"],
+};
+//# sourceMappingURL=layout.js.map

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

@@ -1,12 +1,5 @@
-/** One scripted assistant turn: a final text answer, or a tool call. */
-export interface ModelTurn {
-    /** Final text answer (stops the turn). */
-    readonly text?: string;
-    /** A tool to invoke, e.g. "Bash" | "Write" | "Edit". */
-    readonly tool?: string;
-    /** The tool input, e.g. `{ file_path, content }` or `{ command }`. */
-    readonly input?: Record<string, unknown>;
-}
+import type { ModelTurn, ModelRequest } from "../../core/harness-driver.js";
+export type { ModelTurn, ModelRequest } from "../../core/harness-driver.js";
 /** Build a scripted model from an ordered list of turns. */
 export declare function scriptModel(turns: readonly ModelTurn[]): ModelTurn[];
 export interface TurnInfo {
@@ -14,21 +7,6 @@ export interface TurnInfo {
     readonly stream: boolean;
     readonly hasToolResult: boolean;
 }
-/**
- * One `/v1/messages` request the mock received, flattened to text for
- * assertions. This is the seam that lets a harness test prove what reached the
- * model — a SessionStart hook's injected `additionalContext`, or a slash
- * command's expansion — not just that a hook fired.
- */
-export interface ModelRequest {
-    /** The system prompt, flattened to text (string or text-block array). */
-    readonly system: string;
-    /** The conversation messages, each flattened to `{ role, text }`. */
-    readonly messages: readonly {
-        readonly role: string;
-        readonly text: string;
-    }[];
-}
 export interface MockHandle {
     readonly url: string;
     close(): void;

package/dist/adapters/claude-code/model-mock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * claudeCodeModelMock — the Claude Code `ModelMock`: the mock speaks Anthropic
+ * **Messages** SSE; a turn-consuming request hits `/v1/messages`, and the client
+ * probes `/v1/messages/count_tokens`. `startMock` reads these endpoints from
+ * here. A Codex adapter's `codexModelMock` would set `wireApi:
+ * "openai-responses"` and `modelEndpoint: "/v1/responses"` with no count-tokens
+ * endpoint, and ship its own Responses-SSE renderer.
+ */
+import type { ModelMock } from "../../core/model-mock.js";
+export declare const claudeCodeModelMock: ModelMock;
+//# sourceMappingURL=model-mock.d.ts.map

package/dist/adapters/claude-code/model-mock.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeCodeModelMock = void 0;
+exports.claudeCodeModelMock = {
+    name: "claude-code",
+    wireApi: "anthropic-messages",
+    modelEndpoint: "/v1/messages",
+    countTokensEndpoint: "count_tokens",
+};
+//# sourceMappingURL=model-mock.js.map

package/dist/adapters/claude-code/plugin-loader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * vigiles — the Claude Code wrapper over the harness-agnostic plugin loader.
+ *
+ * The generic loader lives at the composition root (`src/plugin-loader.ts`) and
+ * takes a `PluginLayout` by injection, so no adapter imports a sibling adapter.
+ * This thin wrapper supplies the Claude Code layout as the default, preserving
+ * the `loadPlugin(dir)` / `resolveHarness(opts)` ergonomics and the public
+ * `vigiles/claude-code` + `vigiles/plugin-loader` exports unchanged.
+ */
+import type { PluginLayout } from "../../core/layout.js";
+import { loadPlugin as loadPluginWith, resolveHarness as resolveHarnessWith } from "../../plugin-loader.js";
+export type { LoadedPlugin } from "../../plugin-loader.js";
+/** Load the real Claude Code harness at `pluginPath` (defaults to `claudeCodeLayout`). */
+export declare function loadPlugin(pluginPath: string, layout?: PluginLayout): ReturnType<typeof loadPluginWith>;
+/**
+ * Resolve the effective harness for a test/eval (arm) under the Claude Code
+ * layout by default. Delegates to the generic `resolveHarness` at the
+ * composition root.
+ */
+export declare function resolveHarness(opts: {
+    plugin?: string;
+    settings?: unknown;
+    files?: Record<string, string>;
+}, layout?: PluginLayout): ReturnType<typeof resolveHarnessWith>;
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/adapters/claude-code/plugin-loader.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPlugin = loadPlugin;
+exports.resolveHarness = resolveHarness;
+const plugin_loader_js_1 = require("../../plugin-loader.js");
+const layout_js_1 = require("./layout.js");
+/** Load the real Claude Code harness at `pluginPath` (defaults to `claudeCodeLayout`). */
+function loadPlugin(pluginPath, layout = layout_js_1.claudeCodeLayout) {
+    return (0, plugin_loader_js_1.loadPlugin)(pluginPath, layout);
+}
+/**
+ * Resolve the effective harness for a test/eval (arm) under the Claude Code
+ * layout by default. Delegates to the generic `resolveHarness` at the
+ * composition root.
+ */
+function resolveHarness(opts, layout = layout_js_1.claudeCodeLayout) {
+    return (0, plugin_loader_js_1.resolveHarness)(opts, layout);
+}
+//# sourceMappingURL=plugin-loader.js.map

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

@@ -0,0 +1,204 @@
+import type { HookProtocol } from "../../core/hook-protocol.js";
+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". */
+    readonly hook_event_name?: string;
+    /** PreToolUse/PostToolUse. */
+    readonly tool_name?: string;
+    readonly tool_input?: unknown;
+    readonly tool_response?: unknown;
+    /** UserPromptSubmit. */
+    readonly prompt?: string;
+    /** SessionStart. */
+    readonly source?: string;
+    /** Stop / SubagentStop. */
+    readonly stop_hook_active?: boolean;
+    /** Any other event-specific fields. */
+    readonly [k: string]: unknown;
+}
+/** The JSON a hook may print on stdout (all fields optional). */
+export interface HookOutput {
+    readonly decision?: "approve" | "block";
+    readonly reason?: string;
+    readonly continue?: boolean;
+    readonly stopReason?: string;
+    readonly suppressOutput?: boolean;
+    readonly systemMessage?: string;
+    readonly hookSpecificOutput?: {
+        readonly hookEventName?: string;
+        readonly permissionDecision?: "allow" | "deny" | "ask";
+        readonly permissionDecisionReason?: string;
+        readonly additionalContext?: string;
+    };
+    readonly [k: string]: unknown;
+}
+export interface RunHookOptions {
+    /** Working directory for the hook process. Default: a value won't be set. */
+    readonly cwd?: string;
+    /** Extra env vars (merged over process.env). `{cwd}` in values is left as-is. */
+    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.
+     *
+     * Why this is opt-in (untrusted) and not always-on: the sandbox isn't always
+     * available (Linux + working userns only — forcing it would *refuse* a hook you
+     * wrote on macOS/hardened CI), it's deliberately hostile (no egress,
+     * `--clearenv`, empty HOME, read-only fs — a false failure for trusted code that
+     * needs the network or an env var), trust follows provenance (you already
+     * vouched for inline code), and direct exec is ms vs. the confined path's
+     * setup+spawn. See `docs/sandboxing.md` ("Why confinement is opt-in"). Use
+     * `sandbox: "strict"` to force confinement even on trusted code.
+     */
+    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;
+    /**
+     * Allowlisted egress: let the hook actually reach the network, but ONLY the
+     * listed hosts, with the boundary at the **packet layer** (an `nft` allowlist
+     * inside the sandbox netns, fed by `slirp4netns`) — so a raw socket to an
+     * off-list host is dropped too, which a `recordEgress`/`HTTP_PROXY` allowlist
+     * cannot guarantee. Use it to test a hook/skill whose setup needs a real
+     * `npm install` from a registry you expect, and nothing else. Implies
+     * confinement (it needs the netns), and **refuses** if bubblewrap + slirp4netns
+     * + nft aren't available. The hosts are resolved to IPs at launch; results land
+     * in {@link HookRunResult.egress} (the allowlisted hosts that were reached, with
+     * `allowed: true`) and {@link HookRunResult.egressDropped} (how much off-list
+     * traffic was blocked). See `docs/sandboxing.md`.
+     */
+    readonly egress?: {
+        readonly allow: readonly string[];
+    };
+}
+export interface HookRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Parsed stdout JSON if the hook emitted a JSON decision, else null. */
+    readonly json: HookOutput | null;
+    /**
+     * Normalized decision: a deny/block via exit 2, `decision:"block"`, or
+     * `permissionDecision:"deny"` all set `blocked = true`.
+     */
+    readonly blocked: boolean;
+    /**
+     * Network egress the hook attempted. With {@link RunHookOptions.recordEgress}:
+     * every (blocked) attempt the proxy saw. With {@link RunHookOptions.egress}: the
+     * allowlisted hosts that were actually reached (`allowed: true`, with packet
+     * counts). Empty otherwise.
+     */
+    readonly egress: readonly EgressAttempt[];
+    /**
+     * Allowlisted-egress mode only: the aggregate off-allowlist traffic the
+     * packet-layer wall dropped. `packets === 0` means the hook stayed entirely
+     * within the allowlist. Undefined when {@link RunHookOptions.egress} was unset.
+     */
+    readonly egressDropped?: {
+        readonly packets: number;
+        readonly bytes: number;
+    };
+    /**
+     * 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`
+     * ("approve"|"block"), else undefined.
+     */
+    readonly decision: HookOutput["decision"] | "allow" | "deny" | "ask" | undefined;
+}
+/** Parse stdout as a hook JSON decision (pure, testable without a process). */
+export declare function parseHookOutput(stdout: string): HookOutput | null;
+/**
+ * Decide whether a hook result blocked, and the normalized decision. Pure, so
+ * the policy is unit-testable independent of spawning anything.
+ */
+export declare function decideHook(exitCode: number, json: HookOutput | null, protocol?: HookProtocol): {
+    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[];
+    /** Off-allowlist traffic the packet-layer wall dropped (egress mode only). */
+    readonly egressDropped?: {
+        readonly packets: number;
+        readonly bytes: number;
+    };
+    /** 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;
+    /** Whether allowlisted egress is available (bwrap + slirp4netns + nft). */
+    readonly egressAvailable: boolean;
+    /** Run the command directly (unconfined). */
+    readonly direct: HookSpawner;
+    /** Run the command confined under bubblewrap. */
+    readonly sandboxed: HookSpawner;
+    /** Run the command confined with an allowlisted-egress netns. */
+    readonly egress: 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;
+export declare function egressRoutes(): boolean;
+/**
+ * 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. 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