@agentguard-run/burn 0.1.0

package/dist/src/detectors/evaluate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Detectors and the verdict.
+ *
+ * Two independent safety planes, because the data showed two independent
+ * failure modes:
+ *
+ *   structural  - fan-out. Many agents, each re-sending context. The 172-spawn
+ *                 session. Caught by an absolute spawn cap.
+ *   economic    - sustained burn. Few agents, long session, enormous total. The
+ *                 9.15B session with only 26 spawns, which a spawn cap cannot
+ *                 see. Caught by a cumulative token ceiling and burn debt.
+ *
+ * Verdict is the maximum severity across findings. Advisory detectors (spawn
+ * rate, duplicate work, cache ratio) can raise WARN but never STOP, because
+ * each has a plausible benign explanation and a false STOP is what gets a
+ * safety tool uninstalled.
+ */
+import type { BurnReport, SessionState, Thresholds } from '../types';
+/**
+ * Evaluate a session. `proposedSpawnDepth` is the depth the *candidate* child
+ * would have if the pending spawn were allowed; the decision must be about the
+ * proposal, not about a violation the transcript has already recorded.
+ */
+export declare function evaluate(state: SessionState, thresholds: Thresholds, proposedSpawnDepth?: number | null): BurnReport;
+export declare function fmt(n: number): string;

package/dist/src/detectors/evaluate.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Detectors and the verdict.
+ *
+ * Two independent safety planes, because the data showed two independent
+ * failure modes:
+ *
+ *   structural  - fan-out. Many agents, each re-sending context. The 172-spawn
+ *                 session. Caught by an absolute spawn cap.
+ *   economic    - sustained burn. Few agents, long session, enormous total. The
+ *                 9.15B session with only 26 spawns, which a spawn cap cannot
+ *                 see. Caught by a cumulative token ceiling and burn debt.
+ *
+ * Verdict is the maximum severity across findings. Advisory detectors (spawn
+ * rate, duplicate work, cache ratio) can raise WARN but never STOP, because
+ * each has a plausible benign explanation and a false STOP is what gets a
+ * safety tool uninstalled.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluate = evaluate;
+exports.fmt = fmt;
+const session_1 = require("../state/session");
+const RANK = { OK: 0, WARN: 1, STOP: 2 };
+function worst(a, b) {
+    return RANK[a] >= RANK[b] ? a : b;
+}
+/**
+ * Evaluate a session. `proposedSpawnDepth` is the depth the *candidate* child
+ * would have if the pending spawn were allowed; the decision must be about the
+ * proposal, not about a violation the transcript has already recorded.
+ */
+function evaluate(state, thresholds, proposedSpawnDepth = null) {
+    const findings = [];
+    let verdict = 'OK';
+    // ---- structural plane: fan-out --------------------------------------
+    // Count the proposal itself. "Allow through 40, deny candidate 41."
+    const effectiveSpawns = state.spawnCount + (proposedSpawnDepth !== null ? 1 : 0);
+    if (effectiveSpawns > thresholds.fanout.stop) {
+        findings.push({
+            detector: 'fanout',
+            verdict: 'STOP',
+            summary: `Spawn ${effectiveSpawns} would exceed the fan-out ceiling of ${thresholds.fanout.stop}.`,
+            observed: effectiveSpawns,
+            threshold: thresholds.fanout.stop,
+        });
+        verdict = worst(verdict, 'STOP');
+    }
+    else if (effectiveSpawns >= thresholds.fanout.warn) {
+        findings.push({
+            detector: 'fanout',
+            verdict: 'WARN',
+            summary: `${effectiveSpawns} agent spawns this session; ceiling is ${thresholds.fanout.stop}.`,
+            observed: effectiveSpawns,
+            threshold: thresholds.fanout.warn,
+        });
+        verdict = worst(verdict, 'WARN');
+    }
+    if (proposedSpawnDepth !== null && proposedSpawnDepth > thresholds.fanout.maxDepth) {
+        findings.push({
+            detector: 'fanout',
+            verdict: 'STOP',
+            summary: `Proposed agent would sit at depth ${proposedSpawnDepth}; agents spawning agents beyond depth ${thresholds.fanout.maxDepth} is the fan-out amplifier.`,
+            observed: proposedSpawnDepth,
+            threshold: thresholds.fanout.maxDepth,
+        });
+        verdict = worst(verdict, 'STOP');
+    }
+    // ---- economic plane: sustained burn --------------------------------
+    if (state.totalTokens >= thresholds.sustained.stopTokens) {
+        findings.push({
+            detector: 'sustained_burn',
+            verdict: 'STOP',
+            summary: `Session has consumed ${fmt(state.totalTokens)} tokens, above the ${fmt(thresholds.sustained.stopTokens)} ceiling.`,
+            observed: state.totalTokens,
+            threshold: thresholds.sustained.stopTokens,
+        });
+        verdict = worst(verdict, 'STOP');
+    }
+    else if (state.totalTokens >= thresholds.sustained.warnTokens) {
+        findings.push({
+            detector: 'sustained_burn',
+            verdict: 'WARN',
+            summary: `Session at ${fmt(state.totalTokens)} tokens; ceiling is ${fmt(thresholds.sustained.stopTokens)}.`,
+            observed: state.totalTokens,
+            threshold: thresholds.sustained.warnTokens,
+        });
+        verdict = worst(verdict, 'WARN');
+    }
+    // ---- economic plane: burn debt (only after calibration) ------------
+    if (thresholds.burnDebt.enabled) {
+        if (state.burnDebt >= thresholds.burnDebt.stopDebt) {
+            findings.push({
+                detector: 'burn_debt',
+                verdict: 'STOP',
+                summary: `Burn is ${fmt(state.burnDebt)} tokens above this user's expected rate, sustained.`,
+                observed: state.burnDebt,
+                threshold: thresholds.burnDebt.stopDebt,
+            });
+            verdict = worst(verdict, 'STOP');
+        }
+        else if (state.burnDebt >= thresholds.burnDebt.warnDebt) {
+            findings.push({
+                detector: 'burn_debt',
+                verdict: 'WARN',
+                summary: `Burn is running ${fmt(state.burnDebt)} tokens above the expected rate.`,
+                observed: state.burnDebt,
+                threshold: thresholds.burnDebt.warnDebt,
+            });
+            verdict = worst(verdict, 'WARN');
+        }
+    }
+    // ---- advisory: spawn rate over active time -------------------------
+    const recentSpawns = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, thresholds.spawnRate.windowActiveMinutes);
+    if (recentSpawns >= thresholds.spawnRate.stop) {
+        const severity = thresholds.spawnRate.enforce ? 'STOP' : 'WARN';
+        findings.push({
+            detector: 'spawn_rate',
+            verdict: severity,
+            summary: `${recentSpawns} spawns in the last ${thresholds.spawnRate.windowActiveMinutes} active minutes.`,
+            observed: recentSpawns,
+            threshold: thresholds.spawnRate.stop,
+        });
+        verdict = worst(verdict, severity);
+    }
+    else if (recentSpawns >= thresholds.spawnRate.warn) {
+        findings.push({
+            detector: 'spawn_rate',
+            verdict: 'WARN',
+            summary: `${recentSpawns} spawns in the last ${thresholds.spawnRate.windowActiveMinutes} active minutes.`,
+            observed: recentSpawns,
+            threshold: thresholds.spawnRate.warn,
+        });
+        verdict = worst(verdict, 'WARN');
+    }
+    // ---- advisory: duplicate work --------------------------------------
+    let duplicated = 0;
+    let worstSurfaceReaders = 0;
+    for (const readers of state.surfaceReaders.values()) {
+        if (readers.size >= thresholds.duplicate.warnReaders) {
+            duplicated += 1;
+            worstSurfaceReaders = Math.max(worstSurfaceReaders, readers.size);
+        }
+    }
+    if (duplicated > 0) {
+        findings.push({
+            detector: 'duplicate_work',
+            verdict: 'WARN',
+            summary: `${duplicated} file(s) re-read across ${worstSurfaceReaders}+ agent eras. Context is being re-sent instead of passed down.`,
+            observed: duplicated,
+            threshold: thresholds.duplicate.warnReaders,
+        });
+        verdict = worst(verdict, 'WARN');
+    }
+    return {
+        sessionId: state.sessionId,
+        verdict,
+        findings,
+        prescriptions: prescribe(state, findings, thresholds),
+        cacheReadRatio: (0, session_1.cacheReadRatio)(state),
+        totals: {
+            tokens: state.totalTokens,
+            spawns: state.spawnCount,
+            maxDepth: state.maxDepth,
+            activeMinutes: state.activeMinutes,
+        },
+    };
+}
+/**
+ * The layer that raw telemetry never ships: what to actually do, ranked.
+ * Every line is specific to this session's numbers.
+ */
+function prescribe(state, findings, t) {
+    const out = [];
+    const has = (d, v) => findings.some((f) => f.detector === d && (!v || f.verdict === v));
+    if (has('fanout', 'STOP')) {
+        out.push('Do not start another subagent. The fan-out ceiling is the validated stop.');
+        out.push(`Let the ${Math.min(state.spawnCount, 4)} most useful running agents finish; do not replace them.`);
+    }
+    else if (has('fanout')) {
+        out.push(`You are at ${state.spawnCount} spawns; ${t.fanout.stop - state.spawnCount} remain before the ceiling. Plan for it.`);
+    }
+    if (state.maxDepth >= 2) {
+        out.push('Agents are spawning agents. Make the root orchestrator the only process allowed to spawn.');
+    }
+    if (has('sustained_burn', 'STOP')) {
+        out.push(`This session is at ${fmt(state.totalTokens)} tokens. Start a fresh session for the next task; do not keep extending this one.`);
+        out.push('Compact before any further heavy work so the next call does not re-send the full history.');
+    }
+    else if (has('sustained_burn')) {
+        out.push('Compact now. Every call from here re-sends the accumulated context.');
+    }
+    if (has('burn_debt')) {
+        out.push('Burn is sustained above your own baseline. Narrow the task or split it into a new session.');
+    }
+    if (has('duplicate_work')) {
+        out.push('Assign one reader per file and pass a short digest down, instead of letting every agent re-read it.');
+    }
+    if (has('spawn_rate')) {
+        out.push('Queue agents instead of launching them in parallel; the limit is shared across all of them.');
+    }
+    const median = (0, session_1.medianCompletedMinute)(state);
+    if (median > 0 && (0, session_1.cacheReadRatio)(state) > 0.9) {
+        out.push('Most of this burn is cached context re-sent per agent. Fewer, longer-lived agents beat many short ones.');
+    }
+    if (out.length === 0)
+        out.push('Nothing pathological. Carry on.');
+    return out;
+}
+function fmt(n) {
+    if (n >= 1e9)
+        return `${(n / 1e9).toFixed(2)}B`;
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(1)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(0)}K`;
+    return String(Math.round(n));
+}

package/dist/src/history/claude-transcript.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Claude Code transcript reader.
+ *
+ * Reads ~/.claude/projects/<slug>/<session>.jsonl incrementally. The hot path
+ * (the PreToolUse hook) must never re-read a 25,000-line file, so the reader
+ * remembers the byte offset after the last complete newline and only parses
+ * what has been appended since.
+ *
+ * Transcript lines are not a stable contract. Every line is parsed defensively:
+ * a malformed line is counted and skipped, a partial trailing line is left
+ * uncommitted so it can be re-read once the host finishes writing it, and a
+ * truncated or replaced file resets the cursor rather than reading garbage.
+ */
+import type { BurnEvent } from '../types';
+export interface ReaderCursor {
+    /** Byte just after the last complete newline we processed. */
+    offset: number;
+    /** Size at last read, to detect truncation or replacement. */
+    size: number;
+    malformedLines: number;
+    /** Resolved depth per line uuid, for spawn-depth attribution. */
+    depthByUuid: Map<string, number>;
+}
+export declare function newCursor(): ReaderCursor;
+interface RawLine {
+    timestamp?: string;
+    uuid?: string;
+    parentUuid?: string;
+    isSidechain?: boolean;
+    message?: {
+        usage?: Record<string, number | undefined>;
+        content?: unknown;
+    };
+}
+/** Turn one parsed line into an event, or null if it carries nothing we track. */
+export declare function normaliseLine(raw: RawLine, cursor: ReaderCursor): BurnEvent | null;
+/**
+ * Read every complete line appended since the cursor. Returns the new events
+ * and advances the cursor. O(new bytes), never O(file size) after the first
+ * read.
+ */
+export declare function readIncremental(path: string, cursor: ReaderCursor): BurnEvent[];
+/** Convenience for replay and tests: read a whole transcript from the start. */
+export declare function readAll(path: string): {
+    events: BurnEvent[];
+    cursor: ReaderCursor;
+};
+export {};

package/dist/src/history/claude-transcript.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * Claude Code transcript reader.
+ *
+ * Reads ~/.claude/projects/<slug>/<session>.jsonl incrementally. The hot path
+ * (the PreToolUse hook) must never re-read a 25,000-line file, so the reader
+ * remembers the byte offset after the last complete newline and only parses
+ * what has been appended since.
+ *
+ * Transcript lines are not a stable contract. Every line is parsed defensively:
+ * a malformed line is counted and skipped, a partial trailing line is left
+ * uncommitted so it can be re-read once the host finishes writing it, and a
+ * truncated or replaced file resets the cursor rather than reading garbage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newCursor = newCursor;
+exports.normaliseLine = normaliseLine;
+exports.readIncremental = readIncremental;
+exports.readAll = readAll;
+const node_fs_1 = require("node:fs");
+const CHUNK = 64 * 1024;
+const MAX_LINE = 4 * 1024 * 1024;
+const SPAWN_TOOLS = new Set(['Agent', 'Task']);
+const SURFACE_TOOLS = new Set(['Read', 'Grep', 'Glob']);
+function newCursor() {
+    return { offset: 0, size: 0, malformedLines: 0, depthByUuid: new Map() };
+}
+function toMillis(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+function nonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/** Turn one parsed line into an event, or null if it carries nothing we track. */
+function normaliseLine(raw, cursor) {
+    const at = toMillis(raw.timestamp);
+    if (at === null)
+        return null;
+    const usage = raw.message?.usage ?? {};
+    const cacheRead = nonNegative(usage.cache_read_input_tokens);
+    const tokens = nonNegative(usage.input_tokens) +
+        nonNegative(usage.output_tokens) +
+        nonNegative(usage.cache_creation_input_tokens) +
+        cacheRead;
+    // Depth attribution: a line's depth is its parent's depth, plus one if the
+    // host flagged it as a sidechain (subagent) line. Unknown parents are root.
+    const parentDepth = raw.parentUuid ? cursor.depthByUuid.get(raw.parentUuid) ?? 0 : 0;
+    const depth = raw.isSidechain ? parentDepth + 1 : parentDepth;
+    if (raw.uuid)
+        cursor.depthByUuid.set(raw.uuid, depth);
+    const spawns = [];
+    const surfaces = [];
+    const content = raw.message?.content;
+    if (Array.isArray(content)) {
+        for (const item of content) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const block = item;
+            if (block.type !== 'tool_use' || typeof block.name !== 'string')
+                continue;
+            const input = (block.input && typeof block.input === 'object' ? block.input : {});
+            if (SPAWN_TOOLS.has(block.name)) {
+                spawns.push({
+                    // Bounded and never persisted beyond process memory: this is a label
+                    // for the operator, not a record of the prompt.
+                    description: String(input.description ?? '').slice(0, 80),
+                    model: typeof input.model === 'string' ? input.model : undefined,
+                    issuerDepth: depth,
+                });
+            }
+            else if (SURFACE_TOOLS.has(block.name)) {
+                const target = input.file_path ?? input.path ?? input.pattern;
+                if (typeof target === 'string' && target.length > 0)
+                    surfaces.push(target);
+            }
+        }
+    }
+    if (tokens === 0 && spawns.length === 0 && surfaces.length === 0)
+        return null;
+    return {
+        at,
+        tokens,
+        cacheRead,
+        spawns,
+        surfaces,
+        sidechain: Boolean(raw.isSidechain),
+        uuid: raw.uuid,
+        parentUuid: raw.parentUuid,
+    };
+}
+/**
+ * Read every complete line appended since the cursor. Returns the new events
+ * and advances the cursor. O(new bytes), never O(file size) after the first
+ * read.
+ */
+function readIncremental(path, cursor) {
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(path, 'r');
+    }
+    catch {
+        return [];
+    }
+    try {
+        const size = (0, node_fs_1.fstatSync)(fd).size;
+        // Truncated or replaced: the bytes we remember no longer exist. Restart.
+        if (size < cursor.offset) {
+            cursor.offset = 0;
+            cursor.depthByUuid.clear();
+        }
+        cursor.size = size;
+        if (size === cursor.offset)
+            return [];
+        const events = [];
+        let carry = Buffer.alloc(0);
+        let position = cursor.offset;
+        const buffer = Buffer.allocUnsafe(CHUNK);
+        while (position < size) {
+            const read = (0, node_fs_1.readSync)(fd, buffer, 0, CHUNK, position);
+            if (read <= 0)
+                break;
+            position += read;
+            let chunk = carry.length ? Buffer.concat([carry, buffer.subarray(0, read)]) : buffer.subarray(0, read);
+            let lineStart = 0;
+            for (;;) {
+                const newline = chunk.indexOf(0x0a, lineStart);
+                if (newline === -1)
+                    break;
+                const lineBytes = chunk.subarray(lineStart, newline);
+                lineStart = newline + 1;
+                if (lineBytes.length > 0 && lineBytes.length <= MAX_LINE) {
+                    try {
+                        const parsed = JSON.parse(lineBytes.toString('utf8'));
+                        const event = normaliseLine(parsed, cursor);
+                        if (event)
+                            events.push(event);
+                    }
+                    catch {
+                        cursor.malformedLines += 1;
+                    }
+                }
+                else if (lineBytes.length > MAX_LINE) {
+                    cursor.malformedLines += 1;
+                }
+            }
+            // Everything before lineStart is committed. The remainder is a partial
+            // line the host may still be writing; keep it for the next chunk, and
+            // if the file ends mid-line, do not advance past it.
+            const consumed = position - read + lineStart;
+            cursor.offset = consumed - (carry.length ? carry.length : 0) + (carry.length ? carry.length : 0);
+            carry = Buffer.from(chunk.subarray(lineStart));
+            // Guard against a runaway partial line that never terminates.
+            if (carry.length > MAX_LINE) {
+                cursor.malformedLines += 1;
+                carry = Buffer.alloc(0);
+                cursor.offset = position;
+            }
+        }
+        // Recompute offset precisely: bytes read minus the uncommitted carry.
+        cursor.offset = position - carry.length;
+        return events;
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+/** Convenience for replay and tests: read a whole transcript from the start. */
+function readAll(path) {
+    const cursor = newCursor();
+    const events = readIncremental(path, cursor);
+    return { events, cursor };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Claude Code PreToolUse hook.
+ *
+ * Reads the hook payload from stdin, evaluates the proposed spawn under the
+ * reservation lock, and emits the nested permissionDecision Claude Code
+ * expects. Only Agent/Task spawns are ever denied; ordinary tools pass.
+ *
+ * Shadow mode evaluates and records the decision but always allows. That is
+ * the first-run default, because a blocker with untuned thresholds that fires
+ * on day one gets uninstalled on day one.
+ *
+ * Fail-closed on the reservation lock: if we cannot coordinate with sibling
+ * hook processes, we deny the spawn rather than let a burst through. We
+ * cannot fail closed if Claude Code times the hook out, so the hot path does
+ * as little as possible.
+ */
+import { type ReaderCursor } from '../history/claude-transcript';
+import type { Policy, SessionState } from '../types';
+export interface HookInput {
+    session_id?: string;
+    transcript_path?: string;
+    tool_name?: string;
+    tool_use_id?: string;
+    tool_input?: Record<string, unknown>;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface HookOutput {
+    continue: true;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    hookSpecificOutput?: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow' | 'deny';
+        permissionDecisionReason: 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;
+};
+export declare function handlePreToolUse(input: HookInput, home: string, now?: number): HookOutput;
+/** The settings.json fragment users paste in. Only PreToolUse can block. */
+export declare function settingsSnippet(command: string): Record<string, unknown>;

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

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Claude Code PreToolUse hook.
+ *
+ * Reads the hook payload from stdin, evaluates the proposed spawn under the
+ * reservation lock, and emits the nested permissionDecision Claude Code
+ * expects. Only Agent/Task spawns are ever denied; ordinary tools pass.
+ *
+ * Shadow mode evaluates and records the decision but always allows. That is
+ * the first-run default, because a blocker with untuned thresholds that fires
+ * on day one gets uninstalled on day one.
+ *
+ * Fail-closed on the reservation lock: if we cannot coordinate with sibling
+ * hook processes, we deny the spawn rather than let a burst through. We
+ * cannot fail closed if Claude Code times the hook out, so the hot path does
+ * as little as possible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPolicy = loadPolicy;
+exports.refreshSession = refreshSession;
+exports.handlePreToolUse = handlePreToolUse;
+exports.settingsSnippet = settingsSnippet;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const evaluate_1 = require("../detectors/evaluate");
+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 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`);
+}
+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 };
+    }
+    catch {
+        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt) };
+    }
+}
+function saveSession(home, cursor, state) {
+    (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] },
+        state: {
+            ...state,
+            tokensByActiveMinute: [...state.tokensByActiveMinute],
+            spawnsByActiveMinute: [...state.spawnsByActiveMinute],
+            surfaceReaders: [...state.surfaceReaders].map(([k, v]) => [k, [...v]]),
+        },
+    };
+    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);
+}
+function loadPolicy(home) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, 'burn-policy.json'), 'utf8'));
+        if (parsed && (parsed.mode === 'shadow' || parsed.mode === 'enforce') && parsed.thresholds)
+            return parsed;
+    }
+    catch {
+        /* no policy yet: shadow defaults */
+    }
+    return defaults_1.DEFAULT_POLICY;
+}
+function recordDecision(home, entry) {
+    (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.appendFileSync)((0, node_path_1.join)(home, 'decisions.ndjson'), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+}
+/** 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 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 };
+}
+function handlePreToolUse(input, home, now = Date.now()) {
+    const toolName = input.tool_name ?? '';
+    if (!SPAWN_TOOLS.has(toolName) || !input.session_id || !input.transcript_path) {
+        return { continue: true, suppressOutput: true };
+    }
+    const policy = loadPolicy(home);
+    const store = new reservations_1.ReservationStore(home);
+    let report;
+    let reservation;
+    try {
+        const { state, newSpawns } = refreshSession(home, input.session_id, input.transcript_path);
+        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
+        // fired inside a subagent carries agent_id; treat that as depth 1 issuer.
+        const proposedDepth = input.agent_id ? 2 : 1;
+        report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth);
+        reservation = store.reserve({
+            sessionId: input.session_id,
+            toolUseId: input.tool_use_id ?? `${input.session_id}:${now}`,
+            observedSpawns: state.spawnCount,
+            ceiling: policy.thresholds.fanout.stop,
+            now,
+        });
+    }
+    catch (error) {
+        // Could not coordinate. Deny the spawn; never let a burst through blind.
+        const reason = `AgentGuard failed closed: ${error instanceof Error ? error.message : 'unknown error'}`;
+        recordDecision(home, { at: now, sessionId: input.session_id, verdict: 'STOP', enforced: policy.mode === 'enforce', reason, failClosed: true });
+        return policy.mode === 'enforce' ? deny(reason) : { continue: true, suppressOutput: true };
+    }
+    const shouldDeny = report.verdict === 'STOP' || !reservation.allowed;
+    const reason = shouldDeny ? buildDenyReason(report, reservation) : '';
+    recordDecision(home, {
+        at: now,
+        sessionId: input.session_id,
+        toolUseId: input.tool_use_id ?? null,
+        verdict: report.verdict,
+        wouldDeny: shouldDeny,
+        enforced: policy.mode === 'enforce' && shouldDeny,
+        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 (report.verdict !== 'OK') {
+        return {
+            continue: true,
+            systemMessage: `AgentGuard ${report.verdict}${policy.mode === 'shadow' && shouldDeny ? ' (shadow: would have blocked)' : ''}: ${report.findings[0]?.summary ?? ''}`,
+        };
+    }
+    return { continue: true, suppressOutput: true };
+}
+function buildDenyReason(report, reservation) {
+    const lead = report.findings.find((f) => f.verdict === 'STOP')?.summary ?? `Fan-out ceiling reached (${reservation.effectiveSpawns} effective spawns).`;
+    const rx = report.prescriptions.slice(0, 3).map((p, i) => `${i + 1}. ${p}`).join(' ');
+    return `AgentGuard STOP: blocked this agent spawn. ${lead} ${rx} Override once with: agentguard-burn resume --once --reason "..."`;
+}
+function deny(reason) {
+    return {
+        continue: true,
+        hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason },
+    };
+}
+/** The settings.json fragment users paste in. Only PreToolUse can block. */
+function settingsSnippet(command) {
+    return {
+        hooks: {
+            PreToolUse: [{ matcher: '^(Agent|Task)$', hooks: [{ type: 'command', command, timeout: 5 }] }],
+        },
+    };
+}