@agentguard-run/burn 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.2.2 (2026-09-03)
+
+- Codex: `status` and `init codex --write` now say, every time, that the
+  hook must be trusted once with `/hooks` inside Codex. Verified that an
+  untrusted hook stalls `codex exec` with no output the first time a spawn
+  would be gated, from `hooks.json` and from `config.toml` alike.
+- Verified the installed Claude Code hook end to end from the global
+  install: 0.2s on a 1.95B-token transcript, decision recorded.
+
+## 0.2.1 (2026-09-03)
+
+Finishing the product so it can be used, and a live Codex canary.
+
+### Added
+- `agentguard-burn resume --once` is now real. The STOP box has advertised it
+  since 0.1.0; nothing read the file. Every host consults the override only
+  when a block is due, consumes a `--once` atomically (rename), records the
+  reason in the decisions ledger, and `resume --reason` without `--once`
+  opens a 15-minute window; `--clear` ends it.
+- `init [claude|cursor|codex] --write`: merges the hook into the host's
+  config with a timestamped backup, finds an existing AgentGuard entry by
+  its command and upgrades it in place, refuses to touch a file it cannot
+  parse.
+- `status` shows hook health per host (installed, command exists on disk;
+  a missing script is called out in capitals because that hook fails open),
+  Claude Code sessions alongside gateway sessions, and any active override.
+- Warnings are announced once per change in the finding set, on every host.
+- Captured codex-cli 0.151.0 payloads as a fixture; a test runs on them.
+
+### Verified
+- Codex: live canary on codex-cli 0.151.0. `spawn_agent` denied with the
+  alarm box as the reason; `Bash` passed untouched; `resume --once` let the
+  next spawn through with the reason on the ledger. Codex moves from
+  experimental to beta. The wire sends `tool_name: "spawn_agent"` (the docs
+  say it matches as `Agent`; the matcher covers both). Project-local hooks
+  load only when the project is trusted; the user-layer file needs a
+  one-time `/hooks` trust inside Codex.
+
 ## 0.2.0 (2026-09-03)
 
 The cross-tool layer. One policy, one lock, one receipt across hosts.

package/README.md

@@ -33,14 +33,32 @@ have intercepted, when, and the observed tail after each stop. It is an upper
 bound, labelled as such. Nobody installs a blocker cold.
 
 ```
-npx @agentguard-run/burn calibrate    # fit thresholds to your own usage
-npx @agentguard-run/burn init         # print the settings.json hook snippet
-npx @agentguard-run/burn status       # shadow observations, eligibility
-npx @agentguard-run/burn enforce      # after 7 days and 50 decisions
+npm i -g @agentguard-run/burn
+agentguard-burn init --write          # merge the hook into ~/.claude/settings.json (backup taken)
+agentguard-burn init codex --write    # same for ~/.codex/hooks.json
+agentguard-burn status                # hook health, shadow observations, every live session
+agentguard-burn enforce               # after 7 days and 50 decisions
 ```
 
 The hook installs in **shadow mode**: every decision is recorded, nothing is
-blocked, until you have seen it be right.
+blocked, until you have seen it be right. `status` shows what it would have
+done so far, which sessions are live on every host, and whether each hook's
+command still exists on disk (a hook whose script is gone fails open, and
+`status` says so in capitals).
+
+### When it stops you and you disagree
+
+```
+agentguard-burn resume --once --reason "these 60 agents are the plan"   # the next STOP passes, once, on any host
+agentguard-burn resume --reason "load test"                              # every STOP passes for 15 minutes
+agentguard-burn resume --clear
+```
+
+Every override is written to the decisions ledger with its reason. A
+`--once` override is consumed atomically: two hooks racing for it cannot
+both pass. Warnings are spoken once per change in the finding set, not once
+per spawn; eighteen identical banners train you to stop reading the
+nineteenth.
 
 ## One policy across hosts (0.2.0)
 
@@ -62,7 +80,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 (experimental) | authoritative | estimated | estimated | `PreToolUse` on `spawn_agent`; transcript parsed best-effort |
+| 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 |
 
 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.
@@ -128,10 +146,29 @@ agentguard-burn init codex     # ~/.codex/hooks.json snippet
 Both renderers are one page each and emit only their host's documented output
 object. Codex fails the whole hook on Claude's common fields (`continue`,
 `stopReason`, `suppressOutput`), and a failed hook is a fail-open hook, so the
-Codex renderer never emits them and a test forbids them by name. Cursor is
-labelled beta and Codex experimental until an installed-version deny canary
-has passed on each; the schemas were verified against the vendors' documents
-on 2026-09-03, not against every installed build.
+Codex renderer never emits them and a test forbids them by name.
+
+**Codex** passed a live canary on the installed codex-cli 0.151.0 on
+2026-09-03: a `spawn_agent` call was denied with the alarm box as the reason,
+a shell call passed untouched, and a `resume --once` override let the next
+spawn through with the reason on the ledger. Two things the docs got wrong
+and the wire settled: the tool arrives as `spawn_agent` (the docs say it
+"matches as Agent"; the matcher covers both), and project-local hooks only
+load when the project is trusted. The captured payloads are in
+`fixtures/codex-0.151.0-pretooluse.json` and drive a test.
+
+One step Codex makes you do by hand: after `init codex --write`, open
+`codex`, run `/hooks`, and trust the AgentGuard hook. Codex requires this
+once per hook source, and there is no CLI for it. Until it is done,
+`codex exec` stalls the first time a spawn would be gated (verified: it
+hangs with no output; the same with hooks defined in `config.toml`).
+`status` repeats this under the codex line because it cannot see whether
+trust was granted.
+
+**Cursor** is verified against the documented schema (`permission`,
+`user_message`, `agent_message`; `~/.cursor/hooks.json` with `failClosed`),
+not yet against an installed build. It stays beta until a live deny canary
+passes.
 
 ### Receipts
 

package/dist/src/adapters/codex.js

@@ -75,7 +75,10 @@ function handleCodexHook(raw, gateway, now = Date.now()) {
     // An unrecorded start leaves its reservation pending until TTL, which is
     // the conservative direction.
     quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'spawn_started', eventId: `codex:start:${spawnId}`, host: HOST, sessionId: input.sessionId, at: now, spawnId, depth: 1 }]));
-    if (decision.verdict !== 'OK') {
+    if (decision.overridden) {
+        return { systemMessage: `AgentGuard STOP overridden${decision.overridden.once ? ' once' : ''} ("${decision.overridden.reason}"): ${decision.report.findings[0]?.summary ?? ''}` };
+    }
+    if (decision.notify && decision.verdict !== 'OK') {
         return {
             systemMessage: `AgentGuard ${decision.verdict}${decision.mode === 'shadow' && decision.wouldBlock ? ' (shadow: would have blocked)' : ''}: ${decision.report.findings[0]?.summary ?? ''}`,
         };

package/dist/src/adapters/cursor.js

@@ -64,7 +64,10 @@ function handleCursorHook(raw, gateway, now = Date.now()) {
         // hook after it has decided; a crash is a fail-open on most hosts.
         const depth = decision.proposedDepth ?? 1;
         quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'spawn_started', eventId: `cursor:start:${spawnId}`, host: HOST, sessionId: input.sessionId, at, spawnId, depth }]));
-        if (decision.verdict === 'WARN' || (decision.mode === 'shadow' && decision.wouldBlock)) {
+        if (decision.overridden) {
+            return { permission: 'allow', agent_message: `AgentGuard STOP overridden${decision.overridden.once ? ' once' : ''} ("${decision.overridden.reason}"): ${decision.report.findings[0]?.summary ?? ''}` };
+        }
+        if (decision.notify && decision.verdict !== 'OK') {
             return {
                 permission: 'allow',
                 agent_message: `AgentGuard ${decision.verdict}${decision.mode === 'shadow' && decision.wouldBlock ? ' (shadow: would have blocked)' : ''}: ${decision.report.findings[0]?.summary ?? ''}`,

package/dist/src/cli.js

@@ -27,6 +27,8 @@ const conformance_1 = require("./conformance");
 const defaults_1 = require("./defaults");
 const gateway_1 = require("./gateway");
 const pre_tool_use_1 = require("./hook/pre-tool-use");
+const install_1 = require("./install");
+const override_1 = require("./override");
 const server_1 = require("./proxy/server");
 const render_1 = require("./replay/render");
 const simulate_1 = require("./replay/simulate");
@@ -131,40 +133,59 @@ async function main(argv) {
             const e = shadowEligibility();
             const gateway = new gateway_1.Gateway(HOME, { sign: false });
             const lc = policy.thresholds.localCompute;
+            const override = (0, override_1.readOverride)(HOME);
             process.stdout.write([
-                `mode: ${policy.mode}`,
+                `mode: ${policy.mode}${policy.mode === 'enforce' ? '  (the next STOP blocks)' : '  (recording only; nothing is blocked)'}`,
                 `thresholds: fan-out ${policy.thresholds.fanout.warn}/${policy.thresholds.fanout.stop}  sustained ${(policy.thresholds.sustained.warnTokens / 1e9).toFixed(1)}B/${(policy.thresholds.sustained.stopTokens / 1e9).toFixed(1)}B  local-compute warn at ${lc?.warnConcurrent ?? 4} concurrent${lc?.stopConcurrent ? `, stop at ${lc.stopConcurrent}` : ' (no stop set)'}`,
                 policy.calibration ? `calibrated from ${policy.calibration.sessionsSampled} sessions` : 'using shipped defaults (run: agentguard-burn calibrate)',
                 `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' : `no (need ${defaults_1.SHADOW_MIN_DECISIONS} decisions and ${defaults_1.SHADOW_MIN_DAYS} days)`}`,
+                `eligible for enforcement: ${e.eligible ? 'yes  (agentguard-burn enforce)' : `no (need ${defaults_1.SHADOW_MIN_DECISIONS} decisions and ${defaults_1.SHADOW_MIN_DAYS} days)`}`,
+                override ? `override ACTIVE: ${override.once ? 'the next STOP' : `every STOP until ${new Date(override.until).toLocaleTimeString()}`} passes ("${override.reason}")` : '',
                 '',
-                (0, status_1.renderMachineStatus)(gateway.sessions(), gateway.compute()),
+                (0, status_1.renderHostHealth)(['claude', 'cursor', 'codex'].map((h) => (0, install_1.health)(h))),
+                '',
+                (0, status_1.renderMachineStatus)([...(0, status_1.readHookSessions)(HOME), ...gateway.sessions()], gateway.compute()),
                 '',
                 'content logging: off · telemetry: none · state: this machine only',
-            ].join('\n') + '\n');
+            ]
+                .filter((l) => l !== '' || true)
+                .join('\n')
+                .replace(/\n\n\n/g, '\n\n') + '\n');
             return 0;
         }
         case 'init': {
             const policy = (0, pre_tool_use_1.loadPolicy)(HOME);
             savePolicy(policy);
             const cli = (0, node_path_1.join)(__dirname, 'cli.js');
-            const target = rest.find((a) => !a.startsWith('--')) ?? 'claude';
-            if (target === 'cursor') {
-                process.stdout.write(`Add this to ~/.cursor/hooks.json (merge into existing "hooks"):\n\n${JSON.stringify((0, cursor_1.cursorHooksSnippet)(`node ${cli} cursor-hook`), null, 2)}\n\n` +
-                    `Cursor support is BETA: verified against the documented hook schema, not yet against every installed version. ` +
-                    `"failClosed": true means a crashed hook denies the subagent.\n` +
-                    `Installed in ${policy.mode} mode. Nothing is blocked until you run: agentguard-burn enforce\n`);
-                return 0;
+            const target = (rest.find((a) => !a.startsWith('--')) ?? 'claude');
+            if (!['claude', 'cursor', 'codex'].includes(target)) {
+                process.stderr.write(`init: host must be claude, cursor or codex\n`);
+                return 64;
             }
-            if (target === 'codex') {
-                process.stdout.write(`Add this to ~/.codex/hooks.json (merge into existing "hooks"):\n\n${JSON.stringify((0, codex_1.codexHooksSnippet)(`node ${cli} codex-hook`), null, 2)}\n\n` +
-                    `Codex support is EXPERIMENTAL: the deny shape is verified against the documented schema; transcript usage is best-effort and marked estimated.\n` +
-                    `Installed in ${policy.mode} mode. Nothing is blocked until you run: agentguard-burn enforce\n`);
+            const label = { claude: '', cursor: 'Cursor support is BETA: verified against the documented hook schema, not yet against every installed build. "failClosed": true means a crashed hook denies the subagent.', codex: 'Codex support is BETA: a live deny, allow and override canary passed on codex-cli 0.151.0; transcript usage is best-effort and marked estimated.\nONE MORE STEP: open codex, run /hooks, and trust the AgentGuard hook. Codex requires this once per hook source; until then `codex exec` stalls the first time a spawn would be gated.' }[target];
+            const tail = `Installed in ${policy.mode} mode. Nothing is blocked until you run: agentguard-burn enforce\n`;
+            if (has('--write')) {
+                let result;
+                try {
+                    result = (0, install_1.install)(target, cli);
+                }
+                catch (error) {
+                    process.stderr.write(`init: refusing to touch ${(0, install_1.configPath)(target)}: ${error instanceof Error ? error.message : String(error)}\n`);
+                    return 1;
+                }
+                process.stdout.write((result.changed ? `Wrote ${result.file}${result.backup ? `  (backup: ${result.backup})` : ''}\n` : `${result.file} already has the current hook; nothing changed.\n`) +
+                    `  ${result.command}\n` +
+                    (label ? `${label}\n` : '') +
+                    tail +
+                    `Check it: agentguard-burn status\n`);
                 return 0;
             }
-            process.stdout.write(`Add this to ~/.claude/settings.json (merge into existing "hooks"):\n\n${JSON.stringify((0, pre_tool_use_1.settingsSnippet)(`node ${cli} hook`), null, 2)}\n\nInstalled in ${policy.mode} mode. Nothing is blocked until you run: agentguard-burn enforce\n` +
-                `Other hosts: agentguard-burn init cursor | init codex | proxy --upstream http://127.0.0.1:11434 --host ollama\n`);
+            const snippet = target === 'cursor' ? (0, cursor_1.cursorHooksSnippet)(`node ${cli} cursor-hook`) : target === 'codex' ? (0, codex_1.codexHooksSnippet)(`node ${cli} codex-hook`) : (0, pre_tool_use_1.settingsSnippet)(`node ${cli} hook`);
+            process.stdout.write(`Add this to ${(0, install_1.configPath)(target).replace(process.env.HOME ?? '', '~')} (merge into existing "hooks"), or run: agentguard-burn init ${target} --write\n\n${JSON.stringify(snippet, null, 2)}\n\n` +
+                (label ? `${label}\n` : '') +
+                tail +
+                (target === 'claude' ? `Other hosts: agentguard-burn init cursor | init codex | proxy --upstream http://127.0.0.1:11434 --host ollama\n` : ''));
             return 0;
         }
         case 'cursor-hook': {
@@ -230,20 +251,34 @@ async function main(argv) {
             return 0;
         }
         case 'resume': {
-            const reason = flag('--reason') ?? 'no reason given';
-            (0, node_fs_1.mkdirSync)(HOME, { recursive: true, mode: 0o700 });
-            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(HOME, 'override.json'), JSON.stringify({ at: Date.now(), once: has('--once'), reason }), { mode: 0o600 });
-            process.stdout.write(`Override recorded${has('--once') ? ' for the next STOP only' : ''}: ${reason}\n`);
+            if (has('--clear')) {
+                (0, override_1.clearOverride)(HOME);
+                process.stdout.write('Override cleared. The next STOP blocks.\n');
+                return 0;
+            }
+            const reason = flag('--reason');
+            if (!reason) {
+                process.stderr.write('resume: --reason "..." is required; every override is written to the decisions ledger with it.\n');
+                return 64;
+            }
+            const once = has('--once');
+            const now = Date.now();
+            (0, override_1.writeOverride)(HOME, once ? { at: now, once: true, reason } : { at: now, once: false, reason, until: now + override_1.OVERRIDE_WINDOW_MS });
+            process.stdout.write(once
+                ? `Override recorded for the next STOP only, on any host: "${reason}"\n`
+                : `Override recorded for the next ${override_1.OVERRIDE_WINDOW_MS / 60000} minutes, on any host: "${reason}"\n  (agentguard-burn resume --clear to end it early)\n`);
             return 0;
         }
         default:
             process.stdout.write('agentguard-burn <replay|calibrate|status|init|enforce|shadow|resume|proxy|conformance>\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, every host\n' +
-                '  init [claude|cursor|codex]   print the hook snippet for that host\n' +
+                '  status               mode, shadow observations, eligibility, hook health, every host\n' +
+                '  init [claude|cursor|codex] [--write]   print the hook snippet, or merge it into the config (with a backup)\n' +
                 '  enforce [--force]    shadow -> enforce\n' +
-                '  resume --once --reason "..."\n' +
+                '  shadow               enforce -> shadow\n' +
+                '  resume --once --reason "..."   let the next STOP through, once, on any host\n' +
+                '  resume --reason "..."          let STOPs through for 15 minutes; --clear ends it\n' +
                 '  proxy --upstream http://127.0.0.1:11434 --host ollama|vllm|lm-studio|openai-compatible [--listen 127.0.0.1:18080] [--session ID]\n' +
                 '  conformance          replay the storm and the grind through every adapter shape\n');
             return command ? 64 : 0;

package/dist/src/gateway.d.ts

@@ -39,6 +39,13 @@ export interface Decision {
     wouldBlock: boolean;
     /** Enforcing, and blocking. */
     blocked: boolean;
+    /** A block was due and the user's recorded override let it through. */
+    overridden: {
+        once: boolean;
+        reason: string;
+    } | null;
+    /** The finding set changed since the user was last told. Adapters speak only when true. */
+    notify: boolean;
     mode: Mode;
     report: BurnReport;
     capabilities: HostCapabilities;

package/dist/src/gateway.js

@@ -38,6 +38,7 @@ const evaluate_1 = require("./detectors/evaluate");
 const local_compute_1 = require("./detectors/local-compute");
 const events_1 = require("./events");
 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 session_1 = require("./state/session");
@@ -224,8 +225,9 @@ class Gateway {
                 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.
-                const blocked = wouldBlock && policy.mode === 'enforce' && event.attribution === 'high';
-                const decision = this.finish({ action: 'spawn', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth, verdict, wouldBlock, blocked, report, effectiveSpawns: reservation.effectiveSpawns, compute: null }, policy, meta, state);
+                const due = wouldBlock && policy.mode === 'enforce' && event.attribution === 'high';
+                const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
+                const decision = this.finish({ action: 'spawn', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth, verdict, wouldBlock, blocked: due && !override, override, report, effectiveSpawns: reservation.effectiveSpawns, compute: null }, policy, meta, state);
                 this.save(meta, state);
                 return decision;
             });
@@ -269,8 +271,10 @@ class Gateway {
                 // A low-confidence session (proxy without a session header) can be
                 // stopped only on machine-scope grounds. Its session count is a guess.
                 const machineStop = local.verdict === 'STOP';
-                const blocked = wouldBlock && policy.mode === 'enforce' && (event.attribution === 'high' || machineStop);
-                const decision = this.finish({ action: 'model_call', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth: null, verdict: report.verdict, wouldBlock, blocked, report, effectiveSpawns: state.spawnCount, compute }, policy, meta, state);
+                const due = wouldBlock && policy.mode === 'enforce' && (event.attribution === 'high' || machineStop);
+                const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
+                const blocked = due && !override;
+                const decision = this.finish({ action: 'model_call', host: event.host, sessionId: event.sessionId, at: event.at, proposedDepth: null, verdict: report.verdict, wouldBlock, blocked, override, report, effectiveSpawns: state.spawnCount, compute }, policy, meta, state);
                 if (blocked) {
                     // A denied call neither occupies the machine nor spends tokens.
                     tx.finishCall(event.callId, windowMs(policy), event.at);
@@ -327,6 +331,11 @@ class Gateway {
         if (d.wouldBlock)
             meta.wouldBlock += 1;
         const decisionId = (0, events_1.eventId)();
+        // Speak once per change, not once per spawn. A block or an override is
+        // always spoken; it is the event the user needs to see.
+        const signature = d.verdict === 'OK' ? '' : (0, pre_tool_use_1.findingSignature)(d.report);
+        const notify = d.blocked || d.override !== null || (signature !== '' && signature !== (meta.notified ?? ''));
+        meta.notified = signature;
         // Sign what matters: every spawn admission, and any call that is not OK.
         // Signing every OK call through a busy proxy would be thousands of
         // receipts an hour saying nothing.
@@ -367,6 +376,7 @@ class Gateway {
             verdict: d.verdict,
             wouldDeny: d.wouldBlock,
             enforced: d.blocked,
+            overridden: d.override ?? undefined,
             mode: policy.mode,
             findings: d.report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
             effectiveSpawns: d.effectiveSpawns,
@@ -380,6 +390,8 @@ class Gateway {
             verdict: d.verdict,
             wouldBlock: d.wouldBlock,
             blocked: d.blocked,
+            overridden: d.override,
+            notify,
             mode: policy.mode,
             report: d.report,
             capabilities: meta.capabilities,
@@ -407,6 +419,8 @@ class Gateway {
             verdict: 'STOP',
             wouldBlock: true,
             blocked: policy.mode === 'enforce',
+            overridden: null,
+            notify: true,
             mode: policy.mode,
             report,
             capabilities: events_1.CAPABILITIES[event.host],

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

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

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

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

package/dist/src/index.d.ts

@@ -19,3 +19,7 @@ export { startProxy, profileFor, type ProxyOptions, type ProxyHost, type Running
 export { UsageObserver, type ProxyProfile, type ObservedUsage } from './proxy/usage-observer';
 export { renderMachineStatus } from './status';
 export { runConformance, type ConformanceResult } from './conformance';
+export { writeOverride, readOverride, consumeOverride, clearOverride, OVERRIDE_WINDOW_MS, type Override } from './override';
+export { install, health, configPath, type InstallHost, type InstallResult, type HostHealth } from './install';
+export { readHookSessions, renderHostHealth } from './status';
+export { findingSignature, inflateHookSession, type PersistedSession } from './hook/pre-tool-use';

package/dist/src/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsageObserver = exports.profileFor = exports.startProxy = exports.CODEX_FORBIDDEN_FIELDS = exports.readCodexTranscriptUsage = exports.parseCodexTranscript = exports.codexHooksSnippet = exports.handleCodexHook = exports.cursorHooksSnippet = exports.handleCursorHook = exports.BurnStopError = exports.createRawApiGuard = exports.sha256 = exports.canonical = exports.receiptDigest = exports.verifyReceipt = exports.ReceiptSigner = exports.mergeCapabilities = exports.Gateway = exports.settingsSnippet = exports.loadPolicy = exports.refreshSession = exports.handlePreToolUse = exports.calibrate = exports.renderStop = exports.renderReplay = exports.discoverTranscripts = exports.replayEvents = exports.replaySession = exports.replayAll = exports.RESERVATION_TTL_MS = exports.Transaction = exports.ReservationStore = exports.cacheReadRatio = exports.medianCompletedMinute = exports.windowSum = exports.newSessionState = exports.applyCorrection = exports.applyEvent = exports.normaliseLine = exports.newCursor = exports.readAll = exports.readIncremental = exports.evaluateLocalCompute = exports.fmt = exports.evaluate = exports.CALL_RESERVATION_TTL_MS = exports.DEFAULT_LOCAL_COMPUTE = exports.DEFAULT_THRESHOLDS = exports.DEFAULT_POLICY = void 0;
-exports.runConformance = exports.renderMachineStatus = void 0;
+exports.inflateHookSession = exports.findingSignature = exports.renderHostHealth = exports.readHookSessions = exports.configPath = exports.health = exports.install = exports.OVERRIDE_WINDOW_MS = exports.clearOverride = exports.consumeOverride = exports.readOverride = exports.writeOverride = exports.runConformance = exports.renderMachineStatus = void 0;
 __exportStar(require("./types"), exports);
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "DEFAULT_POLICY", { enumerable: true, get: function () { return defaults_1.DEFAULT_POLICY; } });
@@ -90,3 +90,19 @@ var status_1 = require("./status");
 Object.defineProperty(exports, "renderMachineStatus", { enumerable: true, get: function () { return status_1.renderMachineStatus; } });
 var conformance_1 = require("./conformance");
 Object.defineProperty(exports, "runConformance", { enumerable: true, get: function () { return conformance_1.runConformance; } });
+var override_1 = require("./override");
+Object.defineProperty(exports, "writeOverride", { enumerable: true, get: function () { return override_1.writeOverride; } });
+Object.defineProperty(exports, "readOverride", { enumerable: true, get: function () { return override_1.readOverride; } });
+Object.defineProperty(exports, "consumeOverride", { enumerable: true, get: function () { return override_1.consumeOverride; } });
+Object.defineProperty(exports, "clearOverride", { enumerable: true, get: function () { return override_1.clearOverride; } });
+Object.defineProperty(exports, "OVERRIDE_WINDOW_MS", { enumerable: true, get: function () { return override_1.OVERRIDE_WINDOW_MS; } });
+var install_1 = require("./install");
+Object.defineProperty(exports, "install", { enumerable: true, get: function () { return install_1.install; } });
+Object.defineProperty(exports, "health", { enumerable: true, get: function () { return install_1.health; } });
+Object.defineProperty(exports, "configPath", { enumerable: true, get: function () { return install_1.configPath; } });
+var status_2 = require("./status");
+Object.defineProperty(exports, "readHookSessions", { enumerable: true, get: function () { return status_2.readHookSessions; } });
+Object.defineProperty(exports, "renderHostHealth", { enumerable: true, get: function () { return status_2.renderHostHealth; } });
+var pre_tool_use_2 = require("./hook/pre-tool-use");
+Object.defineProperty(exports, "findingSignature", { enumerable: true, get: function () { return pre_tool_use_2.findingSignature; } });
+Object.defineProperty(exports, "inflateHookSession", { enumerable: true, get: function () { return pre_tool_use_2.inflateHookSession; } });

package/dist/src/install.d.ts

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

package/dist/src/install.js

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

package/dist/src/override.d.ts

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

package/dist/src/override.js

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

package/dist/src/status.d.ts

@@ -7,5 +7,13 @@
  * middleware and the proxy shows full coverage, because it has it.
  */
 import type { GatewaySessionView } from './gateway';
+import type { HostHealth } from './install';
 import type { ComputeSnapshot } from './state/reservations';
+/**
+ * Claude Code sessions live in the hook's own files (they carry a transcript
+ * cursor the gateway sessions do not). Read them into the same view so the
+ * table shows every host, not just the new ones.
+ */
+export declare function readHookSessions(home: string): GatewaySessionView[];
+export declare function renderHostHealth(hosts: HostHealth[]): string;
 export declare function renderMachineStatus(sessions: GatewaySessionView[], compute: ComputeSnapshot, now?: number): string;

package/dist/src/status.js

@@ -8,19 +8,85 @@
  * middleware and the proxy shows full coverage, because it has it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readHookSessions = readHookSessions;
+exports.renderHostHealth = renderHostHealth;
 exports.renderMachineStatus = renderMachineStatus;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const evaluate_1 = require("./detectors/evaluate");
+const events_1 = require("./events");
+const pre_tool_use_1 = require("./hook/pre-tool-use");
 const LIVE_WINDOW_MS = 30 * 60 * 1000;
+/**
+ * Claude Code sessions live in the hook's own files (they carry a transcript
+ * cursor the gateway sessions do not). Read them into the same view so the
+ * table shows every host, not just the new ones.
+ */
+function readHookSessions(home) {
+    const dir = (0, node_path_1.join)(home, 'sessions');
+    const out = [];
+    let names = [];
+    try {
+        names = (0, node_fs_1.readdirSync)(dir).filter((n) => n.endsWith('.json') && !n.startsWith('gw-'));
+    }
+    catch {
+        return out;
+    }
+    for (const name of names) {
+        try {
+            const raw = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, name), 'utf8'));
+            if (!raw.cursor || !raw.state)
+                continue;
+            const state = (0, pre_tool_use_1.inflateHookSession)(raw);
+            out.push({
+                sessionId: state.sessionId,
+                hosts: ['claude-code'],
+                capabilities: events_1.CAPABILITIES['claude-code'],
+                state,
+                liveSpawns: 0,
+                usage: { authoritative: state.totalTokens > 0 ? 1 : 0, estimated: 0, missing: 0 },
+                decisions: 0,
+                wouldBlock: 0,
+                closedAt: null,
+            });
+        }
+        catch {
+            /* half-written or foreign file: skip */
+        }
+    }
+    return out;
+}
+function renderHostHealth(hosts) {
+    const lines = ['hosts:'];
+    for (const h of hosts) {
+        const name = h.host === 'claude' ? 'claude-code' : h.host;
+        let state;
+        if (!h.installed)
+            state = h.hostPresent ? `not installed  (agentguard-burn init ${h.host} --write)` : 'not present on this machine';
+        else if (!h.commandExists)
+            state = `INSTALLED BUT BROKEN: hook command not found on disk, host will fail open  (re-run: agentguard-burn init ${h.host} --write)`;
+        else
+            state = `installed, hook command ok  (${h.file.replace(process.env.HOME ?? '', '~')})`;
+        lines.push(`  ${name.padEnd(13)} ${state}`);
+        if (h.host === 'codex' && h.installed && h.commandExists) {
+            // Codex requires a one-time trust of each hook source. We cannot see
+            // whether it has been granted, and an untrusted hook stalls codex exec
+            // the first time it would fire, so say it every time.
+            lines.push(`  ${''.padEnd(13)} trust it once: open codex, run /hooks, trust the AgentGuard hook. Until then codex exec stalls when a spawn would be gated.`);
+        }
+    }
+    return lines.join('\n');
+}
 function renderMachineStatus(sessions, compute, now = Date.now()) {
-    const live = sessions.filter((s) => s.closedAt === null && now - s.state.lastEventAt <= LIVE_WINDOW_MS);
+    const live = sessions.filter((s) => s.closedAt === null && now - s.state.lastEventAt <= LIVE_WINDOW_MS).sort((a, b) => b.state.lastEventAt - a.state.lastEventAt);
     const totalTokens = live.reduce((n, s) => n + s.state.totalTokens, 0);
     const lines = [];
-    lines.push(`cross-tool sessions: ${live.length} live · ${(0, evaluate_1.fmt)(totalTokens)} tokens · ${compute.inFlight} model call(s) in flight · ${Math.round(compute.occupiedMs / 1000)}s occupied in last ${Math.round(compute.windowMs / 60000)} min`);
+    lines.push(`sessions: ${live.length} active in the last 30 min · ${(0, evaluate_1.fmt)(totalTokens)} tokens · ${compute.inFlight} model call(s) in flight · ${Math.round(compute.occupiedMs / 1000)}s occupied in last ${Math.round(compute.windowMs / 60000)} min`);
     if (live.length === 0) {
-        lines.push('  (none in the last 30 minutes; Claude Code sessions are tracked by the hook and listed by `replay`)');
+        lines.push('  (none)');
         return lines.join('\n');
     }
-    lines.push('  ' + pad('HOST(S)', 22) + pad('SESSION', 20) + pad('TOKENS', 9) + pad('SPAWNS', 8) + pad('DEPTH', 7) + pad('LIVE', 6) + 'COVERAGE');
+    lines.push('  ' + pad('HOST(S)', 22) + pad('SESSION', 20) + pad('TOKENS', 9) + pad('SPAWNS', 8) + pad('DEPTH', 7) + pad('LAST', 8) + 'COVERAGE');
     for (const s of live) {
         lines.push('  ' +
             pad(s.hosts.join('+'), 22) +
@@ -28,11 +94,15 @@ function renderMachineStatus(sessions, compute, now = Date.now()) {
             pad((0, evaluate_1.fmt)(s.state.totalTokens), 9) +
             pad(String(s.state.spawnCount), 8) +
             pad(String(s.state.maxDepth), 7) +
-            pad(String(s.liveSpawns), 6) +
+            pad(ago(now - s.state.lastEventAt), 8) +
             coverageLine(s));
     }
     return lines.join('\n');
 }
+function ago(ms) {
+    const m = Math.floor(ms / 60000);
+    return m < 1 ? 'now' : `${m}m ago`;
+}
 function coverageLine(s) {
     const usage = s.usage.missing > 0 ? `usage:partial(${s.usage.missing} missing)` : s.usage.authoritative > 0 ? 'usage:auth' : s.usage.estimated > 0 ? 'usage:est' : `usage:${short(s.capabilities.usage)}`;
     return `spawns:${short(s.capabilities.spawns)} depth:${short(s.capabilities.depth)} ${usage}`;

package/fixtures/codex-0.151.0-pretooluse.json

@@ -0,0 +1,49 @@
+{
+  "captured_from": "codex-cli 0.151.0, 2026-09-03, codex exec with -c hooks.PreToolUse inline; --dangerously-bypass-hook-trust",
+  "payloads": [
+    {
+      "session_id": "01a069d3-5fc8-7470-8c95-1b42e7206746",
+      "turn_id": "01a069d3-6018-7523-a26e-eea10123676c",
+      "transcript_path": "/Users/example/.codex/sessions/2026/09/03/rollout-example.jsonl",
+      "cwd": "/Users/example/project",
+      "hook_event_name": "PreToolUse",
+      "model": "gpt-5.4-mini",
+      "permission_mode": "bypassPermissions",
+      "tool_name": "Bash",
+      "tool_input": {
+        "command": "echo CANARY_OK"
+      },
+      "tool_use_id": "call_NmxrZob0I2KFC8ChNe2PduGX"
+    },
+    {
+      "session_id": "01a069d4-d356-73b3-9440-1c4440319de8",
+      "turn_id": "01a069d4-d3b2-7593-85ec-8a0281f51bf1",
+      "transcript_path": "/Users/example/.codex/sessions/2026/09/03/rollout-example.jsonl",
+      "cwd": "/Users/example/project",
+      "hook_event_name": "PreToolUse",
+      "model": "gpt-5.4-mini",
+      "permission_mode": "bypassPermissions",
+      "tool_name": "spawn_agent",
+      "tool_input": {
+        "message": "<redacted>",
+        "fork_context": "<redacted>"
+      },
+      "tool_use_id": "call_oktUPQ5jcosNPOcGnEaWqRcv"
+    },
+    {
+      "session_id": "01a069d4-d356-73b3-9440-1c4440319de8",
+      "turn_id": "01a069d4-d3b2-7593-85ec-8a0281f51bf1",
+      "transcript_path": "/Users/example/.codex/sessions/2026/09/03/rollout-example.jsonl",
+      "cwd": "/Users/example/project",
+      "hook_event_name": "PreToolUse",
+      "model": "gpt-5.4-mini",
+      "permission_mode": "bypassPermissions",
+      "tool_name": "multi_agent_v1wait_agent",
+      "tool_input": {
+        "targets": "<redacted>",
+        "timeout_ms": "<redacted>"
+      },
+      "tool_use_id": "call_RK95A6i4UUhTigIGXF24gMMO"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentguard-run/burn",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local runaway-agent circuit breaker for AI coding agents and local model runtimes. One policy across Claude Code, Cursor, Codex, Ollama, vLLM, LM Studio and raw orchestrators: detects fan-out storms and sustained token burn, blocks the next spawn, and proves what happened with content-free signed receipts. Nothing leaves the machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist/src",
+    "fixtures",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"