@agentguard-run/burn 0.2.3 → 0.2.6

package/dist/src/detectors/evaluate.js

@@ -6,20 +6,20 @@
  * failure modes:
  *
  *   structural  - fan-out. Many agents, each re-sending context. The 190-spawn
- *                 session. Caught by an absolute spawn cap.
+ *                 session. Caught by spawn windows over active time.
  *   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.
+ * Verdict is the maximum severity across findings. Lifetime fan-out and
+ * duplicate work are advisory; only a recent burst, depth or economic
+ * threshold can stop new work. Spawn rate can be made advisory by policy.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluate = evaluate;
 exports.fmt = fmt;
 const account_1 = require("../state/account");
+const defaults_1 = require("../defaults");
 const session_1 = require("../state/session");
 const RANK = { OK: 0, WARN: 1, STOP: 2 };
 function worst(a, b) {
@@ -36,12 +36,14 @@ function evaluate(state, thresholds, proposedSpawnDepth = null, account) {
     // ---- 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) {
+    const fanoutWindow = thresholds.fanout.windowActiveMinutes ?? defaults_1.DEFAULT_THRESHOLDS.fanout.windowActiveMinutes;
+    const recentFanout = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, fanoutWindow) + (proposedSpawnDepth !== null ? 1 : 0);
+    if (recentFanout > thresholds.fanout.stop) {
         findings.push({
             detector: 'fanout',
             verdict: 'STOP',
-            summary: `Spawn ${effectiveSpawns} would exceed the fan-out ceiling of ${thresholds.fanout.stop}.`,
-            observed: effectiveSpawns,
+            summary: `Spawn ${recentFanout} would exceed the fan-out ceiling of ${thresholds.fanout.stop}.`,
+            observed: recentFanout,
             threshold: thresholds.fanout.stop,
         });
         verdict = worst(verdict, 'STOP');
@@ -110,8 +112,8 @@ function evaluate(state, thresholds, proposedSpawnDepth = null, account) {
             verdict = worst(verdict, 'WARN');
         }
     }
-    // ---- advisory: spawn rate over active time -------------------------
-    const recentSpawns = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, thresholds.spawnRate.windowActiveMinutes);
+    // ---- structural plane: spawn rate over active time -----------------
+    const recentSpawns = (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, thresholds.spawnRate.windowActiveMinutes) + (proposedSpawnDepth !== null ? 1 : 0);
     if (recentSpawns >= thresholds.spawnRate.stop) {
         const severity = thresholds.spawnRate.enforce ? 'STOP' : 'WARN';
         findings.push({
@@ -199,7 +201,7 @@ function prescribe(state, findings, t) {
         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.`);
+        out.push(`You are at ${state.spawnCount} spawns; ${Math.max(0, t.fanout.stop - (0, session_1.windowSum)(state.spawnsByActiveMinute, state.activeMinutes, t.fanout.windowActiveMinutes ?? defaults_1.DEFAULT_THRESHOLDS.fanout.windowActiveMinutes))} 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.');

package/dist/src/eligibility.d.ts

@@ -0,0 +1,17 @@
+export interface ShadowEligibility {
+    eligible: boolean;
+    decisions: number;
+    days: number;
+    wouldBlock: number;
+    warns: number;
+    excludedLockWaitFailures: number;
+}
+/** Existing lock-failure ledger rows remain readable without a schema change. */
+export declare function isLockWaitFailure(row: Readonly<Record<string, unknown>>): boolean;
+/**
+ * A reservation-lock timeout is an operational failure, not an observation of
+ * a threshold. Keep it in the audit ledger but do not let a burst of timeouts
+ * satisfy the observation count or start the enforcement waiting period.
+ * Older decision rows need no new fields and retain their existing behavior.
+ */
+export declare function computeShadowEligibility(rows: ReadonlyArray<Readonly<Record<string, unknown>>>, now?: number): ShadowEligibility;

package/dist/src/eligibility.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLockWaitFailure = isLockWaitFailure;
+exports.computeShadowEligibility = computeShadowEligibility;
+const defaults_1 = require("./defaults");
+/** Existing lock-failure ledger rows remain readable without a schema change. */
+function isLockWaitFailure(row) {
+    return row.failClosed === true && typeof row.reason === 'string'
+        && /\bcould not acquire (?:the )?reservation lock\b/i.test(row.reason);
+}
+/**
+ * A reservation-lock timeout is an operational failure, not an observation of
+ * a threshold. Keep it in the audit ledger but do not let a burst of timeouts
+ * satisfy the observation count or start the enforcement waiting period.
+ * Older decision rows need no new fields and retain their existing behavior.
+ */
+function computeShadowEligibility(rows, now = Date.now()) {
+    const decisions = rows.filter(row => !isLockWaitFailure(row));
+    const first = decisions.length ? Number(decisions[0].at) : now;
+    const days = (now - first) / 86_400_000;
+    return {
+        eligible: decisions.length >= defaults_1.SHADOW_MIN_DECISIONS && days >= defaults_1.SHADOW_MIN_DAYS,
+        decisions: decisions.length,
+        days,
+        wouldBlock: decisions.filter(row => row.wouldDeny === true).length,
+        warns: decisions.filter(row => row.verdict === 'WARN').length,
+        excludedLockWaitFailures: rows.length - decisions.length,
+    };
+}

package/dist/src/gateway.d.ts

@@ -80,6 +80,8 @@ export interface GatewayOptions {
 }
 export declare class Gateway {
     private readonly home;
+    /** Shared local storage for optional content-free usage observations. */
+    get dataDirectory(): string;
     private readonly store;
     private readonly signer;
     private readonly now;

package/dist/src/gateway.js

@@ -41,6 +41,7 @@ const pre_tool_use_1 = require("./hook/pre-tool-use");
 const override_1 = require("./override");
 const receipt_1 = require("./receipt");
 const reservations_1 = require("./state/reservations");
+const spawn_window_1 = require("./state/spawn-window");
 const account_1 = require("./state/account");
 const session_1 = require("./state/session");
 const MAX_SEEN_EVENTS = 4000;
@@ -50,6 +51,8 @@ function safeName(sessionId) {
 }
 class Gateway {
     home;
+    /** Shared local storage for optional content-free usage observations. */
+    get dataDirectory() { return this.home; }
     store;
     signer;
     now;
@@ -215,14 +218,7 @@ class Gateway {
                 }
                 const live = new Map(meta.liveSpawns);
                 const proposedDepth = event.proposedDepth ?? (event.issuerId !== undefined && live.has(event.issuerId) ? live.get(event.issuerId) + 1 : 1);
-                const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
-                const reservation = tx.reserve({
-                    sessionId: event.sessionId,
-                    toolUseId: event.spawnId,
-                    observedSpawns: state.spawnCount,
-                    ceiling: policy.thresholds.fanout.stop,
-                    now: event.at,
-                });
+                const { report, reservation } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, event.spawnId, event.at, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
                 const wouldBlock = report.verdict === 'STOP' || !reservation.allowed;
                 const verdict = wouldBlock ? 'STOP' : report.verdict;
                 // Session-scope STOPs need a session we trust. Fan-out is session scope.

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

@@ -12,6 +12,8 @@
  * truncated or replaced file resets the cursor rather than reading garbage.
  */
 import type { BurnEvent } from '../types';
+/** Component maxima for one provider response, never transcript contents. */
+export type UsageSnapshot = [input: number, output: number, cacheCreation: number, cacheRead: number];
 export interface ReaderCursor {
     /** Byte just after the last complete newline we processed. */
     offset: number;
@@ -20,6 +22,11 @@ export interface ReaderCursor {
     malformedLines: number;
     /** Resolved depth per line uuid, for spawn-depth attribution. */
     depthByUuid: Map<string, number>;
+    /** Optional and additive so callers with pre-0.2.6 cursors still load. */
+    usageVersion?: 1;
+    usageByMessage?: Map<string, UsageSnapshot>;
+    /** Child file cursors share usageByMessage with their parent. */
+    children?: Map<string, ReaderCursor>;
 }
 export declare function newCursor(): ReaderCursor;
 interface RawLine {
@@ -28,6 +35,7 @@ interface RawLine {
     parentUuid?: string;
     isSidechain?: boolean;
     message?: {
+        id?: unknown;
         usage?: Record<string, number | undefined>;
         content?: unknown;
     };
@@ -39,8 +47,18 @@ export declare function normaliseLine(raw: RawLine, cursor: ReaderCursor): BurnE
  * 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 interface ReadOptions {
+    /** Legacy-state rebuilds must not replace totals after an unreadable file. */
+    throwOnOpenError?: boolean;
+}
+export declare function readIncremental(path: string, cursor: ReaderCursor, options?: ReadOptions): BurnEvent[];
+/**
+ * Fold the parent's tool events and its stored children's usage into one
+ * session. Child histories can contain copied parent tool calls, so only their
+ * usage deltas contribute here. The parent's observed spawn count stays intact.
+ */
+export declare function readSessionIncremental(path: string, cursor: ReaderCursor, options?: ReadOptions): BurnEvent[];
+/** Convenience for replay and tests: read a session and its own stored children. */
 export declare function readAll(path: string): {
     events: BurnEvent[];
     cursor: ReaderCursor;

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

@@ -16,14 +16,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.newCursor = newCursor;
 exports.normaliseLine = normaliseLine;
 exports.readIncremental = readIncremental;
+exports.readSessionIncremental = readSessionIncremental;
 exports.readAll = readAll;
 const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const transcript_1 = require("../insights/transcript");
 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() };
+    return { offset: 0, size: 0, malformedLines: 0, depthByUuid: new Map(), usageVersion: 1, usageByMessage: new Map() };
 }
 function toMillis(value) {
     if (typeof value !== 'string' || value.length === 0)
@@ -40,11 +43,22 @@ function normaliseLine(raw, cursor) {
     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;
+    const snapshot = [nonNegative(usage.input_tokens), nonNegative(usage.output_tokens),
+        nonNegative(usage.cache_creation_input_tokens), nonNegative(usage.cache_read_input_tokens)];
+    let tokens = snapshot.reduce((sum, value) => sum + value, 0);
+    let cacheRead = snapshot[3];
+    // Claude writes one row per content block, all carrying the same message.id.
+    // Fork copies preserve that id too. Match the attribution parser's global
+    // identity and per-category maxima, emitting only newly observed usage.
+    if (raw.message?.id !== undefined && tokens > 0) {
+        const id = (0, transcript_1.providerResponseIdentity)('claude', raw.message.id);
+        cursor.usageByMessage ??= new Map();
+        const previous = cursor.usageByMessage.get(id) ?? [0, 0, 0, 0];
+        const merged = snapshot.map((value, index) => Math.max(value, previous[index]));
+        tokens = merged.reduce((sum, value, index) => sum + value - previous[index], 0);
+        cacheRead = merged[3] - previous[3];
+        cursor.usageByMessage.set(id, merged);
+    }
     // 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;
@@ -91,17 +105,14 @@ function normaliseLine(raw, cursor) {
         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) {
+function readIncremental(path, cursor, options = {}) {
     let fd;
     try {
         fd = (0, node_fs_1.openSync)(path, 'r');
     }
-    catch {
+    catch (error) {
+        if (options.throwOnOpenError)
+            throw error;
         return [];
     }
     try {
@@ -167,9 +178,39 @@ function readIncremental(path, cursor) {
         (0, node_fs_1.closeSync)(fd);
     }
 }
-/** Convenience for replay and tests: read a whole transcript from the start. */
+/**
+ * Fold the parent's tool events and its stored children's usage into one
+ * session. Child histories can contain copied parent tool calls, so only their
+ * usage deltas contribute here. The parent's observed spawn count stays intact.
+ */
+function readSessionIncremental(path, cursor, options = {}) {
+    cursor.usageByMessage ??= new Map();
+    cursor.children ??= new Map();
+    const events = readIncremental(path, cursor, options);
+    const directory = (0, node_path_1.join)(path.replace(/\.jsonl$/, ''), 'subagents');
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(directory).filter(name => name.endsWith('.jsonl')).sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return events;
+        throw error;
+    }
+    for (const name of names) {
+        const child = cursor.children.get(name) ?? newCursor();
+        child.usageByMessage = cursor.usageByMessage;
+        cursor.children.set(name, child);
+        for (const event of readIncremental((0, node_path_1.join)(directory, name), child, options)) {
+            if (event.tokens > 0 || event.cacheRead > 0)
+                events.push({ ...event, spawns: [], surfaces: [], sidechain: true });
+        }
+    }
+    return events.sort((a, b) => a.at - b.at);
+}
+/** Convenience for replay and tests: read a session and its own stored children. */
 function readAll(path) {
     const cursor = newCursor();
-    const events = readIncremental(path, cursor);
+    const events = readSessionIncremental(path, cursor);
     return { events, cursor };
 }

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

@@ -14,8 +14,8 @@
  * 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 { BurnReport, Policy, SessionState } from '../types';
+import { type ReaderCursor, type UsageSnapshot } from '../history/claude-transcript';
+import type { BurnReport, SessionState } from '../types';
 export interface HookInput {
     session_id?: string;
     transcript_path?: string;
@@ -35,13 +35,17 @@ export interface HookOutput {
         permissionDecisionReason: string;
     };
 }
+export interface PersistedReaderCursor {
+    offset: number;
+    size: number;
+    malformedLines: number;
+    depthByUuid: [string, number][];
+    usageVersion?: 1;
+    usageByMessage?: [string, UsageSnapshot][];
+    children?: [string, PersistedReaderCursor][];
+}
 export interface PersistedSession {
-    cursor: {
-        offset: number;
-        size: number;
-        malformedLines: number;
-        depthByUuid: [string, number][];
-    };
+    cursor: PersistedReaderCursor;
     state: Omit<SessionState, 'tokensByActiveMinute' | 'spawnsByActiveMinute' | 'surfaceReaders'> & {
         tokensByActiveMinute: [number, number][];
         spawnsByActiveMinute: [number, number][];
@@ -60,7 +64,7 @@ export declare function inflateHookSession(raw: PersistedSession): SessionState;
  * and the one that matters is the nineteenth.
  */
 export declare function findingSignature(report: BurnReport): string;
-export declare function loadPolicy(home: string): Policy;
+export { loadPolicy } from '../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;

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

@@ -16,9 +16,9 @@
  * as little as possible.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPolicy = void 0;
 exports.inflateHookSession = inflateHookSession;
 exports.findingSignature = findingSignature;
-exports.loadPolicy = loadPolicy;
 exports.refreshSession = refreshSession;
 exports.handlePreToolUse = handlePreToolUse;
 exports.settingsSnippet = settingsSnippet;
@@ -28,13 +28,14 @@ const receipt_1 = require("../receipt");
 const account_1 = require("../state/account");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const evaluate_1 = require("../detectors/evaluate");
+const spawn_window_1 = require("../state/spawn-window");
 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 policy_1 = require("../policy");
 const override_1 = require("../override");
 const render_1 = require("../replay/render");
+const live_1 = require("../insights/live");
 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`);
@@ -48,20 +49,31 @@ function inflateHookSession(raw) {
         surfaceReaders: new Map(raw.state.surfaceReaders.map(([k, v]) => [k, new Set(v)])),
     };
 }
+function inflateCursor(raw, shared) {
+    const usageByMessage = shared ?? new Map(raw.usageByMessage ?? []);
+    return { ...raw, depthByUuid: new Map(raw.depthByUuid), usageByMessage,
+        children: new Map((raw.children ?? []).map(([name, child]) => [name, inflateCursor(child, usageByMessage)])) };
+}
+function persistCursor(cursor, child = false) {
+    return { offset: cursor.offset, size: cursor.size, malformedLines: cursor.malformedLines, depthByUuid: [...cursor.depthByUuid],
+        usageVersion: cursor.usageVersion,
+        ...(!child ? { usageByMessage: [...(cursor.usageByMessage ?? [])] } : {}),
+        ...(cursor.children?.size ? { children: [...cursor.children].map(([name, value]) => [name, persistCursor(value, true)]) } : {}) };
+}
 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) };
-        return { cursor, state: inflateHookSession(raw), notified: raw.notified ?? '', lastReceipt: raw.lastReceipt ?? null };
+        return { cursor: inflateCursor(raw.cursor), state: inflateHookSession(raw), notified: raw.notified ?? '', lastReceipt: raw.lastReceipt ?? null,
+            fresh: false, needsRebuild: raw.cursor.usageVersion !== 1 || !Array.isArray(raw.cursor.usageByMessage) };
     }
     catch {
-        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '', lastReceipt: null };
+        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '', lastReceipt: null, fresh: true, needsRebuild: false };
     }
 }
 function saveSession(home, cursor, state, notified, lastReceipt) {
     (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] },
+        cursor: persistCursor(cursor),
         state: {
             ...state,
             tokensByActiveMinute: [...state.tokensByActiveMinute],
@@ -87,32 +99,52 @@ function findingSignature(report) {
         .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'));
-        if (parsed && (parsed.mode === 'shadow' || parsed.mode === 'enforce') && parsed.thresholds)
-            return parsed;
-    }
-    catch {
-        /* no policy yet: shadow defaults */
-    }
-    return defaults_1.DEFAULT_POLICY;
-}
+var policy_2 = require("../policy");
+Object.defineProperty(exports, "loadPolicy", { enumerable: true, get: function () { return policy_2.loadPolicy; } });
 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, notified, lastReceipt } = loadSession(home, sessionId, Date.now());
+    const loaded = loadSession(home, sessionId, Date.now());
+    let { cursor, state, fresh } = loaded;
+    const { notified, lastReceipt } = loaded;
     const before = state.spawnCount;
-    const events = (0, claude_transcript_1.readIncremental)(transcriptPath, cursor);
+    // Old offsets cannot tell us which repeated rows inflated their totals.
+    // Rebuild once from locally recorded evidence, retaining the signed chain
+    // head and notification state. Never replace old counts with an empty read
+    // when the transcript has disappeared or cannot be opened.
+    if (loaded.needsRebuild) {
+        try {
+            (0, node_fs_1.accessSync)(transcriptPath, node_fs_1.constants.R_OK);
+        }
+        catch {
+            return { cursor, state, newSpawns: 0, notified };
+        }
+        cursor = (0, claude_transcript_1.newCursor)();
+        state = (0, session_1.newSessionState)(sessionId, Date.now());
+        fresh = true;
+    }
+    let events;
+    try {
+        events = (0, claude_transcript_1.readSessionIncremental)(transcriptPath, cursor, { throwOnOpenError: loaded.needsRebuild });
+    }
+    catch (error) {
+        if (!loaded.needsRebuild)
+            throw error;
+        // Opening can fail after the access check, including on a stored child.
+        // Retain the old cursor so the next refresh retries the complete rebuild.
+        return { cursor: loaded.cursor, state: loaded.state, newSpawns: 0, notified };
+    }
+    if (fresh && events.length > 0)
+        state = (0, session_1.newSessionState)(sessionId, events[0].at);
     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, notified, lastReceipt);
-    return { cursor, state, newSpawns: state.spawnCount - before, notified };
+    return { cursor, state, newSpawns: Math.max(0, state.spawnCount - before), notified };
 }
 function rememberNotified(home, sessionId, signature) {
     try {
@@ -127,11 +159,18 @@ function rememberNotified(home, sessionId, signature) {
     }
 }
 function handlePreToolUse(input, home, now = Date.now()) {
+    const observation = (0, live_1.observeTool)(home, input, 'claude', (0, policy_1.loadPolicy)(home), now);
+    const output = handleSpawnPreToolUse(input, home, now);
+    if (!observation.messages.length)
+        return output;
+    return { ...output, suppressOutput: false, systemMessage: [output.systemMessage, ...observation.messages].filter(Boolean).join('\n') };
+}
+function handleSpawnPreToolUse(input, home, 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 policy = (0, policy_1.loadPolicy)(home);
     const store = new reservations_1.ReservationStore(home);
     try {
         const signer = receipt_1.ReceiptSigner.loadOrCreate(home);
@@ -144,14 +183,7 @@ function handlePreToolUse(input, home, now = Date.now()) {
             // 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;
-            const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth, { sessions: (0, account_1.readAccountSessions)(home, state, now), now });
-            const reservation = tx.reserve({
-                sessionId: input.session_id,
-                toolUseId: input.tool_use_id ?? `${input.session_id}:${now}`,
-                observedSpawns: state.spawnCount,
-                ceiling: policy.thresholds.fanout.stop,
-                now,
-            });
+            const { report, reservation } = (0, spawn_window_1.evaluateSpawnReservation)(tx, state, policy.thresholds, proposedDepth, input.tool_use_id ?? `${input.session_id}:${now}`, now, { sessions: (0, account_1.readAccountSessions)(home, state, now), 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.
@@ -231,7 +263,7 @@ function deny(reason) {
 function settingsSnippet(command) {
     return {
         hooks: {
-            PreToolUse: [{ matcher: '^(Agent|Task)$', hooks: [{ type: 'command', command, timeout: 5 }] }],
+            PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 15 }] }],
         },
     };
 }

package/dist/src/insights/attribution.d.ts

@@ -0,0 +1,4 @@
+import { type AttributionSummary, type InsightTurn, type RewriteEvidence } from './types';
+export declare function classifyRewrite(turn: InsightTurn): RewriteEvidence | null;
+/** Partition measured usage; byte lengths only divide a measured increment among its recorded events. */
+export declare function attributeTurns(turns: InsightTurn[]): AttributionSummary;