vigiles 6.0.0 → 7.0.0

package/dist/core/bash-effects.d.ts

@@ -38,4 +38,16 @@ export declare function classifyBashCommand(command: string): BashEffect;
  * caller uses to decide "this Bash is provably an observation."
  */
 export declare function isReadOnlyBash(command: string): boolean;
+/**
+ * Extract the static argv of every simple command (CallExpr) in `command`, each
+ * as an array of literal words (dynamic / quoted-interpolated words are dropped).
+ * AST-backed, so a leaf nested in a pipeline, `&&`/`;`/`|`, a subshell, or a
+ * compound command is still found — the structural query a robust matcher needs
+ * (a regex over the raw string misses `cd x && git push`). Parse failure → [].
+ *
+ * This is the matching primitive a typed hook's `command.runs("git push")` is
+ * built on: it sees the real `git push` leaf however it's wrapped, which the
+ * native `Bash(git:*)` glob (issue #30519) and a hand-written `grep` both miss.
+ */
+export declare function leafCommands(command: string): string[][];
 //# sourceMappingURL=bash-effects.d.ts.map

package/dist/core/bash-effects.js

@@ -26,6 +26,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyBashCommand = classifyBashCommand;
 exports.isReadOnlyBash = isReadOnlyBash;
+exports.leafCommands = leafCommands;
 // mvdan-sh is a CJS package (GopherJS build) with no bundled TypeScript types.
 // The project compiles to CommonJS (Node16, no "type":"module"), so plain
 // require() works and is the idiomatic pattern here (see linters.ts).
@@ -402,4 +403,34 @@ function classifyBashCommand(command) {
 function isReadOnlyBash(command) {
     return classifyBashCommand(command) === "read-only";
 }
+/**
+ * Extract the static argv of every simple command (CallExpr) in `command`, each
+ * as an array of literal words (dynamic / quoted-interpolated words are dropped).
+ * AST-backed, so a leaf nested in a pipeline, `&&`/`;`/`|`, a subshell, or a
+ * compound command is still found — the structural query a robust matcher needs
+ * (a regex over the raw string misses `cd x && git push`). Parse failure → [].
+ *
+ * This is the matching primitive a typed hook's `command.runs("git push")` is
+ * built on: it sees the real `git push` leaf however it's wrapped, which the
+ * native `Bash(git:*)` glob (issue #30519) and a hand-written `grep` both miss.
+ */
+function leafCommands(command) {
+    let file;
+    try {
+        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    sh.syntax.Walk(file, (node) => {
+        if (sh.syntax.NodeType(node) === "CallExpr" && node.Args) {
+            const argv = node.Args.map((w) => getLiteral(w)).filter((s) => s !== null);
+            if (argv.length > 0)
+                out.push(argv);
+        }
+        return true;
+    });
+    return out;
+}
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/capability-diff.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Capability-diff — "did this change widen the agent's blast radius?" (moat #2).
+ *
+ * The whole-harness capability lattice ({@link HarnessCapabilities}, computed by
+ * `computeHarnessCapabilities`) is the set of effects an agent/harness can reach:
+ * read-only tools, side-effecting tools, unknown/MCP tools, and the loosest purity.
+ * Diffing two lattices (a PR's base vs head) yields a deterministic, model-free
+ * verdict: a change WIDENED the blast radius iff it adds a side-effecting or
+ * unknown/MCP tool, or loosens the purity floor. New read-only tools and removals
+ * are reported but are NOT a widening.
+ *
+ * Honesty / don't-cry-wolf: a widening is INFORMATIONAL by default (a PR comment),
+ * not an automatic failure — widening the surface is often intended. The CLI gates
+ * a non-zero exit behind an explicit `--fail-on-widen`. Pure + harness-agnostic
+ * (operates on the lattice, no dialect needed). See research/typed-spec-moat.md (#2).
+ */
+import type { HarnessCapabilities } from "./generate-harness.js";
+import type { PurityLevel } from "./effects.js";
+/** A purity move between two lattices (omitted when unchanged). */
+export interface PurityChange {
+    readonly from: PurityLevel;
+    readonly to: PurityLevel;
+    /** `widened` = loosened (pure→bounded→unrestricted); `narrowed` = tightened. */
+    readonly direction: "widened" | "narrowed";
+}
+export interface CapabilityDiff {
+    /** Side-effecting tools reachable AFTER but not before — the core blast-radius growth. */
+    readonly addedSideEffecting: readonly string[];
+    /** Unknown-effect (MCP / unrecognized) tools newly reachable — also widened reach. */
+    readonly addedUnknown: readonly string[];
+    /** Read-only tools newly reachable — benign (reported, NOT a widening). */
+    readonly addedReadOnly: readonly string[];
+    /** Tools reachable before but not after — a NARROWING (good; informational). */
+    readonly removed: readonly string[];
+    /** The purity move, or null when unchanged. */
+    readonly purity: PurityChange | null;
+    /** The verdict: did the blast radius GROW (new side-effecting/unknown, or purity loosened)? */
+    readonly widened: boolean;
+}
+/** Diff two capability lattices → what changed + the widened verdict. Pure. */
+export declare function diffCapabilities(before: HarnessCapabilities, after: HarnessCapabilities): CapabilityDiff;
+/** True when the diff carries no change at all (the common, quiet case). */
+export declare function isNoOpDiff(d: CapabilityDiff): boolean;
+/** Render a capability-diff as a PR-comment-style report (Markdown-friendly). */
+export declare function formatCapabilityDiff(d: CapabilityDiff): string;
+//# sourceMappingURL=capability-diff.d.ts.map

package/dist/core/capability-diff.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Capability-diff — "did this change widen the agent's blast radius?" (moat #2).
+ *
+ * The whole-harness capability lattice ({@link HarnessCapabilities}, computed by
+ * `computeHarnessCapabilities`) is the set of effects an agent/harness can reach:
+ * read-only tools, side-effecting tools, unknown/MCP tools, and the loosest purity.
+ * Diffing two lattices (a PR's base vs head) yields a deterministic, model-free
+ * verdict: a change WIDENED the blast radius iff it adds a side-effecting or
+ * unknown/MCP tool, or loosens the purity floor. New read-only tools and removals
+ * are reported but are NOT a widening.
+ *
+ * Honesty / don't-cry-wolf: a widening is INFORMATIONAL by default (a PR comment),
+ * not an automatic failure — widening the surface is often intended. The CLI gates
+ * a non-zero exit behind an explicit `--fail-on-widen`. Pure + harness-agnostic
+ * (operates on the lattice, no dialect needed). See research/typed-spec-moat.md (#2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCapabilities = diffCapabilities;
+exports.isNoOpDiff = isNoOpDiff;
+exports.formatCapabilityDiff = formatCapabilityDiff;
+const PURITY_RANK = {
+    pure: 0,
+    bounded: 1,
+    unrestricted: 2,
+};
+const addedIn = (before, after) => after.filter((x) => !before.includes(x));
+/** Diff two capability lattices → what changed + the widened verdict. Pure. */
+function diffCapabilities(before, after) {
+    const addedSideEffecting = addedIn(before.sideEffecting, after.sideEffecting);
+    const addedUnknown = addedIn(before.unknown, after.unknown);
+    const addedReadOnly = addedIn(before.readOnly, after.readOnly);
+    // A tool is "removed" if it was reachable in ANY bucket before and in NONE after.
+    const afterAll = new Set([
+        ...after.readOnly,
+        ...after.sideEffecting,
+        ...after.unknown,
+    ]);
+    const removed = [
+        ...before.readOnly,
+        ...before.sideEffecting,
+        ...before.unknown,
+    ].filter((x) => !afterAll.has(x));
+    const fromRank = PURITY_RANK[before.purity];
+    const toRank = PURITY_RANK[after.purity];
+    const purity = fromRank === toRank
+        ? null
+        : {
+            from: before.purity,
+            to: after.purity,
+            direction: toRank > fromRank ? "widened" : "narrowed",
+        };
+    const widened = addedSideEffecting.length > 0 ||
+        addedUnknown.length > 0 ||
+        purity?.direction === "widened";
+    return {
+        addedSideEffecting,
+        addedUnknown,
+        addedReadOnly,
+        removed,
+        purity,
+        widened,
+    };
+}
+/** True when the diff carries no change at all (the common, quiet case). */
+function isNoOpDiff(d) {
+    return (d.addedSideEffecting.length === 0 &&
+        d.addedUnknown.length === 0 &&
+        d.addedReadOnly.length === 0 &&
+        d.removed.length === 0 &&
+        d.purity === null);
+}
+/** Render a capability-diff as a PR-comment-style report (Markdown-friendly). */
+function formatCapabilityDiff(d) {
+    if (isNoOpDiff(d)) {
+        return "Capability surface unchanged — no blast-radius change.";
+    }
+    const lines = [
+        d.widened
+            ? "⚠️ Capability surface **WIDENED** — this change grows the agent's blast radius:"
+            : "Capability surface changed (no widening — narrowing / read-only only):",
+    ];
+    if (d.addedSideEffecting.length > 0)
+        lines.push(`  + side-effecting: ${d.addedSideEffecting.join(", ")}`);
+    if (d.addedUnknown.length > 0)
+        lines.push(`  + unknown/MCP: ${d.addedUnknown.join(", ")}`);
+    if (d.purity?.direction === "widened")
+        lines.push(`  + purity loosened: ${d.purity.from} → ${d.purity.to}`);
+    if (d.addedReadOnly.length > 0)
+        lines.push(`  · read-only added (benign): ${d.addedReadOnly.join(", ")}`);
+    if (d.removed.length > 0)
+        lines.push(`  − narrowed (removed): ${d.removed.join(", ")}`);
+    if (d.purity?.direction === "narrowed")
+        lines.push(`  − purity tightened: ${d.purity.from} → ${d.purity.to}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=capability-diff.js.map

package/dist/core/guards.d.ts

@@ -0,0 +1,126 @@
+/**
+ * EXPERIMENTAL prototype — typed, safe-by-construction harness GUARDS.
+ *
+ * Dogfood finding (real OSS hooks: our pre-edit.sh, superpowers/OMC session-start,
+ * OMC keyword-detector): a "hook" today is an arbitrary shell command in
+ * settings.json — which is BOTH the enforcement vehicle AND the RCE footgun
+ * (CVE-2025-59536: a malicious repo's hook runs before the trust dialog). Arbitrary
+ * hook safety is UNDECIDABLE (Rice). So this prototype inverts it: you don't WRITE a
+ * hook, you DECLARE a guard from a closed, audited vocabulary, and vigiles GENERATES
+ * the hooks block — whose command is vigiles's OWN gate (`vigiles hook-runtime guard`), never
+ * user shell. Safe-by-construction, not safe-by-analysis.
+ *
+ * Covers the real PreToolUse patterns + the new ORDER axis:
+ *   - block:        deny a tool call matching args (reproduces pre-edit.sh's intent)
+ *   - requireBefore: ORDER — deny a tool call until a prerequisite call has fired
+ *                    (`terraform destroy` only after `terraform plan`; the moat)
+ *   - confine:      deny a path-taking tool whose path escapes an allowlist (rm -rf /)
+ *
+ * EXPERIMENTAL — not on the public API. But the gate now RUNS end-to-end: the
+ * `vigiles hook-runtime guard` CLI subcommand reads the live PreToolUse event, loads the
+ * guard set (`.vigiles/guards.json`) + the session ledger (`.vigiles/guard-ledger.json`,
+ * the reconstructed prior-call list `requireBefore` needs), runs `decideGuards`, and
+ * blocks (exit 2 + reason) or records-the-allowed-call (so the next call sees it). The
+ * pure `decideGuards` is the decision; `compileGuards` is the generator; the
+ * serialization + ledger below are the IO seam the CLI calls.
+ * See research/harness-protocol-flow-moat.md.
+ */
+import { type ArgMatcher } from "../arg-match.js";
+/** A tool-call shape: a tool name + an optional argument matcher (the `when`). */
+export interface ToolPattern {
+    readonly tool: string;
+    readonly when?: ArgMatcher;
+}
+export type Guard = {
+    readonly kind: "block";
+    readonly target: ToolPattern;
+    readonly reason: string;
+} | {
+    readonly kind: "requireBefore";
+    readonly target: ToolPattern;
+    /** The prerequisite call that must have fired earlier this session. */
+    readonly prerequisite: ToolPattern;
+    readonly reason?: string;
+} | {
+    readonly kind: "confine";
+    readonly tools: readonly string[];
+    /** Dot-path to the path argument (default `file_path`). */
+    readonly pathKey?: string;
+    /** Allowed path prefixes (a call outside ALL of them is denied). */
+    readonly allow: readonly string[];
+    readonly reason?: string;
+};
+/** Ergonomic builders for the closed vocabulary. */
+export declare const guard: {
+    block: (target: ToolPattern, reason: string) => Guard;
+    requireBefore: (target: ToolPattern, prerequisite: ToolPattern, reason?: string) => Guard;
+    confine: (tools: readonly string[], allow: readonly string[], reason?: string, pathKey?: string) => Guard;
+};
+/** A tool call as seen at PreToolUse (and as recorded in the prior-call ledger). */
+export interface ToolEvent {
+    readonly tool: string;
+    readonly input: unknown;
+}
+export interface GuardDecision {
+    readonly allow: boolean;
+    /** Set on a deny — the message surfaced to the agent. */
+    readonly reason?: string;
+}
+/**
+ * The pure runtime gate: decide allow/deny for `event`, given the guards and the
+ * calls that already fired this session (`prior`, oldest-first — the ledger the
+ * `guard-hook` CLI reconstructs from the transcript). First match wins a deny.
+ */
+export declare function decideGuards(guards: readonly Guard[], event: ToolEvent, prior?: readonly ToolEvent[]): GuardDecision;
+/** Every tool name a guard set gates (the PreToolUse matcher union). */
+export declare function guardedTools(guards: readonly Guard[]): string[];
+/** A Claude Code settings `hooks` block (the generated artifact). */
+export interface HooksConfig {
+    readonly hooks: {
+        readonly PreToolUse: readonly {
+            readonly matcher: string;
+            readonly hooks: readonly {
+                readonly type: "command";
+                readonly command: string;
+            }[];
+        }[];
+    };
+}
+/**
+ * Generate the hooks block for a guard set. The command is vigiles's OWN gate
+ * (default `npx vigiles hook-runtime guard`), NOT user shell — so the generated
+ * enforcement is safe-by-construction and a repo can't smuggle an arbitrary RCE
+ * hook. The gate reads the same guard set + the live event and runs `decideGuards`.
+ */
+export declare function compileGuards(guards: readonly Guard[], gateCommand?: string): HooksConfig;
+/** Serialize a guard set for `.vigiles/guards.json` (RegExp matchers preserved). */
+export declare function serializeGuards(guards: readonly Guard[]): string;
+/** Parse a guard set from JSON (tolerant — a malformed guard is skipped). */
+export declare function parseGuards(json: string): Guard[];
+/** Load the declared guard set from `.vigiles/guards.json` (absent → none). */
+export declare function loadGuards(cwd: string): Guard[];
+/**
+ * The prior-call ledger — the calls already allowed this session, oldest-first.
+ * `requireBefore` reads it to know whether a prerequisite ran. Claude Code doesn't
+ * surface call history to a hook, so vigiles records each allowed call itself
+ * (mirrors `.vigiles/active-agent.json`).
+ */
+export declare function readGuardLedger(cwd: string): ToolEvent[];
+/** Append an allowed call to the session ledger. */
+export declare function recordGuardCall(cwd: string, event: ToolEvent): void;
+/** Parse a PreToolUse event JSON (the hook's stdin) into a {@link ToolEvent}. */
+export declare function parseGuardEvent(rawJson: string): ToolEvent | null;
+/** The outcome of running the gate against one event. */
+export interface GuardHookOutcome {
+    readonly decision: GuardDecision;
+    /** True iff the allowed call was recorded to the ledger. */
+    readonly recorded: boolean;
+}
+/**
+ * The runnable gate, decoupled from process/exit so it's testable. Decides the
+ * event against the loaded guards + the prior-call ledger; on ALLOW it records the
+ * call (so a later `requireBefore` sees it) and on DENY it records nothing (a
+ * blocked call never happened). Malformed/absent event → allow, record nothing.
+ */
+export declare function runGuardHook(cwd: string, rawJson: string): GuardHookOutcome;
+//# sourceMappingURL=guards.d.ts.map

package/dist/core/guards.js

@@ -0,0 +1,309 @@
+"use strict";
+/**
+ * EXPERIMENTAL prototype — typed, safe-by-construction harness GUARDS.
+ *
+ * Dogfood finding (real OSS hooks: our pre-edit.sh, superpowers/OMC session-start,
+ * OMC keyword-detector): a "hook" today is an arbitrary shell command in
+ * settings.json — which is BOTH the enforcement vehicle AND the RCE footgun
+ * (CVE-2025-59536: a malicious repo's hook runs before the trust dialog). Arbitrary
+ * hook safety is UNDECIDABLE (Rice). So this prototype inverts it: you don't WRITE a
+ * hook, you DECLARE a guard from a closed, audited vocabulary, and vigiles GENERATES
+ * the hooks block — whose command is vigiles's OWN gate (`vigiles hook-runtime guard`), never
+ * user shell. Safe-by-construction, not safe-by-analysis.
+ *
+ * Covers the real PreToolUse patterns + the new ORDER axis:
+ *   - block:        deny a tool call matching args (reproduces pre-edit.sh's intent)
+ *   - requireBefore: ORDER — deny a tool call until a prerequisite call has fired
+ *                    (`terraform destroy` only after `terraform plan`; the moat)
+ *   - confine:      deny a path-taking tool whose path escapes an allowlist (rm -rf /)
+ *
+ * EXPERIMENTAL — not on the public API. But the gate now RUNS end-to-end: the
+ * `vigiles hook-runtime guard` CLI subcommand reads the live PreToolUse event, loads the
+ * guard set (`.vigiles/guards.json`) + the session ledger (`.vigiles/guard-ledger.json`,
+ * the reconstructed prior-call list `requireBefore` needs), runs `decideGuards`, and
+ * blocks (exit 2 + reason) or records-the-allowed-call (so the next call sees it). The
+ * pure `decideGuards` is the decision; `compileGuards` is the generator; the
+ * serialization + ledger below are the IO seam the CLI calls.
+ * See research/harness-protocol-flow-moat.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guard = void 0;
+exports.decideGuards = decideGuards;
+exports.guardedTools = guardedTools;
+exports.compileGuards = compileGuards;
+exports.serializeGuards = serializeGuards;
+exports.parseGuards = parseGuards;
+exports.loadGuards = loadGuards;
+exports.readGuardLedger = readGuardLedger;
+exports.recordGuardCall = recordGuardCall;
+exports.parseGuardEvent = parseGuardEvent;
+exports.runGuardHook = runGuardHook;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const arg_match_js_1 = require("../arg-match.js");
+/** Ergonomic builders for the closed vocabulary. */
+exports.guard = {
+    block: (target, reason) => ({
+        kind: "block",
+        target,
+        reason,
+    }),
+    requireBefore: (target, prerequisite, reason) => ({ kind: "requireBefore", target, prerequisite, reason }),
+    confine: (tools, allow, reason, pathKey) => ({ kind: "confine", tools, allow, reason, pathKey }),
+};
+const ALLOW = { allow: true };
+const deny = (reason) => ({ allow: false, reason });
+const matchesPattern = (e, p) => e.tool === p.tool && (p.when === undefined || (0, arg_match_js_1.matchesArgs)(e.input, p.when));
+/** A path is confined if it sits under at least one allowed prefix. */
+function isConfined(path, allow) {
+    const norm = path.replace(/^\.\//, "");
+    return allow.some((a) => {
+        const base = a.replace(/\/?\*+$/, "").replace(/\/$/, "");
+        return base === "" || norm === base || norm.startsWith(base + "/");
+    });
+}
+/** Decide a single guard against the event (null = this guard doesn't apply). */
+function decideOne(g, event, prior) {
+    switch (g.kind) {
+        case "block":
+            return matchesPattern(event, g.target) ? deny(g.reason) : null;
+        case "requireBefore":
+            if (!matchesPattern(event, g.target))
+                return null;
+            if (prior.some((c) => matchesPattern(c, g.prerequisite)))
+                return null;
+            return deny(g.reason ??
+                `${describePattern(g.target)} requires ${describePattern(g.prerequisite)} first`);
+        case "confine": {
+            if (!g.tools.includes(event.tool))
+                return null;
+            const path = event.input?.[g.pathKey ?? "file_path"];
+            if (typeof path !== "string" || isConfined(path, g.allow))
+                return null;
+            return deny(g.reason ??
+                `${event.tool} path "${path}" is outside the allowed set [${g.allow.join(", ")}]`);
+        }
+    }
+}
+/**
+ * The pure runtime gate: decide allow/deny for `event`, given the guards and the
+ * calls that already fired this session (`prior`, oldest-first — the ledger the
+ * `guard-hook` CLI reconstructs from the transcript). First match wins a deny.
+ */
+function decideGuards(guards, event, prior = []) {
+    for (const g of guards) {
+        const d = decideOne(g, event, prior);
+        if (d)
+            return d;
+    }
+    return ALLOW;
+}
+const describePattern = (p) => p.when ? `${p.tool}(${(0, arg_match_js_1.describeArgs)(p.when)})` : p.tool;
+/** Every tool name a guard set gates (the PreToolUse matcher union). */
+function guardedTools(guards) {
+    const tools = new Set();
+    for (const g of guards) {
+        if (g.kind === "confine")
+            for (const t of g.tools)
+                tools.add(t);
+        else
+            tools.add(g.target.tool);
+    }
+    return [...tools].sort();
+}
+/**
+ * Generate the hooks block for a guard set. The command is vigiles's OWN gate
+ * (default `npx vigiles hook-runtime guard`), NOT user shell — so the generated
+ * enforcement is safe-by-construction and a repo can't smuggle an arbitrary RCE
+ * hook. The gate reads the same guard set + the live event and runs `decideGuards`.
+ */
+function compileGuards(guards, gateCommand = "npx vigiles hook-runtime guard") {
+    const matcher = guardedTools(guards).join("|");
+    return {
+        hooks: {
+            PreToolUse: [
+                { matcher, hooks: [{ type: "command", command: gateCommand }] },
+            ],
+        },
+    };
+}
+function isWireRegex(v) {
+    return typeof v === "object" && v !== null && "re" in v;
+}
+function encodeMatcher(m) {
+    const out = {};
+    for (const [k, v] of Object.entries(m)) {
+        out[k] = v instanceof RegExp ? { re: v.source, flags: v.flags } : v;
+    }
+    return out;
+}
+function decodeMatcher(w) {
+    const out = {};
+    for (const [k, v] of Object.entries(w)) {
+        out[k] = isWireRegex(v) ? new RegExp(v.re, v.flags) : v;
+    }
+    return out;
+}
+function encodePattern(p) {
+    return { tool: p.tool, when: p.when ? encodeMatcher(p.when) : undefined };
+}
+function decodePattern(raw) {
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const o = raw;
+    if (typeof o.tool !== "string")
+        return null;
+    const when = o.when !== null && typeof o.when === "object"
+        ? decodeMatcher(o.when)
+        : undefined;
+    return { tool: o.tool, when };
+}
+/** Serialize a guard set for `.vigiles/guards.json` (RegExp matchers preserved). */
+function serializeGuards(guards) {
+    const wire = guards.map((g) => {
+        if (g.kind === "confine") {
+            return {
+                kind: g.kind,
+                tools: g.tools,
+                allow: g.allow,
+                pathKey: g.pathKey,
+                reason: g.reason,
+            };
+        }
+        if (g.kind === "requireBefore") {
+            return {
+                kind: g.kind,
+                target: encodePattern(g.target),
+                prerequisite: encodePattern(g.prerequisite),
+                reason: g.reason,
+            };
+        }
+        return { kind: g.kind, target: encodePattern(g.target), reason: g.reason };
+    });
+    return JSON.stringify({ guards: wire }, null, 2);
+}
+function parseConfine(o) {
+    if (!Array.isArray(o.tools) || !Array.isArray(o.allow))
+        return null;
+    return {
+        kind: "confine",
+        tools: o.tools.filter((t) => typeof t === "string"),
+        allow: o.allow.filter((a) => typeof a === "string"),
+        pathKey: typeof o.pathKey === "string" ? o.pathKey : undefined,
+        reason: typeof o.reason === "string" ? o.reason : undefined,
+    };
+}
+function parseGuard(raw) {
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const o = raw;
+    const reason = typeof o.reason === "string" ? o.reason : undefined;
+    if (o.kind === "block") {
+        const target = decodePattern(o.target);
+        return target && reason ? { kind: "block", target, reason } : null;
+    }
+    if (o.kind === "requireBefore") {
+        const target = decodePattern(o.target);
+        const prerequisite = decodePattern(o.prerequisite);
+        if (!target || !prerequisite)
+            return null;
+        return { kind: "requireBefore", target, prerequisite, reason };
+    }
+    if (o.kind === "confine")
+        return parseConfine(o);
+    return null;
+}
+/** Parse a guard set from JSON (tolerant — a malformed guard is skipped). */
+function parseGuards(json) {
+    let data;
+    try {
+        data = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    const list = data?.guards;
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const item of list) {
+        const g = parseGuard(item);
+        if (g)
+            out.push(g);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Runtime IO — load the guard set, read/append the session ledger
+// ---------------------------------------------------------------------------
+const GUARDS_FILE = ".vigiles/guards.json";
+const LEDGER_FILE = ".vigiles/guard-ledger.json";
+/** Load the declared guard set from `.vigiles/guards.json` (absent → none). */
+function loadGuards(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, GUARDS_FILE);
+    if (!(0, node_fs_1.existsSync)(p))
+        return [];
+    return parseGuards((0, node_fs_1.readFileSync)(p, "utf-8"));
+}
+/**
+ * The prior-call ledger — the calls already allowed this session, oldest-first.
+ * `requireBefore` reads it to know whether a prerequisite ran. Claude Code doesn't
+ * surface call history to a hook, so vigiles records each allowed call itself
+ * (mirrors `.vigiles/active-agent.json`).
+ */
+function readGuardLedger(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, LEDGER_FILE);
+    if (!(0, node_fs_1.existsSync)(p))
+        return [];
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        if (!Array.isArray(parsed.calls))
+            return [];
+        return parsed.calls.filter((c) => c !== null &&
+            typeof c === "object" &&
+            typeof c.tool === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/** Append an allowed call to the session ledger. */
+function recordGuardCall(cwd, event) {
+    const p = (0, node_path_1.resolve)(cwd, LEDGER_FILE);
+    const calls = readGuardLedger(cwd);
+    calls.push({ tool: event.tool, input: event.input });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ calls }, null, 2));
+}
+/** Parse a PreToolUse event JSON (the hook's stdin) into a {@link ToolEvent}. */
+function parseGuardEvent(rawJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawJson);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.tool_name !== "string" || !parsed.tool_name)
+        return null;
+    return { tool: parsed.tool_name, input: parsed.tool_input ?? {} };
+}
+/**
+ * The runnable gate, decoupled from process/exit so it's testable. Decides the
+ * event against the loaded guards + the prior-call ledger; on ALLOW it records the
+ * call (so a later `requireBefore` sees it) and on DENY it records nothing (a
+ * blocked call never happened). Malformed/absent event → allow, record nothing.
+ */
+function runGuardHook(cwd, rawJson) {
+    const event = parseGuardEvent(rawJson);
+    if (!event)
+        return { decision: ALLOW, recorded: false };
+    const guards = loadGuards(cwd);
+    const decision = decideGuards(guards, event, readGuardLedger(cwd));
+    if (decision.allow) {
+        recordGuardCall(cwd, event);
+        return { decision, recorded: true };
+    }
+    return { decision, recorded: false };
+}
+//# sourceMappingURL=guards.js.map

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

@@ -19,7 +19,7 @@ import type { HarnessRuntime } from "./runtime.js";
 /**
  * One scripted assistant turn: a final text answer, or a tool call. The common
  * shape both harness mocks consume — the Anthropic Messages mock
- * (`src/adapters/claude-code/mock-model.ts`) and the OpenAI Responses mock
+ * (`src/mock-model.ts`) and the OpenAI Responses mock
  * (`src/adapters/codex/mock-model.ts`, which uses only `text`).
  */
 export interface ModelTurn {