@agentguard-run/burn 0.1.1 → 0.2.1

package/dist/src/hook/pre-tool-use.d.ts

@@ -15,7 +15,7 @@
  * as little as possible.
  */
 import { type ReaderCursor } from '../history/claude-transcript';
-import type { Policy, SessionState } from '../types';
+import type { BurnReport, Policy, SessionState } from '../types';
 export interface HookInput {
     session_id?: string;
     transcript_path?: string;
@@ -35,12 +35,36 @@ export interface HookOutput {
         permissionDecisionReason: string;
     };
 }
+export interface PersistedSession {
+    cursor: {
+        offset: number;
+        size: number;
+        malformedLines: number;
+        depthByUuid: [string, number][];
+    };
+    state: Omit<SessionState, 'tokensByActiveMinute' | 'spawnsByActiveMinute' | 'surfaceReaders'> & {
+        tokensByActiveMinute: [number, number][];
+        spawnsByActiveMinute: [number, number][];
+        surfaceReaders: [string, number[]][];
+    };
+    /** Signature of the last finding set the user was told about. */
+    notified?: string;
+}
+/** Inflate a persisted Claude Code session. Shared with status. */
+export declare function inflateHookSession(raw: PersistedSession): SessionState;
+/**
+ * Tell the user once per change, not once per spawn. Eighteen identical
+ * "WARN: 30 spawns" banners in a row train the user to stop reading them,
+ * and the one that matters is the nineteenth.
+ */
+export declare function findingSignature(report: BurnReport): string;
 export declare function loadPolicy(home: string): Policy;
 /** Refresh session state from the transcript. Cheap: only new bytes are read. */
 export declare function refreshSession(home: string, sessionId: string, transcriptPath: string): {
     cursor: ReaderCursor;
     state: SessionState;
     newSpawns: number;
+    notified: string;
 };
 export declare function handlePreToolUse(input: HookInput, home: string, now?: number): HookOutput;
 /** The settings.json fragment users paste in. Only PreToolUse can block. */

package/dist/src/hook/pre-tool-use.js

@@ -16,6 +16,8 @@
  * as little as possible.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.inflateHookSession = inflateHookSession;
+exports.findingSignature = findingSignature;
 exports.loadPolicy = loadPolicy;
 exports.refreshSession = refreshSession;
 exports.handlePreToolUse = handlePreToolUse;
@@ -27,28 +29,32 @@ const claude_transcript_1 = require("../history/claude-transcript");
 const reservations_1 = require("../state/reservations");
 const session_1 = require("../state/session");
 const defaults_1 = require("../defaults");
+const override_1 = require("../override");
 const render_1 = require("../replay/render");
 const SPAWN_TOOLS = new Set(['Agent', 'Task']);
 function sessionFile(home, sessionId) {
     return (0, node_path_1.join)(home, 'sessions', `${sessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
 }
+/** Inflate a persisted Claude Code session. Shared with status. */
+function inflateHookSession(raw) {
+    return {
+        ...raw.state,
+        tokensByActiveMinute: new Map(raw.state.tokensByActiveMinute),
+        spawnsByActiveMinute: new Map(raw.state.spawnsByActiveMinute),
+        surfaceReaders: new Map(raw.state.surfaceReaders.map(([k, v]) => [k, new Set(v)])),
+    };
+}
 function loadSession(home, sessionId, firstEventAt) {
     try {
         const raw = JSON.parse((0, node_fs_1.readFileSync)(sessionFile(home, sessionId), 'utf8'));
         const cursor = { ...raw.cursor, depthByUuid: new Map(raw.cursor.depthByUuid) };
-        const state = {
-            ...raw.state,
-            tokensByActiveMinute: new Map(raw.state.tokensByActiveMinute),
-            spawnsByActiveMinute: new Map(raw.state.spawnsByActiveMinute),
-            surfaceReaders: new Map(raw.state.surfaceReaders.map(([k, v]) => [k, new Set(v)])),
-        };
-        return { cursor, state };
+        return { cursor, state: inflateHookSession(raw), notified: raw.notified ?? '' };
     }
     catch {
-        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt) };
+        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '' };
     }
 }
-function saveSession(home, cursor, state) {
+function saveSession(home, cursor, state, notified) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(home, 'sessions'), { recursive: true, mode: 0o700 });
     const persisted = {
         cursor: { offset: cursor.offset, size: cursor.size, malformedLines: cursor.malformedLines, depthByUuid: [...cursor.depthByUuid] },
@@ -58,12 +64,24 @@ function saveSession(home, cursor, state) {
             spawnsByActiveMinute: [...state.spawnsByActiveMinute],
             surfaceReaders: [...state.surfaceReaders].map(([k, v]) => [k, [...v]]),
         },
+        notified,
     };
     const file = sessionFile(home, state.sessionId);
     (0, node_fs_1.writeFileSync)(`${file}.tmp`, JSON.stringify(persisted), { mode: 0o600 });
     // rename is atomic; a concurrent reader never sees a half-written file.
     require('node:fs').renameSync(`${file}.tmp`, file);
 }
+/**
+ * Tell the user once per change, not once per spawn. Eighteen identical
+ * "WARN: 30 spawns" banners in a row train the user to stop reading them,
+ * and the one that matters is the nineteenth.
+ */
+function findingSignature(report) {
+    return report.findings
+        .map((f) => `${f.detector}:${f.verdict}`)
+        .sort()
+        .join('|');
+}
 function loadPolicy(home) {
     try {
         const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, 'burn-policy.json'), 'utf8'));
@@ -81,15 +99,27 @@ function recordDecision(home, entry) {
 }
 /** Refresh session state from the transcript. Cheap: only new bytes are read. */
 function refreshSession(home, sessionId, transcriptPath) {
-    const { cursor, state } = loadSession(home, sessionId, Date.now());
+    const { cursor, state, notified } = loadSession(home, sessionId, Date.now());
     const before = state.spawnCount;
     const events = (0, claude_transcript_1.readIncremental)(transcriptPath, cursor);
     for (const event of events)
         (0, session_1.applyEvent)(state, event);
     if (events.length > 0 && state.startedAt > events[0].at)
         state.startedAt = events[0].at;
-    saveSession(home, cursor, state);
-    return { cursor, state, newSpawns: state.spawnCount - before };
+    saveSession(home, cursor, state, notified);
+    return { cursor, state, newSpawns: state.spawnCount - before, notified };
+}
+function rememberNotified(home, sessionId, signature) {
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)(sessionFile(home, sessionId), 'utf8'));
+        raw.notified = signature;
+        const file = sessionFile(home, sessionId);
+        (0, node_fs_1.writeFileSync)(`${file}.tmp`, JSON.stringify(raw), { mode: 0o600 });
+        require('node:fs').renameSync(`${file}.tmp`, file);
+    }
+    catch {
+        /* best effort; the worst case is one repeated banner */
+    }
 }
 function handlePreToolUse(input, home, now = Date.now()) {
     const toolName = input.tool_name ?? '';
@@ -100,8 +130,11 @@ function handlePreToolUse(input, home, now = Date.now()) {
     const store = new reservations_1.ReservationStore(home);
     let report;
     let reservation;
+    let notified = '';
     try {
-        const { state, newSpawns } = refreshSession(home, input.session_id, input.transcript_path);
+        const refreshed = refreshSession(home, input.session_id, input.transcript_path);
+        const { state, newSpawns } = refreshed;
+        notified = refreshed.notified;
         if (newSpawns > 0)
             store.reconcile(input.session_id, state.spawnCount, state.spawnCount - newSpawns);
         // Depth of the proposed child: the issuing agent's depth plus one. A hook
@@ -124,26 +157,41 @@ function handlePreToolUse(input, home, now = Date.now()) {
     }
     const shouldDeny = report.verdict === 'STOP' || !reservation.allowed;
     const reason = shouldDeny ? buildDenyReason(report, reservation) : '';
+    // The audited override: only consulted when a block is about to happen.
+    const override = shouldDeny && policy.mode === 'enforce' ? (0, override_1.consumeOverride)(home, now) : null;
     recordDecision(home, {
         at: now,
         sessionId: input.session_id,
         toolUseId: input.tool_use_id ?? null,
         verdict: report.verdict,
         wouldDeny: shouldDeny,
-        enforced: policy.mode === 'enforce' && shouldDeny,
+        enforced: policy.mode === 'enforce' && shouldDeny && !override,
+        overridden: override ? { once: override.once, reason: override.reason } : undefined,
         mode: policy.mode,
         findings: report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
         effectiveSpawns: reservation.effectiveSpawns,
         totals: report.totals,
     });
-    if (shouldDeny && policy.mode === 'enforce')
-        return deny(reason);
+    if (shouldDeny && policy.mode === 'enforce') {
+        if (!override)
+            return deny(reason);
+        return {
+            continue: true,
+            systemMessage: `AgentGuard STOP overridden${override.once ? ' once' : ''} ("${override.reason}"): ${report.findings[0]?.summary ?? ''}`,
+        };
+    }
     if (report.verdict !== 'OK') {
+        const signature = findingSignature(report);
+        if (signature === notified)
+            return { continue: true, suppressOutput: true };
+        rememberNotified(home, input.session_id, signature);
         return {
             continue: true,
             systemMessage: `AgentGuard ${report.verdict}${policy.mode === 'shadow' && shouldDeny ? ' (shadow: would have blocked)' : ''}: ${report.findings[0]?.summary ?? ''}`,
         };
     }
+    if (notified)
+        rememberNotified(home, input.session_id, '');
     return { continue: true, suppressOutput: true };
 }
 function buildDenyReason(report, _reservation) {

package/dist/src/index.d.ts

@@ -1,10 +1,25 @@
 export * from './types';
-export { DEFAULT_POLICY, DEFAULT_THRESHOLDS } from './defaults';
+export { DEFAULT_POLICY, DEFAULT_THRESHOLDS, DEFAULT_LOCAL_COMPUTE, CALL_RESERVATION_TTL_MS } from './defaults';
 export { evaluate, fmt } from './detectors/evaluate';
+export { evaluateLocalCompute } from './detectors/local-compute';
 export { readIncremental, readAll, newCursor, normaliseLine, type ReaderCursor } from './history/claude-transcript';
-export { applyEvent, newSessionState, windowSum, medianCompletedMinute, cacheReadRatio } from './state/session';
-export { ReservationStore, RESERVATION_TTL_MS } from './state/reservations';
+export { applyEvent, applyCorrection, newSessionState, windowSum, medianCompletedMinute, cacheReadRatio } from './state/session';
+export { ReservationStore, Transaction, RESERVATION_TTL_MS, type Reservation, type CallReservation, type ComputeSnapshot } from './state/reservations';
 export { replayAll, replaySession, replayEvents, discoverTranscripts, type ReplaySummary, type SessionReplay } from './replay/simulate';
-export { renderReplay } from './replay/render';
+export { renderReplay, renderStop } from './replay/render';
 export { calibrate, type CalibrationResult } from './calibrate';
 export { handlePreToolUse, refreshSession, loadPolicy, settingsSnippet, type HookInput, type HookOutput } from './hook/pre-tool-use';
+export * from './events';
+export { Gateway, mergeCapabilities, type Decision, type GatewaySessionView, type UsageCoverage, type GatewayOptions } from './gateway';
+export { ReceiptSigner, verifyReceipt, receiptDigest, canonical, sha256, type ReceiptPayload, type SignedReceipt } from './receipt';
+export { createRawApiGuard, BurnStopError, type RawApiGuard, type RawGuardOptions } from './adapters/raw-api';
+export { handleCursorHook, cursorHooksSnippet, type CursorHookOutput } from './adapters/cursor';
+export { handleCodexHook, codexHooksSnippet, parseCodexTranscript, readCodexTranscriptUsage, CODEX_FORBIDDEN_FIELDS, type CodexHookOutput } from './adapters/codex';
+export { startProxy, profileFor, type ProxyOptions, type ProxyHost, type RunningProxy } from './proxy/server';
+export { UsageObserver, type ProxyProfile, type ObservedUsage } from './proxy/usage-observer';
+export { renderMachineStatus } from './status';
+export { runConformance, type ConformanceResult } from './conformance';
+export { writeOverride, readOverride, consumeOverride, clearOverride, OVERRIDE_WINDOW_MS, type Override } from './override';
+export { install, health, configPath, type InstallHost, type InstallResult, type HostHealth } from './install';
+export { readHookSessions, renderHostHealth } from './status';
+export { findingSignature, inflateHookSession, type PersistedSession } from './hook/pre-tool-use';

package/dist/src/index.js

@@ -14,14 +14,19 @@ 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 });
-exports.settingsSnippet = exports.loadPolicy = exports.refreshSession = exports.handlePreToolUse = exports.calibrate = exports.renderReplay = exports.discoverTranscripts = exports.replayEvents = exports.replaySession = exports.replayAll = exports.RESERVATION_TTL_MS = exports.ReservationStore = exports.cacheReadRatio = exports.medianCompletedMinute = exports.windowSum = exports.newSessionState = exports.applyEvent = exports.normaliseLine = exports.newCursor = exports.readAll = exports.readIncremental = exports.fmt = exports.evaluate = exports.DEFAULT_THRESHOLDS = exports.DEFAULT_POLICY = void 0;
+exports.UsageObserver = exports.profileFor = exports.startProxy = exports.CODEX_FORBIDDEN_FIELDS = exports.readCodexTranscriptUsage = exports.parseCodexTranscript = exports.codexHooksSnippet = exports.handleCodexHook = exports.cursorHooksSnippet = exports.handleCursorHook = exports.BurnStopError = exports.createRawApiGuard = exports.sha256 = exports.canonical = exports.receiptDigest = exports.verifyReceipt = exports.ReceiptSigner = exports.mergeCapabilities = exports.Gateway = exports.settingsSnippet = exports.loadPolicy = exports.refreshSession = exports.handlePreToolUse = exports.calibrate = exports.renderStop = exports.renderReplay = exports.discoverTranscripts = exports.replayEvents = exports.replaySession = exports.replayAll = exports.RESERVATION_TTL_MS = exports.Transaction = exports.ReservationStore = exports.cacheReadRatio = exports.medianCompletedMinute = exports.windowSum = exports.newSessionState = exports.applyCorrection = exports.applyEvent = exports.normaliseLine = exports.newCursor = exports.readAll = exports.readIncremental = exports.evaluateLocalCompute = exports.fmt = exports.evaluate = exports.CALL_RESERVATION_TTL_MS = exports.DEFAULT_LOCAL_COMPUTE = exports.DEFAULT_THRESHOLDS = exports.DEFAULT_POLICY = void 0;
+exports.inflateHookSession = exports.findingSignature = exports.renderHostHealth = exports.readHookSessions = exports.configPath = exports.health = exports.install = exports.OVERRIDE_WINDOW_MS = exports.clearOverride = exports.consumeOverride = exports.readOverride = exports.writeOverride = exports.runConformance = exports.renderMachineStatus = void 0;
 __exportStar(require("./types"), exports);
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "DEFAULT_POLICY", { enumerable: true, get: function () { return defaults_1.DEFAULT_POLICY; } });
 Object.defineProperty(exports, "DEFAULT_THRESHOLDS", { enumerable: true, get: function () { return defaults_1.DEFAULT_THRESHOLDS; } });
+Object.defineProperty(exports, "DEFAULT_LOCAL_COMPUTE", { enumerable: true, get: function () { return defaults_1.DEFAULT_LOCAL_COMPUTE; } });
+Object.defineProperty(exports, "CALL_RESERVATION_TTL_MS", { enumerable: true, get: function () { return defaults_1.CALL_RESERVATION_TTL_MS; } });
 var evaluate_1 = require("./detectors/evaluate");
 Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return evaluate_1.evaluate; } });
 Object.defineProperty(exports, "fmt", { enumerable: true, get: function () { return evaluate_1.fmt; } });
+var local_compute_1 = require("./detectors/local-compute");
+Object.defineProperty(exports, "evaluateLocalCompute", { enumerable: true, get: function () { return local_compute_1.evaluateLocalCompute; } });
 var claude_transcript_1 = require("./history/claude-transcript");
 Object.defineProperty(exports, "readIncremental", { enumerable: true, get: function () { return claude_transcript_1.readIncremental; } });
 Object.defineProperty(exports, "readAll", { enumerable: true, get: function () { return claude_transcript_1.readAll; } });
@@ -29,12 +34,14 @@ Object.defineProperty(exports, "newCursor", { enumerable: true, get: function ()
 Object.defineProperty(exports, "normaliseLine", { enumerable: true, get: function () { return claude_transcript_1.normaliseLine; } });
 var session_1 = require("./state/session");
 Object.defineProperty(exports, "applyEvent", { enumerable: true, get: function () { return session_1.applyEvent; } });
+Object.defineProperty(exports, "applyCorrection", { enumerable: true, get: function () { return session_1.applyCorrection; } });
 Object.defineProperty(exports, "newSessionState", { enumerable: true, get: function () { return session_1.newSessionState; } });
 Object.defineProperty(exports, "windowSum", { enumerable: true, get: function () { return session_1.windowSum; } });
 Object.defineProperty(exports, "medianCompletedMinute", { enumerable: true, get: function () { return session_1.medianCompletedMinute; } });
 Object.defineProperty(exports, "cacheReadRatio", { enumerable: true, get: function () { return session_1.cacheReadRatio; } });
 var reservations_1 = require("./state/reservations");
 Object.defineProperty(exports, "ReservationStore", { enumerable: true, get: function () { return reservations_1.ReservationStore; } });
+Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return reservations_1.Transaction; } });
 Object.defineProperty(exports, "RESERVATION_TTL_MS", { enumerable: true, get: function () { return reservations_1.RESERVATION_TTL_MS; } });
 var simulate_1 = require("./replay/simulate");
 Object.defineProperty(exports, "replayAll", { enumerable: true, get: function () { return simulate_1.replayAll; } });
@@ -43,6 +50,7 @@ Object.defineProperty(exports, "replayEvents", { enumerable: true, get: function
 Object.defineProperty(exports, "discoverTranscripts", { enumerable: true, get: function () { return simulate_1.discoverTranscripts; } });
 var render_1 = require("./replay/render");
 Object.defineProperty(exports, "renderReplay", { enumerable: true, get: function () { return render_1.renderReplay; } });
+Object.defineProperty(exports, "renderStop", { enumerable: true, get: function () { return render_1.renderStop; } });
 var calibrate_1 = require("./calibrate");
 Object.defineProperty(exports, "calibrate", { enumerable: true, get: function () { return calibrate_1.calibrate; } });
 var pre_tool_use_1 = require("./hook/pre-tool-use");
@@ -50,3 +58,51 @@ Object.defineProperty(exports, "handlePreToolUse", { enumerable: true, get: func
 Object.defineProperty(exports, "refreshSession", { enumerable: true, get: function () { return pre_tool_use_1.refreshSession; } });
 Object.defineProperty(exports, "loadPolicy", { enumerable: true, get: function () { return pre_tool_use_1.loadPolicy; } });
 Object.defineProperty(exports, "settingsSnippet", { enumerable: true, get: function () { return pre_tool_use_1.settingsSnippet; } });
+// Cross-tool layer (0.2.0)
+__exportStar(require("./events"), exports);
+var gateway_1 = require("./gateway");
+Object.defineProperty(exports, "Gateway", { enumerable: true, get: function () { return gateway_1.Gateway; } });
+Object.defineProperty(exports, "mergeCapabilities", { enumerable: true, get: function () { return gateway_1.mergeCapabilities; } });
+var receipt_1 = require("./receipt");
+Object.defineProperty(exports, "ReceiptSigner", { enumerable: true, get: function () { return receipt_1.ReceiptSigner; } });
+Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return receipt_1.verifyReceipt; } });
+Object.defineProperty(exports, "receiptDigest", { enumerable: true, get: function () { return receipt_1.receiptDigest; } });
+Object.defineProperty(exports, "canonical", { enumerable: true, get: function () { return receipt_1.canonical; } });
+Object.defineProperty(exports, "sha256", { enumerable: true, get: function () { return receipt_1.sha256; } });
+var raw_api_1 = require("./adapters/raw-api");
+Object.defineProperty(exports, "createRawApiGuard", { enumerable: true, get: function () { return raw_api_1.createRawApiGuard; } });
+Object.defineProperty(exports, "BurnStopError", { enumerable: true, get: function () { return raw_api_1.BurnStopError; } });
+var cursor_1 = require("./adapters/cursor");
+Object.defineProperty(exports, "handleCursorHook", { enumerable: true, get: function () { return cursor_1.handleCursorHook; } });
+Object.defineProperty(exports, "cursorHooksSnippet", { enumerable: true, get: function () { return cursor_1.cursorHooksSnippet; } });
+var codex_1 = require("./adapters/codex");
+Object.defineProperty(exports, "handleCodexHook", { enumerable: true, get: function () { return codex_1.handleCodexHook; } });
+Object.defineProperty(exports, "codexHooksSnippet", { enumerable: true, get: function () { return codex_1.codexHooksSnippet; } });
+Object.defineProperty(exports, "parseCodexTranscript", { enumerable: true, get: function () { return codex_1.parseCodexTranscript; } });
+Object.defineProperty(exports, "readCodexTranscriptUsage", { enumerable: true, get: function () { return codex_1.readCodexTranscriptUsage; } });
+Object.defineProperty(exports, "CODEX_FORBIDDEN_FIELDS", { enumerable: true, get: function () { return codex_1.CODEX_FORBIDDEN_FIELDS; } });
+var server_1 = require("./proxy/server");
+Object.defineProperty(exports, "startProxy", { enumerable: true, get: function () { return server_1.startProxy; } });
+Object.defineProperty(exports, "profileFor", { enumerable: true, get: function () { return server_1.profileFor; } });
+var usage_observer_1 = require("./proxy/usage-observer");
+Object.defineProperty(exports, "UsageObserver", { enumerable: true, get: function () { return usage_observer_1.UsageObserver; } });
+var status_1 = require("./status");
+Object.defineProperty(exports, "renderMachineStatus", { enumerable: true, get: function () { return status_1.renderMachineStatus; } });
+var conformance_1 = require("./conformance");
+Object.defineProperty(exports, "runConformance", { enumerable: true, get: function () { return conformance_1.runConformance; } });
+var override_1 = require("./override");
+Object.defineProperty(exports, "writeOverride", { enumerable: true, get: function () { return override_1.writeOverride; } });
+Object.defineProperty(exports, "readOverride", { enumerable: true, get: function () { return override_1.readOverride; } });
+Object.defineProperty(exports, "consumeOverride", { enumerable: true, get: function () { return override_1.consumeOverride; } });
+Object.defineProperty(exports, "clearOverride", { enumerable: true, get: function () { return override_1.clearOverride; } });
+Object.defineProperty(exports, "OVERRIDE_WINDOW_MS", { enumerable: true, get: function () { return override_1.OVERRIDE_WINDOW_MS; } });
+var install_1 = require("./install");
+Object.defineProperty(exports, "install", { enumerable: true, get: function () { return install_1.install; } });
+Object.defineProperty(exports, "health", { enumerable: true, get: function () { return install_1.health; } });
+Object.defineProperty(exports, "configPath", { enumerable: true, get: function () { return install_1.configPath; } });
+var status_2 = require("./status");
+Object.defineProperty(exports, "readHookSessions", { enumerable: true, get: function () { return status_2.readHookSessions; } });
+Object.defineProperty(exports, "renderHostHealth", { enumerable: true, get: function () { return status_2.renderHostHealth; } });
+var pre_tool_use_2 = require("./hook/pre-tool-use");
+Object.defineProperty(exports, "findingSignature", { enumerable: true, get: function () { return pre_tool_use_2.findingSignature; } });
+Object.defineProperty(exports, "inflateHookSession", { enumerable: true, get: function () { return pre_tool_use_2.inflateHookSession; } });

package/dist/src/install.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Installing the hook into each host's config, and checking it is there.
+ *
+ * Merging into a config file the user also edits by hand is the one place
+ * this tool can do damage, so: always a timestamped backup first, always a
+ * parse-before-write, always an atomic rename, and the AgentGuard entry is
+ * found by its command (any command mentioning agentguard-burn), so a
+ * re-run upgrades the path in place instead of stacking duplicates.
+ */
+export type InstallHost = 'claude' | 'cursor' | 'codex';
+export interface InstallResult {
+    file: string;
+    backup: string | null;
+    changed: boolean;
+    command: string;
+}
+export interface HostHealth {
+    host: InstallHost;
+    file: string;
+    installed: boolean;
+    command: string | null;
+    /** The script the command points at exists on disk. */
+    commandExists: boolean;
+    /** The host itself is present (its config dir or binary). */
+    hostPresent: boolean;
+}
+export declare function configPath(host: InstallHost, home?: string): string;
+export declare function install(host: InstallHost, cliPath: string, home?: string): InstallResult;
+export declare function health(host: InstallHost, home?: string): HostHealth;

package/dist/src/install.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Installing the hook into each host's config, and checking it is there.
+ *
+ * Merging into a config file the user also edits by hand is the one place
+ * this tool can do damage, so: always a timestamped backup first, always a
+ * parse-before-write, always an atomic rename, and the AgentGuard entry is
+ * found by its command (any command mentioning agentguard-burn), so a
+ * re-run upgrades the path in place instead of stacking duplicates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configPath = configPath;
+exports.install = install;
+exports.health = health;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const MARK = /agentguard-burn|agentguard-run\/burn/;
+function configPath(host, home = (0, node_os_1.homedir)()) {
+    return host === 'claude' ? (0, node_path_1.join)(home, '.claude', 'settings.json') : host === 'cursor' ? (0, node_path_1.join)(home, '.cursor', 'hooks.json') : (0, node_path_1.join)(home, '.codex', 'hooks.json');
+}
+function readJson(file) {
+    if (!(0, node_fs_1.existsSync)(file))
+        return {};
+    const text = (0, node_fs_1.readFileSync)(file, 'utf8');
+    if (!text.trim())
+        return {};
+    const parsed = JSON.parse(text); // throws on a corrupt file: we refuse to overwrite what we cannot read
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error(`${file} is not a JSON object`);
+    return parsed;
+}
+function writeJson(file, value) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(file, '..'), { recursive: true });
+    let backup = null;
+    if ((0, node_fs_1.existsSync)(file)) {
+        backup = `${file}.bak-${new Date().toISOString().replace(/[:.]/g, '').slice(0, 15)}`;
+        (0, node_fs_1.copyFileSync)(file, backup);
+    }
+    const tmp = `${file}.agentguard.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, file);
+    return backup;
+}
+/** Claude Code and Codex share the { hooks: { Event: [ { matcher, hooks: [ {command} ] } ] } } shape. */
+function mergeMatcherStyle(cfg, event, matcher, command, timeout) {
+    const hooks = (cfg.hooks ??= {});
+    const list = (hooks[event] ??= []);
+    let changed = false;
+    let found = false;
+    for (const m of list) {
+        for (const h of m.hooks ?? []) {
+            if (typeof h.command === 'string' && MARK.test(h.command)) {
+                found = true;
+                if (h.command !== command || m.matcher !== matcher || h.timeout !== timeout) {
+                    h.command = command;
+                    h.timeout = timeout;
+                    m.matcher = matcher;
+                    changed = true;
+                }
+            }
+        }
+    }
+    if (!found) {
+        list.push({ matcher, hooks: [{ type: 'command', command, timeout }] });
+        changed = true;
+    }
+    return changed;
+}
+/** Cursor: { version: 1, hooks: { subagentStart: [ {command, timeout, failClosed} ] } } */
+function mergeCursor(cfg, command) {
+    let changed = false;
+    if (cfg.version !== 1) {
+        cfg.version = 1;
+        changed = true;
+    }
+    const hooks = (cfg.hooks ??= {});
+    const want = {
+        subagentStart: { command, timeout: 5, failClosed: true },
+        subagentStop: { command, timeout: 5 },
+        sessionEnd: { command, timeout: 3 },
+    };
+    for (const [event, entry] of Object.entries(want)) {
+        const list = (hooks[event] ??= []);
+        const mine = list.find((h) => typeof h.command === 'string' && MARK.test(h.command));
+        if (!mine) {
+            list.push(entry);
+            changed = true;
+        }
+        else if (JSON.stringify(mine) !== JSON.stringify({ ...mine, ...entry })) {
+            Object.assign(mine, entry);
+            changed = true;
+        }
+    }
+    return changed;
+}
+function install(host, cliPath, home = (0, node_os_1.homedir)()) {
+    const file = configPath(host, home);
+    const cfg = readJson(file);
+    let command;
+    let changed;
+    if (host === 'claude') {
+        command = `node ${cliPath} hook`;
+        changed = mergeMatcherStyle(cfg, 'PreToolUse', '^(Agent|Task)$', command, 5);
+    }
+    else if (host === 'codex') {
+        command = `node ${cliPath} codex-hook`;
+        changed = mergeMatcherStyle(cfg, 'PreToolUse', '^(Agent|spawn_agent)$', command, 5);
+    }
+    else {
+        command = `node ${cliPath} cursor-hook`;
+        changed = mergeCursor(cfg, command);
+    }
+    const backup = changed ? writeJson(file, cfg) : null;
+    return { file, backup, changed, command };
+}
+function findCommand(cfg) {
+    const hooks = cfg.hooks;
+    if (!hooks || typeof hooks !== 'object')
+        return null;
+    for (const list of Object.values(hooks)) {
+        if (!Array.isArray(list))
+            continue;
+        for (const item of list) {
+            const entries = Array.isArray(item.hooks) ? item.hooks : [item];
+            for (const h of entries)
+                if (typeof h.command === 'string' && MARK.test(h.command))
+                    return h.command;
+        }
+    }
+    return null;
+}
+function health(host, home = (0, node_os_1.homedir)()) {
+    const file = configPath(host, home);
+    let command = null;
+    try {
+        command = findCommand(readJson(file));
+    }
+    catch {
+        command = null;
+    }
+    const script = command?.match(/^node (\S+)/)?.[1] ?? null;
+    const hostPresent = host === 'claude' ? (0, node_fs_1.existsSync)((0, node_path_1.join)(home, '.claude')) : host === 'cursor' ? (0, node_fs_1.existsSync)((0, node_path_1.join)(home, '.cursor')) : (0, node_fs_1.existsSync)((0, node_path_1.join)(home, '.codex'));
+    return { host, file, installed: command !== null, command, commandExists: script !== null && (0, node_fs_1.existsSync)(script), hostPresent };
+}

package/dist/src/override.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The audited override.
+ *
+ * The STOP box says "override once: agentguard-burn resume --once". That
+ * has to be real, and it has to be single-use across every host on the
+ * machine: two hooks that both see the file must not both let a spawn
+ * through. Consumption is a rename, which is atomic; the loser of the race
+ * finds nothing to rename and blocks.
+ *
+ * Without --once the override is a window, 15 minutes by default, for the
+ * case where the user has decided the session is fine and does not want to
+ * type the command forty times. Every overridden STOP is written to the
+ * decisions ledger with the reason, so "why did this get through" always
+ * has an answer.
+ */
+export interface Override {
+    at: number;
+    once: boolean;
+    reason: string;
+    /** Absent for --once. */
+    until?: number;
+}
+export declare const OVERRIDE_WINDOW_MS: number;
+export declare function writeOverride(home: string, o: Override): void;
+export declare function readOverride(home: string, now?: number): Override | null;
+/**
+ * Called only when a STOP is about to be enforced. Returns the override to
+ * apply, or null. A --once override is consumed here and cannot be used
+ * twice, however many processes ask at the same moment.
+ */
+export declare function consumeOverride(home: string, now?: number): Override | null;
+export declare function clearOverride(home: string): void;

package/dist/src/override.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * The audited override.
+ *
+ * The STOP box says "override once: agentguard-burn resume --once". That
+ * has to be real, and it has to be single-use across every host on the
+ * machine: two hooks that both see the file must not both let a spawn
+ * through. Consumption is a rename, which is atomic; the loser of the race
+ * finds nothing to rename and blocks.
+ *
+ * Without --once the override is a window, 15 minutes by default, for the
+ * case where the user has decided the session is fine and does not want to
+ * type the command forty times. Every overridden STOP is written to the
+ * decisions ledger with the reason, so "why did this get through" always
+ * has an answer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERRIDE_WINDOW_MS = void 0;
+exports.writeOverride = writeOverride;
+exports.readOverride = readOverride;
+exports.consumeOverride = consumeOverride;
+exports.clearOverride = clearOverride;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.OVERRIDE_WINDOW_MS = 15 * 60 * 1000;
+function file(home) {
+    return (0, node_path_1.join)(home, 'override.json');
+}
+function writeOverride(home, o) {
+    (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(file(home), JSON.stringify(o), { mode: 0o600 });
+}
+function readOverride(home, now = Date.now()) {
+    try {
+        const o = JSON.parse((0, node_fs_1.readFileSync)(file(home), 'utf8'));
+        if (typeof o.reason !== 'string' || typeof o.at !== 'number')
+            return null;
+        if (!o.once && (o.until === undefined || o.until < now))
+            return null;
+        return o;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Called only when a STOP is about to be enforced. Returns the override to
+ * apply, or null. A --once override is consumed here and cannot be used
+ * twice, however many processes ask at the same moment.
+ */
+function consumeOverride(home, now = Date.now()) {
+    const o = readOverride(home, now);
+    if (!o) {
+        if ((0, node_fs_1.existsSync)(file(home)))
+            (0, node_fs_1.rmSync)(file(home), { force: true }); // expired or malformed
+        return null;
+    }
+    if (!o.once)
+        return o;
+    const consumed = `${file(home)}.used.${process.pid}.${now.toString(36)}`;
+    try {
+        (0, node_fs_1.renameSync)(file(home), consumed);
+    }
+    catch {
+        return null; // a sibling consumed it first
+    }
+    (0, node_fs_1.rmSync)(consumed, { force: true });
+    return o;
+}
+function clearOverride(home) {
+    (0, node_fs_1.rmSync)(file(home), { force: true });
+}