proactive-gate 0.1.2 → 0.2.0

package/dist/src/checks.d.ts

@@ -17,8 +17,10 @@ export declare function enabled(): Check;
 export declare function mode(options: {
     allow: string[];
 }): Check;
-/** A global pause until an instant. */
-export declare function snooze(): Check;
+/** A global pause until an instant. With `defer: true` the decision carries the instant as `retryAt` instead of rejecting. */
+export declare function snooze(options?: {
+    defer?: boolean;
+}): Check;
 /** Per-type mute. */
 export declare function mute(): Check;
 /**
@@ -59,23 +61,80 @@ export declare function adaptiveTiming(options?: {
     nextGoodMoment?: (ctx: CheckContext) => Promise<Date | null> | Date | null;
     surfacesFor?: (ctx: CheckContext) => Surface[] | null;
 }): Check;
-/**
- * At most `limit` deliveries per user per local day. The check reads the
- * counter; gate.commit() increments it atomically and can still refuse when
- * two instances race, which is the only race-safe place to enforce a cap.
- */
 export interface BudgetCheck extends Check {
     limit: number;
+    consume(ctx: CheckContext): Promise<boolean>;
 }
-export declare function dailyBudget(options?: {
+export interface BudgetOptions {
     limit?: number;
     bypassPriority?: Priority;
-}): BudgetCheck;
+    /** Fraction of the limit at which a pass carries a nearLimit note. Default 0.8. */
+    nearLimit?: number;
+}
 export declare const budgetKey: (userId: string, now: Date, timezone?: string) => string;
 export declare const weeklyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
-export declare function weeklyBudget(options?: {
-    limit?: number;
-    bypassPriority?: Priority;
+export declare const monthlyBudgetKey: (userId: string, now: Date, timezone?: string) => string;
+/** At most `limit` deliveries per user per local day. */
+export declare function dailyBudget(options?: BudgetOptions): BudgetCheck;
+/** At most `limit` deliveries per user per local ISO week. */
+export declare function weeklyBudget(options?: BudgetOptions): BudgetCheck;
+/** At most `limit` deliveries per user per local calendar month. */
+export declare function monthlyBudget(options?: BudgetOptions): BudgetCheck;
+/**
+ * Horvitz's expected-utility rule with the PRISM threshold: act only when the
+ * caller's estimate of acceptance clears tau = cFA / (cFA + pNeed * cFN).
+ * `candidate.pAccept` and `candidate.pNeed` come from the caller's own model.
+ */
+export declare function utilityFloor(options: {
+    costFalseAlarm: number;
+    costMissedHelp: number;
+}): Check;
+/**
+ * Bounded deferral (Horvitz): when the user is busy, wait t* = min(bound,
+ * lambda * interruptCost / (2 * staleness)), the optimum of a quadratic
+ * staleness loss against the cost of interrupting a busy person, with the
+ * user becoming free at rate lambda. Never rejects; only moves deliverAt.
+ */
+export declare function boundedDeferral(options?: {
+    lambda?: number;
+    interruptCost?: number;
+    staleness?: number;
+    boundSeconds?: number;
+    isBusy?: (ctx: CheckContext) => boolean;
+}): Check;
+/** Deliveries only inside [start, end) local time in a fixed zone or the user's. */
+export declare function allowedWindow(options: {
+    start: string;
+    end: string;
+    timezone: string;
+    priorityFloor?: Priority;
+    id?: string;
+}): Check;
+/** Requires `user.consents[name]`, always or only inside a local-time window. */
+export declare function requiresConsent(options: {
+    name: string;
+    when?: {
+        start: string;
+        end: string;
+        timezone: string;
+    };
+    id?: string;
+}): Check;
+/** Fixed-window rate limit keyed by user or by candidate.channel; consumed at commit. */
+export declare function rateLimit(options: {
+    limit: number;
+    perSeconds: number;
+    keyBy?: "user" | "channel";
+    id?: string;
+}): BudgetCheck;
+/** The user wrote to the assistant within the last `withinHours`. */
+export declare function recentInteraction(options: {
+    withinHours: number;
+}): Check;
+/** At most `limit` deliveries in the `withinHours` window that opened with the user's last inbound message. */
+export declare function windowBudget(options: {
+    limit: number;
+    withinHours: number;
 }): BudgetCheck;
 /** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
 export declare function defaultChecks(options?: {

package/dist/src/checks.js

@@ -2,6 +2,7 @@ import { PRIORITY_RANK } from "./types.js";
 const pass = { kind: "pass" };
 const reject = (reason) => ({ kind: "reject", reason });
 const skip = (reason) => ({ kind: "skip", reason });
+const defer = (reason, retryAt) => ({ kind: "defer", reason, retryAt });
 const atLeast = (priority, floor) => PRIORITY_RANK[priority] >= PRIORITY_RANK[floor];
 const toDate = (value) => {
     if (value === null || value === undefined)
@@ -37,6 +38,7 @@ export function inWindow(minutes, start, end) {
         return false;
     return start < end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
 }
+const localDay = (now, timezone) => (timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10));
 /* ------------------------------------------------------------------------ */
 /* The checks, in the order LILA runs them. Compose your own order freely.  */
 /* ------------------------------------------------------------------------ */
@@ -72,13 +74,16 @@ export function mode(options) {
             : pass,
     };
 }
-/** A global pause until an instant. */
-export function snooze() {
+/** A global pause until an instant. With `defer: true` the decision carries the instant as `retryAt` instead of rejecting. */
+export function snooze(options = {}) {
     return {
         id: "snooze",
         run: ({ user, now }) => {
             const until = toDate(user.snoozedUntil);
-            return until && until > now ? reject(`snoozed until ${until.toISOString()}`) : pass;
+            if (!until || until <= now)
+                return pass;
+            const reason = `snoozed until ${until.toISOString()}`;
+            return options.defer ? defer(reason, until) : reject(reason);
         },
     };
 }
@@ -196,21 +201,30 @@ export function adaptiveTiming(options = {}) {
         },
     };
 }
-export function dailyBudget(options = {}) {
-    const limit = options.limit ?? 5;
+function budget(spec, options) {
+    const limit = options.limit ?? spec.defaultLimit;
+    const nearAt = Math.max(1, Math.ceil(limit * (options.nearLimit ?? 0.8)));
+    const bypass = (priority) => options.bypassPriority !== undefined && atLeast(priority, options.bypassPriority);
     return {
-        id: "dailyBudget",
+        id: spec.id,
         limit,
-        async run({ user, now, store, priority }) {
-            if (options.bypassPriority && atLeast(priority, options.bypassPriority))
+        async run(ctx) {
+            if (bypass(ctx.priority))
                 return pass;
-            const key = budgetKey(user.id, now, user.timezone);
-            const used = Number((await store.get(key)) ?? 0);
-            return used < limit ? pass : reject(`daily budget of ${limit} used (${used})`);
+            const used = Number((await ctx.store.get(spec.keyFor(ctx))) ?? 0);
+            if (used >= limit)
+                return reject(`${spec.label} of ${limit} used (${used})`);
+            return used >= nearAt ? { kind: "pass", reason: `${used} of ${limit} used`, nearLimit: { used, limit } } : pass;
+        },
+        async consume(ctx) {
+            if (bypass(ctx.priority))
+                return true;
+            const used = await ctx.store.incr(spec.keyFor(ctx), spec.ttlSeconds);
+            return used <= limit;
         },
     };
 }
-export const budgetKey = (userId, now, timezone) => `budget:${userId}:${timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10)}`;
+export const budgetKey = (userId, now, timezone) => `budget:${userId}:${localDay(now, timezone)}`;
 const isoWeekKey = (day) => {
     const date = new Date(`${day}T00:00:00Z`);
     const weekday = date.getUTCDay() || 7;
@@ -219,24 +233,135 @@ const isoWeekKey = (day) => {
     const week = Math.ceil((((date.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
     return `${date.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
 };
-export const weeklyBudgetKey = (userId, now, timezone) => {
-    const day = timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10);
-    return `weeklyBudget:${userId}:${isoWeekKey(day)}`;
-};
+export const weeklyBudgetKey = (userId, now, timezone) => `weeklyBudget:${userId}:${isoWeekKey(localDay(now, timezone))}`;
+export const monthlyBudgetKey = (userId, now, timezone) => `monthlyBudget:${userId}:${localDay(now, timezone).slice(0, 7)}`;
+/** At most `limit` deliveries per user per local day. */
+export function dailyBudget(options = {}) {
+    return budget({ id: "dailyBudget", label: "daily budget", defaultLimit: 5, keyFor: ({ user, now }) => budgetKey(user.id, now, user.timezone), ttlSeconds: 2 * DAY_SECONDS }, options);
+}
+/** At most `limit` deliveries per user per local ISO week. */
 export function weeklyBudget(options = {}) {
-    const limit = options.limit ?? 20;
+    return budget({ id: "weeklyBudget", label: "weekly budget", defaultLimit: 20, keyFor: ({ user, now }) => weeklyBudgetKey(user.id, now, user.timezone), ttlSeconds: 8 * DAY_SECONDS }, options);
+}
+/** At most `limit` deliveries per user per local calendar month. */
+export function monthlyBudget(options = {}) {
+    return budget({ id: "monthlyBudget", label: "monthly budget", defaultLimit: 60, keyFor: ({ user, now }) => monthlyBudgetKey(user.id, now, user.timezone), ttlSeconds: 32 * DAY_SECONDS }, options);
+}
+/* ------------------------------------------------------------------------ */
+/* Optional, caller-fed checks. Off by default; the package ships no model.  */
+/* ------------------------------------------------------------------------ */
+/**
+ * Horvitz's expected-utility rule with the PRISM threshold: act only when the
+ * caller's estimate of acceptance clears tau = cFA / (cFA + pNeed * cFN).
+ * `candidate.pAccept` and `candidate.pNeed` come from the caller's own model.
+ */
+export function utilityFloor(options) {
+    const { costFalseAlarm: cFA, costMissedHelp: cFN } = options;
     return {
-        id: "weeklyBudget",
-        limit,
-        async run({ user, now, store, priority }) {
-            if (options.bypassPriority && atLeast(priority, options.bypassPriority))
+        id: "utilityFloor",
+        run: ({ candidate }) => {
+            if (typeof candidate.pAccept !== "number")
+                return skip("no pAccept on the candidate; utility floor cannot be evaluated");
+            const pNeed = typeof candidate.pNeed === "number" ? candidate.pNeed : 1;
+            const tau = cFA / (cFA + pNeed * cFN);
+            return candidate.pAccept >= tau ? pass : reject(`pAccept ${round3(candidate.pAccept)} < tau ${round3(tau)}`);
+        },
+    };
+}
+const round3 = (n) => Math.round(n * 1000) / 1000;
+/**
+ * Bounded deferral (Horvitz): when the user is busy, wait t* = min(bound,
+ * lambda * interruptCost / (2 * staleness)), the optimum of a quadratic
+ * staleness loss against the cost of interrupting a busy person, with the
+ * user becoming free at rate lambda. Never rejects; only moves deliverAt.
+ */
+export function boundedDeferral(options = {}) {
+    const lambda = options.lambda ?? 1 / 43;
+    const cost = options.interruptCost ?? 1;
+    const staleness = options.staleness ?? 0.0001;
+    const bound = options.boundSeconds ?? 240;
+    const tStar = Math.min(bound, (lambda * cost) / (2 * staleness));
+    return {
+        id: "boundedDeferral",
+        nonRejecting: true,
+        run: (ctx) => {
+            const busy = options.isBusy ? options.isBusy(ctx) : ctx.candidate.busy === true;
+            if (!busy)
                 return pass;
-            const key = weeklyBudgetKey(user.id, now, user.timezone);
-            const used = Number((await store.get(key)) ?? 0);
-            return used < limit ? pass : reject(`weekly budget of ${limit} used (${used})`);
+            const at = new Date(ctx.now.getTime() + Math.round(tStar * 1000));
+            return { kind: "adjust", reason: `user busy; deliver at ${at.toISOString()} (t* ${Math.round(tStar)} s)`, deliverAt: at };
         },
     };
 }
+/* ------------------------------------------------------------------------ */
+/* Primitives the presets compose.                                           */
+/* ------------------------------------------------------------------------ */
+const zoneOf = (ctx, timezone) => (timezone === "user" ? ctx.user.timezone : timezone);
+/** Deliveries only inside [start, end) local time in a fixed zone or the user's. */
+export function allowedWindow(options) {
+    const start = parseHHMM(options.start);
+    const end = parseHHMM(options.end);
+    return {
+        id: options.id ?? "allowedWindow",
+        run: (ctx) => {
+            const zone = zoneOf(ctx, options.timezone);
+            if (!zone)
+                return skip("no timezone on the user; window cannot be evaluated");
+            if (options.priorityFloor && atLeast(ctx.priority, options.priorityFloor))
+                return pass;
+            const { minutes } = localClock(ctx.now, zone);
+            return inWindow(minutes, start, end) ? pass : reject(`outside the allowed window ${options.start} to ${options.end} ${zone}`);
+        },
+    };
+}
+/** Requires `user.consents[name]`, always or only inside a local-time window. */
+export function requiresConsent(options) {
+    const when = options.when ? { start: parseHHMM(options.when.start), end: parseHHMM(options.when.end), timezone: options.when.timezone } : null;
+    return {
+        id: options.id ?? `consent:${options.name}`,
+        run: (ctx) => {
+            if (when) {
+                const zone = zoneOf(ctx, when.timezone);
+                if (!zone)
+                    return skip("no timezone on the user; consent window cannot be evaluated");
+                if (!inWindow(localClock(ctx.now, zone).minutes, when.start, when.end))
+                    return pass;
+            }
+            return ctx.user.consents?.[options.name] ? pass : reject(`consent "${options.name}" is missing${when ? ` (required ${options.when.start} to ${options.when.end})` : ""}`);
+        },
+    };
+}
+/** Fixed-window rate limit keyed by user or by candidate.channel; consumed at commit. */
+export function rateLimit(options) {
+    const keyBy = options.keyBy ?? "user";
+    const keyFor = (ctx) => {
+        const scope = keyBy === "channel" ? ctx.candidate.channel ?? ctx.user.id : ctx.user.id;
+        return `rate:${keyBy}:${scope}:${options.perSeconds}:${Math.floor(ctx.now.getTime() / 1000 / options.perSeconds)}`;
+    };
+    const id = options.id ?? `rate:${options.limit}/${options.perSeconds}s`;
+    return budget({ id, label: `rate limit ${options.limit} per ${options.perSeconds} s`, defaultLimit: options.limit, keyFor, ttlSeconds: options.perSeconds * 2 }, { limit: options.limit, nearLimit: 1 });
+}
+/** The user wrote to the assistant within the last `withinHours`. */
+export function recentInteraction(options) {
+    return {
+        id: "recentInteraction",
+        run: ({ user, now }) => {
+            const last = toDate(user.lastInboundAt);
+            if (!last)
+                return reject("no inbound message from the user on record");
+            const age = (now.getTime() - last.getTime()) / 3600000;
+            return age <= options.withinHours ? pass : reject(`last inbound message ${Math.floor(age)} h ago, window is ${options.withinHours} h`);
+        },
+    };
+}
+/** At most `limit` deliveries in the `withinHours` window that opened with the user's last inbound message. */
+export function windowBudget(options) {
+    const keyFor = ({ user }) => {
+        const last = toDate(user.lastInboundAt);
+        return `windowBudget:${user.id}:${last ? Math.floor(last.getTime() / 1000) : "none"}`;
+    };
+    return budget({ id: "windowBudget", label: `window budget`, defaultLimit: options.limit, keyFor, ttlSeconds: options.withinHours * 3600 }, { limit: options.limit, nearLimit: 1 });
+}
 /** The LILA order, as a starting point. Replace, reorder, or drop checks freely. */
 export function defaultChecks(options = {}) {
     return [

package/dist/src/cli.d.ts

@@ -1,6 +1,19 @@
 #!/usr/bin/env node
 import type { Gate } from "./gate.js";
-import type { Decision } from "./types.js";
+import type { Decision, EvaluateInput } from "./types.js";
 export declare function loadPolicy(path?: string): Promise<Gate>;
 export declare function replay(lines: string[], gate: Gate, commit: boolean): Promise<Decision[]>;
 export declare function summarize(decisions: Decision[]): string;
+interface PreToolUseEvent {
+    tool_name?: string;
+    tool_input?: {
+        gate?: {
+            user: EvaluateInput["user"];
+            candidate: EvaluateInput["candidate"];
+            now?: string;
+        };
+    };
+}
+/** Turns a PreToolUse event into the hook output Claude Code expects, or null when the tool does not match. */
+export declare function hookDecision(event: PreToolUseEvent, gate: Gate, tool: string): Promise<string | null>;
+export {};

package/dist/src/cli.js

@@ -1,31 +1,65 @@
 #!/usr/bin/env node
 /**
- * proactive-gate replay <events.jsonl> [--policy <module>] [--json]
+ * proactive-gate replay <events.jsonl> [--policy <file>] [--json] [--commit]
+ * proactive-gate replay --fixtures <dir>
+ * proactive-gate hook --policy <file> [--tool <name>]
  *
- * Replays candidate messages through a gate and prints why each one was or
+ * replay feeds candidate messages through a gate and prints why each one was or
  * was not allowed. Each JSONL line is an EvaluateInput: { user, candidate, now? }.
- * The policy module must export `gate` (a Gate) or default-export one; without
- * --policy the default check order runs against an in-memory store.
+ * A policy is a JSON document (spec/schema/policy.schema.json) or an ES module
+ * that exports `gate`; without --policy the default check order runs against an
+ * in-memory store. --fixtures runs the conformance suite instead.
+ *
+ * hook reads a Claude Code PreToolUse event on stdin and prints a permission
+ * decision for the matching tool.
  */
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { resolve } from "node:path";
+import { createRequire } from "node:module";
 import { createGate } from "./gate.js";
 import { defaultChecks } from "./checks.js";
-const HELP = `usage: proactive-gate replay <events.jsonl> [--policy <module.js>] [--json] [--commit]
+import { loadFixtures, readSkips, runFixture } from "./conformance.js";
+import { FRAMEWORKS, listText, plan } from "./init.js";
+const HELP = `usage: proactive-gate init [--preset <name>] [--framework <name>] [--out <file>]
+       proactive-gate replay <events.jsonl> [--policy <file>] [--json] [--commit]
+       proactive-gate replay --fixtures <dir> [--skip <file>]
+       proactive-gate hook --policy <file> [--tool <name>]
+
+init writes a policy you can read and edit, and prints the lines that wire it in.
 
-Replays candidates through a gate and reports what was allowed and why not.
+  --preset <name>    a platform or legal preset to append (see --list)
+  --framework <name> ${FRAMEWORKS.join(", ")} (default none)
+  --out <file>       where to write (default proactive-gate.policy.json)
+  --force            overwrite an existing file
+  --list             print the presets and frameworks and exit
 
-  --policy <module>  ES module exporting \`gate\` (or default) built with createGate()
+replay reports what was allowed and why not.
+
+  --policy <file>    policy.json (spec/schema/policy.schema.json) or an ES module
+                     exporting \`gate\` (or default) built with createGate()
   --json             one Decision per line instead of the summary table
-  --commit           also call gate.commit() for allowed decisions, so the daily
-                     budget is consumed in order, as it would be in production
+  --commit           also call gate.commit() for allowed decisions, so budgets are
+                     consumed in order, as they would be in production
+  --fixtures <dir>   run the conformance fixtures under <dir> and report failures
+  --skip <file>      fixture names to skip, one per line (default spec/skip/ts.txt)
+
+hook reads a PreToolUse event (JSON) on stdin; when tool_name matches --tool
+(default send_message) it evaluates tool_input.gate = { user, candidate, now? }
+and prints a permissionDecision. Other tools print nothing.
+
   -h, --help         this text
+  --version          print the version
 
-Each line of the file is {"user": {...}, "candidate": {...}, "now": "ISO date"}.`;
+Each line of an events file is {"user": {...}, "candidate": {...}, "now": "ISO date"}.`;
 export async function loadPolicy(path) {
     if (!path)
         return createGate({ checks: defaultChecks() });
+    if (path.endsWith(".json")) {
+        const policy = JSON.parse(await readFile(path, "utf8"));
+        return createGate({ policy });
+    }
     const mod = await import(pathToFileURL(resolve(path)).href);
     const gate = mod.gate ?? mod.default;
     if (!gate || typeof gate.evaluate !== "function")
@@ -50,8 +84,8 @@ export async function replay(lines, gate, commit) {
             const ok = await gate.commit(decision, input);
             if (!ok) {
                 decision.allowed = false;
-                decision.rejectedBy = "dailyBudget";
-                decision.reason = "daily budget exhausted at commit";
+                decision.rejectedBy = "commit";
+                decision.reason = "a budget was exhausted at commit";
             }
         }
         decisions.push(decision);
@@ -60,23 +94,26 @@ export async function replay(lines, gate, commit) {
 }
 export function summarize(decisions) {
     const allowed = decisions.filter((d) => d.allowed).length;
+    const deferred = decisions.filter((d) => d.deferredBy).length;
     const byCheck = new Map();
     const sample = new Map();
     for (const d of decisions) {
-        if (d.allowed || !d.rejectedBy)
+        const by = d.rejectedBy ?? d.deferredBy;
+        if (d.allowed || !by)
             continue;
-        byCheck.set(d.rejectedBy, (byCheck.get(d.rejectedBy) ?? 0) + 1);
-        if (!sample.has(d.rejectedBy) && d.reason)
-            sample.set(d.rejectedBy, d.reason);
+        byCheck.set(by, (byCheck.get(by) ?? 0) + 1);
+        if (!sample.has(by) && d.reason)
+            sample.set(by, d.reason);
     }
-    const deferred = decisions.filter((d) => d.allowed && d.deliverAt).length;
+    const later = decisions.filter((d) => d.allowed && d.deliverAt).length;
+    const shadowed = decisions.reduce((n, d) => n + d.shadowed.length, 0);
     const lines = [
-        `${decisions.length} candidates  ·  ${allowed} allowed (${pct(allowed, decisions.length)})  ·  ${decisions.length - allowed} rejected${deferred ? `  ·  ${deferred} deferred to a later moment` : ""}`,
+        `${decisions.length} candidates  ·  ${allowed} allowed (${pct(allowed, decisions.length)})  ·  ${decisions.length - allowed - deferred} rejected${deferred ? `  ·  ${deferred} deferred` : ""}${later ? `  ·  ${later} moved to a later moment` : ""}${shadowed ? `  ·  ${shadowed} shadow rejections` : ""}`,
         "",
     ];
     if (byCheck.size) {
         const w = Math.max(...[...byCheck.keys()].map((k) => k.length), 5);
-        lines.push(`${"check".padEnd(w)}  ${"rejected".padStart(8)}  example`);
+        lines.push(`${"check".padEnd(w)}  ${"stopped".padStart(8)}  example`);
         lines.push("-".repeat(w + 2 + 8 + 2 + 40));
         for (const [id, n] of [...byCheck.entries()].sort((a, b) => b[1] - a[1])) {
             lines.push(`${id.padEnd(w)}  ${String(n).padStart(8)}  ${sample.get(id) ?? ""}`);
@@ -88,19 +125,112 @@ export function summarize(decisions) {
     return lines.join("\n");
 }
 const pct = (n, total) => (total ? `${((100 * n) / total).toFixed(1)}%` : "0%");
+const argValue = (argv, flag) => {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? argv[i + 1] : undefined;
+};
+async function runFixtures(dir, skipFile) {
+    const fixtures = await loadFixtures(dir);
+    const skips = await readSkips(skipFile ?? resolve(dir, "..", "skip", "ts.txt"));
+    let failed = 0;
+    let skipped = 0;
+    for (const fixture of fixtures) {
+        const reason = skips.get(fixture.name);
+        if (reason !== undefined) {
+            skipped++;
+            console.log(`skip  ${fixture.name}  (${reason})`);
+            continue;
+        }
+        const failures = await runFixture(fixture);
+        if (failures.length) {
+            failed++;
+            console.log(`FAIL  ${fixture.name}`);
+            for (const f of failures)
+                console.log(`      ${f}`);
+        }
+        else {
+            console.log(`ok    ${fixture.name}`);
+        }
+    }
+    console.log(`${fixtures.length - failed - skipped} passed, ${failed} failed, ${skipped} skipped`);
+    return failed ? 1 : 0;
+}
+/** Turns a PreToolUse event into the hook output Claude Code expects, or null when the tool does not match. */
+export async function hookDecision(event, gate, tool) {
+    if (event.tool_name !== tool)
+        return null;
+    const payload = event.tool_input?.gate;
+    const out = (permissionDecision, permissionDecisionReason) => JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason } });
+    if (!payload?.user || !payload.candidate)
+        return out("deny", "tool_input.gate must carry { user, candidate } for proactive-gate to decide");
+    const decision = await gate.evaluate({ user: payload.user, candidate: payload.candidate, ...(payload.now ? { now: new Date(payload.now) } : {}) });
+    if (decision.allowed) {
+        const ok = await gate.commit(decision, { user: payload.user, candidate: payload.candidate, ...(decision.evaluatedAt ? { now: decision.evaluatedAt } : {}) });
+        return ok ? out("allow", `proactive-gate: allowed on ${decision.surfaces.join(",")}${decision.deliverAt ? `, deliver at ${decision.deliverAt.toISOString()}` : ""}`) : out("deny", "proactive-gate: a budget was exhausted at commit");
+    }
+    if (decision.deferredBy)
+        return out("deny", `proactive-gate: deferred by ${decision.deferredBy} until ${decision.retryAt?.toISOString()} (${decision.reason})`);
+    return out("deny", `proactive-gate: rejected by ${decision.rejectedBy} (${decision.reason})`);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+const VERSION = createRequire(import.meta.url)("../../package.json").version;
 async function main(argv) {
+    if (argv.includes("--version")) {
+        console.log(VERSION);
+        return;
+    }
     if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
         console.log(HELP);
         return;
     }
     const [command, file] = argv;
-    if (command !== "replay" || !file) {
+    if (command === "init") {
+        if (argv.includes("--list")) {
+            console.log(listText());
+            return;
+        }
+        const out = argValue(argv, "--out") ?? "proactive-gate.policy.json";
+        const presetName = argValue(argv, "--preset");
+        const frameworkName = argValue(argv, "--framework");
+        const { policy, message } = plan({
+            ...(presetName === undefined ? {} : { preset: presetName }),
+            ...(frameworkName === undefined ? {} : { framework: frameworkName }),
+            out,
+        });
+        if (!argv.includes("--force") && existsSync(out)) {
+            console.error(`${out} already exists; pass --force to overwrite it`);
+            process.exit(1);
+        }
+        await writeFile(out, policy);
+        console.log(message);
+        return;
+    }
+    if (command === "hook") {
+        const gate = await loadPolicy(argValue(argv, "--policy"));
+        const event = JSON.parse((await readStdin()) || "{}");
+        const output = await hookDecision(event, gate, argValue(argv, "--tool") ?? "send_message");
+        if (output)
+            console.log(output);
+        return;
+    }
+    if (command !== "replay") {
+        console.error(HELP);
+        process.exit(2);
+    }
+    const fixtures = argValue(argv, "--fixtures");
+    if (fixtures) {
+        process.exit(await runFixtures(fixtures, argValue(argv, "--skip")));
+    }
+    if (!file || file.startsWith("--")) {
         console.error(HELP);
         process.exit(2);
     }
-    const policyIndex = argv.indexOf("--policy");
-    const policy = policyIndex >= 0 ? argv[policyIndex + 1] : undefined;
-    const gate = await loadPolicy(policy);
+    const gate = await loadPolicy(argValue(argv, "--policy"));
     const text = await readFile(file, "utf8");
     const decisions = await replay(text.split("\n"), gate, argv.includes("--commit"));
     if (argv.includes("--json")) {

package/dist/src/conformance.d.ts

@@ -0,0 +1,42 @@
+import type { Candidate, Policy, UserState } from "./types.js";
+export interface FixtureExpect {
+    allowed: boolean;
+    rejectedBy?: string;
+    deferredBy?: string;
+    retryAt?: string;
+    surfaces?: string[];
+    deliverAt?: string;
+    trace: string[];
+    shadowed?: string[];
+    nearLimit?: Array<{
+        check: string;
+        used: number;
+        limit: number;
+    }>;
+    reason_pattern?: string;
+    commit?: boolean;
+    store_after?: Record<string, string>;
+}
+export interface FixtureTest {
+    description: string;
+    input: {
+        user: UserState;
+        candidate: Candidate;
+        now: string;
+    };
+    commit?: boolean;
+    expect: FixtureExpect;
+}
+export interface Fixture {
+    spec_version: string;
+    since: string;
+    name: string;
+    description: string;
+    policy: Policy;
+    store_seed?: Record<string, string>;
+    tests: FixtureTest[];
+}
+export declare function loadFixtures(dir: string): Promise<Fixture[]>;
+export declare function readSkips(file: string): Promise<Map<string, string>>;
+/** Runs one fixture and returns the list of mismatches, empty when it conforms. */
+export declare function runFixture(fixture: Fixture): Promise<string[]>;