@agentguard-run/burn 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# Changelog
+
+## 0.2.5 (2026-09-18)
+
+- Attribute session usage from measured deltas: fixed-prefix context, cached history, tool output, repeated Read results and conversation. Use bytes only to split a measured increment, with mixed intervals counted as shared.
+- Preserve every recorded token across output, rewrites, child fan-out and the residual. The Method footer explains each bucket, baseline resets and the prior-output subtraction retained in the residual.
+- Keep baseline and event state across responses for correct last-turn shares and category pricing. Repeated usage snapshots retain their original event interval; old pace caches rebuild local metadata once.
+- Validate every bucket against a constructed session, including UTF-8 weights, integer rounding, prefix changes, duplicate events and per-category conservation.
+- Tests: 120 passing by default, one opt-in stress test skipped.
+
+## 0.2.4 (2026-09-18)
+
+- Add local `why`, `rewrites`, `pace`, `statusline` and `pricing` commands. Assistant usage is reconciled by response identity, with unknown attribution kept explicit and child usage identified from transcript metadata.
+- Explain full-prefix cache writes, measured lifetimes, cause evidence and API list cost. Warn on configurable rewrite spend and heavy context crossings without blocking ordinary tools.
+- Observe every Claude Code and Codex tool call. Track cached and uncached ten-minute pace. Forecast limits only from fresh host percentage observations; provide a companion terminal line where Codex cannot run a custom footer command.
+- Bundle dated model pricing and local overrides. Keep unknown models unpriced, content out of persisted metadata, and new reporting paths free of network calls.
+- Raise reservation lock wait to eight seconds, serialize stale-lock retirement, and exclude operational lock-wait failures from enforce eligibility. Old ledgers and receipts remain readable.
+- Validate a 240-process burst: exactly 40 admitted, 200 denied, 240 signed receipts, zero lock failures and a valid chain.
+- Tests: 106 passing by default, one opt-in stress test skipped. The separate stress run also passes.
+
 ## 0.2.3 (2026-09-15)
 
 - Replay evidence refreshed from this machine: 4 STOP, 3 WARN, 431 clean across
@@ -16,8 +36,6 @@
   identifiers, and stop labelling every omitted replay session as clean.
 - Tests: 47 passing by default, one stress test skipped unless AGENTGUARD_STRESS=1.
 
-# Changelog
-
 ## 0.2.2 (2026-09-03)
 
 - Codex: `status` and `init codex --write` now say, every time, that the

package/README.md

@@ -1,16 +1,63 @@
 # @agentguard-run/burn
 
-Local runaway-agent circuit breaker for AI coding agents.
+See where a coding session's tokens went and what the next heavy turn could cost in time and limits. Burn explains recorded usage, warns about large cache rewrites and keeps its existing runaway-session circuit breaker. Everything stays on this machine.
 
-Raw token counters did not help. You see "360k tokens" and keep going. This
-tool does the three things a counter does not: it decides whether a session is
-pathological, it blocks the next agent spawn when it is, and it tells you what
-to do about it. Nothing leaves the machine.
+## Install in five lines
+
+```sh
+npm i -g @agentguard-run/burn
+agentguard-burn init claude
+agentguard-burn init codex
+agentguard-burn statusline
+agentguard-burn why
+```
+
+The two init commands print hook configuration for review. Merge the relevant snippet into your host configuration. They do not write it. For Codex, review and trust the hook through `/hooks`. Upgrading an existing hook requires the new snippet: it matches every tool so pace can update on ordinary tool calls, while admission still gates spawns.
+
+For Claude Code, configure its `statusLine` command as `agentguard-burn statusline`. It receives the host JSON on stdin. Codex 0.154.0 has no external status command slot. Use `agentguard-burn statusline SESSION_ID` in a companion terminal and the native Codex limit indicators. See [host fields and setup](docs/USAGE_AND_PRICING.md#what-the-hosts-expose).
+
+## Why this session
+
+```sh
+agentguard-burn why
+agentguard-burn why SESSION_ID
+agentguard-burn rewrites SESSION_ID
+agentguard-burn rewrites all
+agentguard-burn pace SESSION_ID
+agentguard-burn pricing
+```
+
+A session argument can also be a transcript path. Without one, Burn uses the session environment variable when available, then the most recently modified local transcript. Claude child transcripts are included in `why`. Token shares are shares of recorded tokens, not shares of dollars. Repeated usage records for one provider response count once. Copied Codex history is reconciled before counting new usage.
+
+The table covers instruction stack + system, history re-sent, repeated file reads, subagent fan-out, tool output, conversation, full-prefix rewrites, output and unattributed usage. The fixed-prefix baseline is the first assistant response's measured context. It includes the initial user message, so the label is an operational baseline rather than a direct measurement of instruction files. A rewrite classified as prefix change resets that baseline and is counted in the footer; the new baseline can include history already present at that point.
+
+Later cache reads up to the baseline go to instruction stack + system. Reads above it go to history re-sent. Fresh input plus cache creation is the measured arriving increment. Burn subtracts the previous response's output before assigning that increment to intervening tool results and user messages. Result byte sizes only split that measured total; bytes are never converted into tokens. A result for a previously read Read path goes to re-read files. Mixed user and tool intervals are marked shared and counted in the footer.
+
+Rewrite tokens and child transcript usage keep their own buckets. Prior output deducted from an input increment remains in the unattributed residual so every recorded input and output token is counted exactly once. Missing event evidence also remains there. Integer allocation preserves every token, and the Method footer explains each row.
+
+A full-prefix rewrite writes more than 150,000 tokens and more than half the actual input context. Burn reports the observed cache lifetime and surrounding evidence: idle beyond that lifetime, immediate compaction, first subagent response, or residual prefix change. An unknown lifetime stays unknown. Each write is priced at its measured lifetime, or a range when that lifetime is unavailable.
+
+Every tool hook updates a local pace file under the Burn home. Pace uses ten wall-clock minutes: cached means cache reads; uncached means fresh input, writes and output. The next-hour projection assumes that pace continues. A time-to-limit estimate requires rising, fresh host percentage samples from the same quota pool and reset window. No token-to-limit conversion or cache weighting is assumed. Without sufficient host data, the line says why the limit is unknown.
+
+The new warnings are advisory in both modes. Cache rewrites warn once when their last-hour API list equivalent exceeds $5. A context crossing 500,000 tokens warns about processing time and compaction, estimates a cache rewrite, and suggests a fresh session with a handoff note. These warnings do not deny a tool call.
+
+Optional settings in your existing `burn-policy.json`:
+
+```json
+{
+  "insights": {
+    "rewriteWarnDollarsPerHour": 5,
+    "heavyTurnTokens": 500000
+  }
+}
+```
+
+Merge these fields into the existing policy. All existing thresholds and modes remain supported. Prices are exact-model API list equivalents, not a subscription bill. Unknown models show tokens only. Every rate has a source and verification date. A local override file and full pricing table are documented in [Usage and pricing](docs/USAGE_AND_PRICING.md).
 
 ## Two safety planes
 
 Originally fitted against 412 real Claude Code sessions, then replayed on
-2026-09-15 against 438 sessions. The history shows two independent
+2026-09-18 against 453 sessions. The history shows two independent
 failure shapes that one detector cannot cover:
 
 | Plane | Catches | Rule | Validated on |
@@ -18,11 +65,14 @@ failure shapes that one detector cannot cover:
 | Structural | fan-out storms: many agents re-sending context | WARN 24 spawns, STOP before spawn 41, no agents-spawning-agents past depth 2 | 59-, 190- and 226-spawn sessions; the 190-spawn session has a 4.35B post-STOP tail (92%) |
 | Economic | slow grinds: few agents, enormous total | WARN 3.5B, STOP 5B tokens per session | the 9.15B / 26-spawn session the spawn cap could not see |
 
-The 2026-09-15 replay snapshot: **4 STOP, 3 WARN, 431 clean across 438
-sessions and 616 spawns**. Replay hero: **32%** — **10.27B** of **32.58B**
-observed tokens came after a STOP boundary; API-list scenario **$4,639**.
+The 2026-09-18 replay snapshot: **5 STOP, 3 WARN, 445 clean across 453
+sessions and 662 spawns**. Replay hero: **30%**. **10.80B** of **36.30B**
+recorded tokens came after a STOP boundary; API-list scenario **$4,832**.
 This is an upper bound assuming no override or restart. Replay does not label
-false positives. Active histories can change the next replay result.
+false positives. Active histories can change the next replay result. The existing replay
+counters retain their published behavior and can include repeated streaming
+usage records. The new `why` report reconciles provider responses, so its
+totals can differ. Do not treat replay as a reconciled invoice.
 
 Cache-read ratio was about 98% in the original calibration, healthy and pathological alike. It
 is shown as an explanation and never used to decide.
@@ -85,7 +135,7 @@ What each host can actually see is stated, not implied:
 | Ollama proxy | none | none | authoritative | `prompt_eval_count` + `eval_count` on the final chunk |
 | vLLM / LM Studio / OpenAI-compatible proxy | none | none | authoritative when the server sends `usage`, else reported missing | non-streaming `usage`, or the final SSE usage event |
 | Cursor (beta) | authoritative | estimated | none | native `subagentStart` deny; hosted-model usage is never exposed |
-| Codex (beta) | authoritative | estimated | estimated | `PreToolUse` on `spawn_agent`; live deny, allow and override canary passed on codex-cli 0.151.0; transcript parsed best-effort |
+| Codex (beta) | authoritative | estimated | estimated | `PreToolUse` on every tool, with admission on `spawn_agent`; live deny, allow and override canary passed on codex-cli 0.151.0; transcript parsed best-effort |
 
 An `OK` from a host that cannot see usage is an OK about spawns, and `status`
 says `usage:n/a` next to it. Missing usage never becomes a guessed zero.
@@ -211,6 +261,11 @@ grabbed the instance it judged, and every write is fenced on the holder's
 own nonce still being on the path. In 0.2.3, bounded, staggered retries prevent
 lock waiters from starving the holder. The Sep 15 audit includes one successful
 240-process run after that fix; it does not establish a 192-run guarantee.
+In 0.2.4, the wait is eight seconds and retirement is serialized before
+renaming an abandoned lock. The fresh 240-process run admitted exactly 40,
+denied 200, signed 240 receipts and had zero lock failures. Operational
+lock-wait failures do not count toward enforce eligibility. See the
+[conservative recovery procedure](docs/USAGE_AND_PRICING.md#reservation-lock-recovery).
 
 Single-machine by design. Two laptops on one account do not share state, and
 that is stated rather than hidden.
@@ -228,5 +283,4 @@ a would-block decision in shadow and blocks new work only in enforce mode.
 ## What it never does
 
 No prompts, responses, file contents, or tool inputs are persisted or rendered.
-No telemetry. No provider-quota guesses: it projects against your configured
-policy, never against a subscription allowance it cannot see.
+No telemetry. No provider-quota guesses. Account forecasts use only observed host percentages, never an invented allowance or cache weighting.

package/dist/src/adapters/codex.js

@@ -33,11 +33,21 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const events_1 = require("../events");
 const render_1 = require("../replay/render");
+const live_1 = require("../insights/live");
+const pre_tool_use_1 = require("../hook/pre-tool-use");
 /** Fields this renderer must never emit. Codex rejects the whole object if they appear. */
 exports.CODEX_FORBIDDEN_FIELDS = ['continue', 'stopReason', 'suppressOutput', 'decision', 'reason'];
 const HOST = 'codex';
 const SPAWN_TOOLS = new Set(['Agent', 'spawn_agent', 'Task']);
 function handleCodexHook(raw, gateway, now = Date.now()) {
+    const parsed = parse(raw);
+    if (!parsed)
+        return {};
+    const observation = (0, live_1.observeTool)(gateway.dataDirectory, { session_id: parsed.sessionId, transcript_path: parsed.transcriptPath, tool_name: parsed.toolName }, 'codex', (0, pre_tool_use_1.loadPolicy)(gateway.dataDirectory), now);
+    const output = parsed.event === 'PreToolUse' && SPAWN_TOOLS.has(parsed.toolName) ? handleCodexSpawnHook(raw, gateway, now) : {};
+    return observation.messages.length ? { ...output, systemMessage: [output.systemMessage, ...observation.messages].filter(Boolean).join('\n') } : output;
+}
+function handleCodexSpawnHook(raw, gateway, now) {
     const input = parse(raw);
     if (!input)
         return {};
@@ -190,7 +200,7 @@ function walk(value, path) {
 function codexHooksSnippet(command) {
     return {
         hooks: {
-            PreToolUse: [{ matcher: '^(Agent|spawn_agent)$', hooks: [{ type: 'command', command, timeout: 5 }] }],
+            PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 15 }] }],
         },
     };
 }

package/dist/src/adapters/cursor.js

@@ -127,8 +127,8 @@ function cursorHooksSnippet(command) {
     return {
         version: 1,
         hooks: {
-            subagentStart: [{ command, timeout: 5, failClosed: true }],
-            subagentStop: [{ command, timeout: 5 }],
+            subagentStart: [{ command, timeout: 15, failClosed: true }],
+            subagentStop: [{ command, timeout: 15 }],
             sessionEnd: [{ command, timeout: 3 }],
         },
     };

package/dist/src/cli.js

@@ -33,6 +33,11 @@ const server_1 = require("./proxy/server");
 const render_1 = require("./replay/render");
 const simulate_1 = require("./replay/simulate");
 const status_1 = require("./status");
+const eligibility_1 = require("./eligibility");
+const sessions_1 = require("./insights/sessions");
+const transcript_1 = require("./insights/transcript");
+const live_1 = require("./insights/live");
+const render_2 = require("./insights/render");
 const HOME = process.env.AGENTGUARD_HOME ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.agentguard');
 const PROXY_HOSTS = ['ollama', 'vllm', 'lm-studio', 'openai-compatible'];
 function readStdinJson() {
@@ -66,18 +71,7 @@ function readDecisions() {
         .filter((x) => x !== null);
 }
 function shadowEligibility() {
-    const decisions = readDecisions();
-    const first = decisions.length ? Number(decisions[0].at) : Date.now();
-    const days = (Date.now() - first) / 86_400_000;
-    const wouldBlock = decisions.filter((d) => d.wouldDeny === true).length;
-    const warns = decisions.filter((d) => d.verdict === 'WARN').length;
-    return {
-        eligible: decisions.length >= defaults_1.SHADOW_MIN_DECISIONS && days >= defaults_1.SHADOW_MIN_DAYS,
-        decisions: decisions.length,
-        days,
-        wouldBlock,
-        warns,
-    };
+    return (0, eligibility_1.computeShadowEligibility)(readDecisions());
 }
 async function main(argv) {
     const [command, ...rest] = argv;
@@ -87,6 +81,33 @@ async function main(argv) {
     };
     const has = (name) => rest.includes(name);
     switch (command) {
+        case 'why': {
+            const location = (0, sessions_1.selectInsightTranscript)(rest.find(value => value !== 'json'));
+            const transcript = (0, transcript_1.readInsightSession)(location.path, { host: location.host, sessionId: location.sessionId });
+            process.stdout.write(rest.includes('json') ? JSON.stringify(transcript, null, 2) + '\n' : (0, render_2.renderWhy)(transcript, (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n');
+            return 0;
+        }
+        case 'rewrites': {
+            const session = rest.find(value => value !== 'json');
+            const locations = session === 'all' ? (0, sessions_1.discoverInsightTranscripts)() : [(0, sessions_1.selectInsightTranscript)(session)];
+            const transcripts = locations.map(location => (0, transcript_1.readInsightTranscript)(location.path, { host: location.host, sessionId: location.sessionId }));
+            const rates = (0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME));
+            process.stdout.write(rest.includes('json') ? JSON.stringify((0, render_2.rewriteReport)(transcripts, rates), null, 2) + '\n' : (0, render_2.renderRewrites)(transcripts, rates) + '\n');
+            return 0;
+        }
+        case 'pricing': {
+            process.stdout.write((0, render_2.renderPricing)((0, live_1.readPricing)(HOME, (0, pre_tool_use_1.loadPolicy)(HOME))) + '\n');
+            return 0;
+        }
+        case 'statusline':
+        case 'pace': {
+            const raw = command === 'statusline' && !process.stdin.isTTY ? readStdinJson() : null;
+            const payload = raw && typeof raw === 'object' ? raw : {};
+            const location = (0, sessions_1.selectInsightTranscript)(payload.transcript_path || rest[0] || payload.session_id);
+            const observation = (0, live_1.observeTool)(HOME, { ...payload, session_id: payload.session_id || location.sessionId, transcript_path: location.path }, location.host, (0, pre_tool_use_1.loadPolicy)(HOME));
+            process.stdout.write((observation.snapshot ? (0, live_1.renderStatusLine)(observation.snapshot) : 'AgentGuard pace unavailable: local usage metadata is not readable.') + '\n');
+            return observation.snapshot ? 0 : 1;
+        }
         case 'hook': {
             const raw = (0, node_fs_1.readFileSync)(0, 'utf8');
             let input = {};
@@ -141,6 +162,7 @@ async function main(argv) {
                 `shadow observation: ${e.decisions} decisions over ${e.days.toFixed(1)} days`,
                 `  would have warned: ${e.warns}   would have blocked: ${e.wouldBlock}`,
                 `eligible for enforcement: ${e.eligible ? 'yes  (agentguard-burn enforce)' : `no (need ${defaults_1.SHADOW_MIN_DECISIONS} decisions and ${defaults_1.SHADOW_MIN_DAYS} days)`}`,
+                `lock-wait failures excluded from eligibility: ${e.excludedLockWaitFailures}`,
                 override ? `override ACTIVE: ${override.once ? 'the next STOP' : `every STOP until ${new Date(override.until).toLocaleTimeString()}`} passes ("${override.reason}")` : '',
                 '',
                 (0, status_1.renderHostHealth)(['claude', 'cursor', 'codex'].map((h) => (0, install_1.health)(h))),
@@ -270,7 +292,12 @@ async function main(argv) {
             return 0;
         }
         default:
-            process.stdout.write('agentguard-burn <replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
+            process.stdout.write('agentguard-burn <why|rewrites|pace|statusline|pricing|replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\n' +
+                '  why [session]       token attribution and API list-price equivalents\n' +
+                '  rewrites [session|all]   full-prefix cache writes by cause\n' +
+                '  pace [session]      ten-minute pace and next-hour projection\n' +
+                '  statusline [session]   one-line local status; accepts Claude status JSON\n' +
+                '  pricing             verified model rates and local overrides\n' +
                 '  replay [files...] [--json] [--top N] [--min-tokens N]\n' +
                 '  calibrate            fit thresholds to your history (writes shadow policy)\n' +
                 '  status               mode, shadow observations, eligibility, hook health, every host\n' +

package/dist/src/defaults.d.ts

@@ -3,8 +3,10 @@ import type { Policy, Thresholds } from './types';
  * Shipped thresholds.
  *
  * Originally fitted against 412 real Claude Code sessions. Replayed on the
- * author's machine on 2026-09-15: 438 sessions, 616 spawns, 32.58B tokens;
- * 4 STOP, 3 WARN, 431 clean. The observed post-STOP tail is 10.27B (32%).
+ * author's machine on 2026-09-18: 453 sessions, 662 spawns, 36.30B recorded tokens;
+ * 5 STOP, 3 WARN, 445 clean. The recorded post-STOP tail is 10.80B (30%).
+ * Legacy replay counters can include repeated streaming usage records. The
+ * new insights report reconciles provider responses instead.
  * Fan-out 24/40 stops before spawn 41 on the 59-, 190- and 226-spawn
  * sessions; sustained 3.5B/5B catches the 9.15B / 26-spawn slow grind.
  * This is a dated replay snapshot and an upper bound, not labelled evidence

package/dist/src/defaults.js

@@ -5,8 +5,10 @@ exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_
  * Shipped thresholds.
  *
  * Originally fitted against 412 real Claude Code sessions. Replayed on the
- * author's machine on 2026-09-15: 438 sessions, 616 spawns, 32.58B tokens;
- * 4 STOP, 3 WARN, 431 clean. The observed post-STOP tail is 10.27B (32%).
+ * author's machine on 2026-09-18: 453 sessions, 662 spawns, 36.30B recorded tokens;
+ * 5 STOP, 3 WARN, 445 clean. The recorded post-STOP tail is 10.80B (30%).
+ * Legacy replay counters can include repeated streaming usage records. The
+ * new insights report reconciles provider responses instead.
  * Fan-out 24/40 stops before spawn 41 on the 59-, 190- and 226-spawn
  * sessions; sustained 3.5B/5B catches the 9.15B / 26-spawn slow grind.
  * This is a dated replay snapshot and an upper bound, not labelled evidence

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

@@ -50,6 +50,8 @@ function safeName(sessionId) {
 }
 class Gateway {
     home;
+    /** Shared local storage for optional content-free usage observations. */
+    get dataDirectory() { return this.home; }
     store;
     signer;
     now;

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

@@ -35,6 +35,7 @@ const session_1 = require("../state/session");
 const defaults_1 = require("../defaults");
 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`);
@@ -127,6 +128,13 @@ function rememberNotified(home, sessionId, signature) {
     }
 }
 function handlePreToolUse(input, home, now = Date.now()) {
+    const observation = (0, live_1.observeTool)(home, input, 'claude', 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 };
@@ -231,7 +239,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;

package/dist/src/insights/attribution.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyRewrite = classifyRewrite;
+exports.attributeTurns = attributeTurns;
+const types_1 = require("./types");
+const transcript_1 = require("./transcript");
+function classifyRewrite(turn) {
+    if (!(turn.cacheWriteTokens > 150_000 && turn.cacheWriteTokens > turn.contextTokens / 2))
+        return null;
+    const idleMs = turn.signals.idleMs;
+    const ttl = turn.cacheTtlSeconds;
+    const evidence = { turnId: turn.id, cacheWriteTokens: turn.cacheWriteTokens, contextTokens: turn.contextTokens,
+        ...(idleMs !== undefined ? { idleMs } : {}), idleOver60Minutes: idleMs !== undefined && idleMs > 3_600_000,
+        ...(ttl ? { ttlSeconds: ttl } : {}), ttlUnknown: !ttl };
+    if (ttl && idleMs !== undefined && idleMs > ttl * 1000)
+        return { ...evidence, cause: 'idle_ttl_expired', explanation: 'Idle gap exceeds the TTL reported for this cache-write class; timing is consistent with expiration.' };
+    if (turn.signals.afterCompaction)
+        return { ...evidence, cause: 'compaction', explanation: 'A compaction boundary immediately precedes this usage turn.' };
+    if (turn.signals.firstSpawnedTurn)
+        return { ...evidence, cause: 'first_spawned_turn', explanation: 'This is the first recorded usage turn in an explicitly identified subagent session.' };
+    if (!ttl)
+        return { ...evidence, cause: 'unknown_ttl', explanation: 'Cache TTL is absent or mixed; expiration cannot be distinguished from a prefix change.' };
+    return { ...evidence, cause: 'prefix_change', explanation: turn.signals.prefixChanged
+            ? 'The host reports a changed prefix identifier without an expired-TTL or compaction signal.'
+            : 'No expiration, compaction, or first-subagent-turn signal explains the rewrite; prefix change is a residual hypothesis, not an observed cause.' };
+}
+const tokenCategories = ['input', 'cacheCreation', 'cacheRead', 'output'];
+const emptyBuckets = () => types_1.INSIGHT_BUCKETS.map(bucket => ({ bucket, tokens: 0,
+    categories: { input: 0, cacheCreation: 0, cacheRead: 0, output: 0 } }));
+/** Largest remainders split an already measured token total without inventing tokens from bytes. */
+function integerShares(total, weights) {
+    const weight = weights.reduce((sum, value) => sum + value, 0);
+    if (!weight || !total)
+        return weights.map(() => 0);
+    const exact = weights.map(value => total * (value / weight));
+    const shares = exact.map(Math.floor);
+    const order = exact.map((value, index) => ({ index, remainder: value - shares[index] }))
+        .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+    for (let left = total - shares.reduce((sum, value) => sum + value, 0), i = 0; left > 0; left--, i++)
+        shares[order[i % order.length].index]++;
+    return shares;
+}
+/** Partition measured usage; byte lengths only divide a measured increment among its recorded events. */
+function attributeTurns(turns) {
+    const buckets = emptyBuckets();
+    const byBucket = new Map(buckets.map(bucket => [bucket.bucket, bucket]));
+    const result = { buckets, totalTokens: 0, rewrites: [],
+        rewriteCounts: { idle_ttl_expired: 0, compaction: 0, first_spawned_turn: 0, prefix_change: 0, unknown_ttl: 0 },
+        idleOver60MinuteRewrites: 0, uncertainties: [], turnAttributions: [], sharedTurns: 0,
+        prefixRebaselines: 0, previousOutputTokensReserved: 0 };
+    const uncertainties = new Set();
+    const sessions = new Map();
+    const ordered = (0, transcript_1.deduplicateTurns)(turns).sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+    for (const turn of ordered) {
+        const remaining = { input: turn.inputTokens, cacheCreation: turn.cacheWriteTokens, cacheRead: turn.cacheReadTokens, output: turn.outputTokens };
+        const turnBuckets = emptyBuckets();
+        const turnByBucket = new Map(turnBuckets.map(bucket => [bucket.bucket, bucket]));
+        const totalTokens = Object.values(remaining).reduce((sum, value) => sum + value, 0);
+        result.totalTokens += totalTokens;
+        const allocate = (bucket, category, tokens) => {
+            const amount = Math.min(remaining[category], Math.max(0, tokens));
+            if (amount < tokens)
+                uncertainties.add('attribution_evidence_exceeds_category_total');
+            for (const target of [byBucket.get(bucket), turnByBucket.get(bucket)]) {
+                target.tokens += amount;
+                target.categories[category] += amount;
+            }
+            remaining[category] -= amount;
+        };
+        const previous = sessions.get(turn.sessionId);
+        let prefix = previous?.prefix ?? turn.contextTokens;
+        allocate('output', 'output', remaining.output);
+        const rewrite = classifyRewrite(turn);
+        if (rewrite) {
+            result.rewrites.push(rewrite);
+            result.rewriteCounts[rewrite.cause]++;
+            if (rewrite.idleOver60Minutes)
+                result.idleOver60MinuteRewrites++;
+            allocate('full_prefix_rewrites', 'cacheCreation', remaining.cacheCreation);
+            if (rewrite.ttlUnknown)
+                uncertainties.add('rewrite_ttl_unknown');
+            if (rewrite.cause === 'prefix_change') {
+                prefix = turn.contextTokens;
+                if (previous)
+                    result.prefixRebaselines++;
+                if (!turn.signals.prefixChanged)
+                    uncertainties.add('prefix_change_is_residual_hypothesis');
+            }
+        }
+        for (const item of turn.explicitAttribution) {
+            if (item.bucket !== 'output' && item.bucket !== 'full_prefix_rewrites' && item.bucket !== 'unattributed' && Number.isSafeInteger(item.tokens) && item.tokens > 0)
+                allocate(item.bucket, item.category, item.tokens);
+        }
+        if (turn.subagent) {
+            for (const category of ['input', 'cacheCreation', 'cacheRead'])
+                allocate('subagent_fanout', category, remaining[category]);
+        }
+        else if (!turn.explicitAttribution.length) {
+            if (!previous || rewrite?.cause === 'prefix_change') {
+                // Rewrites retain their measured write tokens; the rest establishes the new fixed prefix.
+                for (const category of ['input', 'cacheCreation', 'cacheRead'])
+                    allocate('instruction_stack', category, remaining[category]);
+            }
+            else {
+                const history = Math.max(0, turn.cacheReadTokens - prefix);
+                allocate('instruction_stack', 'cacheRead', Math.min(remaining.cacheRead, prefix));
+                allocate('history_resent', 'cacheRead', Math.min(remaining.cacheRead, history));
+                if (!rewrite) {
+                    // Prior assistant output reappears in input usage but is not newly arrived content.
+                    // Keep that measured input in the residual rather than count it as generated output twice.
+                    let reserved = Math.min(previous.previousOutput, remaining.input + remaining.cacheCreation);
+                    result.previousOutputTokensReserved += reserved;
+                    for (const category of ['input', 'cacheCreation']) {
+                        const amount = Math.min(reserved, remaining[category]);
+                        allocate('unattributed', category, amount);
+                        reserved -= amount;
+                    }
+                    const interval = turn.interval;
+                    const eventBuckets = ['tool_output', 'reread_files', 'conversation'];
+                    let weights = interval ? [interval.toolOutputBytes, interval.reReadBytes, interval.conversationBytes] : [0, 0, 0];
+                    if (interval && !weights.some(value => value > 0)) {
+                        // A sole event class owns the whole measured increment even for an
+                        // empty result; mixed empty payloads have no byte-based split.
+                        const present = [interval.toolResults > (interval.reReadResults ?? 0), (interval.reReadResults ?? 0) > 0, interval.userMessages > 0];
+                        if (present.filter(Boolean).length === 1)
+                            weights = present.map(value => value ? 1 : 0);
+                    }
+                    if (weights.some(value => value > 0)) {
+                        const shares = integerShares(remaining.input + remaining.cacheCreation, weights);
+                        const inputs = integerShares(remaining.input, shares);
+                        if (interval.shared && shares.some(value => value > 0))
+                            result.sharedTurns++;
+                        eventBuckets.forEach((bucket, i) => {
+                            allocate(bucket, 'input', inputs[i]);
+                            allocate(bucket, 'cacheCreation', shares[i] - inputs[i]);
+                        });
+                    }
+                }
+            }
+        }
+        for (const category of tokenCategories)
+            allocate('unattributed', category, remaining[category]);
+        turn.uncertainties.forEach(value => uncertainties.add(value));
+        sessions.set(turn.sessionId, { prefix, previousOutput: turn.outputTokens });
+        result.turnAttributions.push({ turnId: turn.id, sessionId: turn.sessionId, buckets: turnBuckets, totalTokens });
+    }
+    if (byBucket.get('unattributed').tokens)
+        uncertainties.add('unattributed_usage_includes_prior_output_and_missing_event_evidence');
+    result.uncertainties = [...uncertainties].sort();
+    return result;
+}

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

@@ -0,0 +1,53 @@
+import type { Policy } from '../types';
+import type { InsightHost, InsightParserState, InsightTurn } from './types';
+import { type PricingTable } from './pricing';
+import { type Pace, type UsageWindow, type LimitForecast } from './pace';
+export interface InsightSettings {
+    rewriteWarnDollarsPerHour?: number;
+    heavyTurnTokens?: number;
+    pricingFile?: string;
+}
+export interface LiveSnapshot {
+    schema: 1;
+    host: InsightHost;
+    sessionId: string;
+    updatedAt: number;
+    toolEvents: number;
+    cursor: {
+        offset: number;
+        inode: number;
+        pathDigest: string;
+    };
+    parser?: InsightParserState;
+    pace: Pace;
+    windows: UsageWindow[];
+    forecast: LimitForecast;
+    lastTurnTokens: number;
+    rewriteDollarsToday: {
+        min: number;
+        max: number;
+    } | null;
+    unpricedRewritesToday: number;
+    heavyAbove: boolean;
+    rewriteAbove: boolean;
+}
+export interface LiveInput {
+    session_id?: string;
+    transcript_path?: string;
+    tool_name?: string;
+    rate_limits?: unknown;
+}
+export declare function pacePath(home: string, sessionId: string): string;
+export declare function readPricing(home: string, policy?: Policy): PricingTable;
+export declare function dollars(value: {
+    min: number;
+    max: number;
+} | null): string;
+export declare function hostWindows(value: unknown, source: UsageWindow['source'], at: number): UsageWindow[];
+export declare function heavyTurnMessage(turn: InsightTurn, rates: PricingTable): string;
+/** Local advisory observer. No tool input or output content enters this API. */
+export declare function observeTool(home: string, input: LiveInput, host: InsightHost, policy: Policy, now?: number): {
+    snapshot?: LiveSnapshot;
+    messages: string[];
+};
+export declare function renderStatusLine(snapshot: LiveSnapshot): string;