@agentguard-run/burn 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## 0.2.0 (2026-09-03)
+
+The cross-tool layer. One policy, one lock, one receipt across hosts.
+
+### Added
+- Host-neutral `AgentEvent` vocabulary and a `Gateway` that folds events,
+  evaluates the existing detectors and decides, so adapters cannot drift.
+- Raw middleware (`@agentguard-run/burn/middleware`): `beforeSpawn` /
+  `beforeCall` leases with stable IDs. The strongest position: it sees the
+  tree and the request.
+- Loopback reverse proxy (`agentguard-burn proxy`) for Ollama, vLLM, LM
+  Studio and OpenAI-compatible servers. Streams before it inspects, honours
+  backpressure, reads final usage as a side channel, answers the next
+  request with 429 on STOP. Never truncates a stream in flight.
+- Local-compute plane: concurrent in-flight calls and occupied request time,
+  WARN-only by default (4 concurrent). Operators set the STOP for their own
+  hardware.
+- Cursor adapter (beta): `subagentStart` admission with the documented
+  `{ permission, user_message, agent_message }` output; depth derived from
+  the issuing subagent; `failClosed` in the generated snippet.
+- Codex adapter (experimental): `PreToolUse` on `spawn_agent`, host-specific
+  output only. A test forbids `continue`, `stopReason`, `suppressOutput`,
+  `decision` and `reason` by name. Transcript usage is best-effort and
+  marked estimated.
+- Content-free Ed25519 receipts on `node:crypto`, chained per session.
+- Capability-aware `status` across every host, with coverage per plane.
+- `agentguard-burn conformance`: the same storm and the same grind through
+  every adapter, asserting identical boundaries, plus the composite case.
+- Usage is committed by call ID and replaces the reservation under it, in
+  either direction. Middleware and proxy never double count one call.
+
+### Fixed
+- The reservation lock could be torn down by a waiter that judged a
+  previous, already-released instance as dead (TOCTOU under heavy
+  contention). Under 240 concurrent hook processes this admitted 41 to 46
+  spawns against a cap of 40. Lock instances now carry a nonce; reclaims
+  are verified against the instance judged; writes are fenced on the
+  holder's nonce. 192 runs at 240 concurrent processes admit exactly 40.
+- A lock owner record could be read half-written and parsed as "held since
+  1970". The record is now written atomically and malformed records are
+  never trusted.
+- Lock removal was readdir + unlink + rmdir on the live path and could hit a
+  sibling's fresh directory (ENOTEMPTY crash mid-lock). Removal is now
+  rename-then-delete.
+- The signing key is created atomically; concurrent first-run hooks no
+  longer race on `wx`.
+
+### Changed
+- Dropped `@noble/ed25519` (unused, ESM-only). Zero runtime dependencies.
+- `Thresholds.localCompute` added as an optional field; 0.1 policy files
+  load unchanged.
+
+### Unchanged
+- The Claude Code hook, transcript reader, detectors and thresholds. The
+  existing 24 tests pass as they were.
+
+## 0.1.1 (2026-09-03)
+- The artifact: block-digit hero, per-session sparklines with the STOP marked,
+  boxed STOP alarm.
+
+## 0.1.0 (2026-09-03)
+- First publish. Two safety planes fitted on 412 real sessions.

package/README.md

@@ -42,13 +42,122 @@ npx @agentguard-run/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.
 
+## One policy across hosts (0.2.0)
+
+The detectors never learn which host produced an event. Claude Code, Cursor,
+Codex, a local model runtime behind the proxy, and an orchestrator calling
+the middleware all normalise into the same event stream, share one
+machine-wide reservation lock, and sign the same receipt. The same failure,
+through every door, stops at the same step: `agentguard-burn conformance`
+replays a 42-spawn storm and a 250M-token-per-call grind through each adapter
+and asserts fan-out WARN at 24, STOP at 41, sustained WARN at 3.5B, STOP at
+5B.
+
+What each host can actually see is stated, not implied:
+
+| Host | Spawns | Depth | Usage | How |
+|---|---|---|---|---|
+| Claude Code | authoritative | authoritative | authoritative | PreToolUse hook + transcript (unchanged from 0.1) |
+| Raw middleware | authoritative | authoritative | authoritative | `beforeSpawn` / `beforeCall` leases in your orchestrator |
+| 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 |
+
+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.
+
+The full claim, "40 spawns, depth 2, 5B tokens, enforced identically", is true
+for a deployment that feeds both a topology source and a usage source into one
+session ID: raw middleware plus the proxy, for instance. A proxy alone sees
+tokens and no tree. A Cursor hook alone sees the tree and no tokens. The
+composite conformance check proves the combined case: candidate spawn 41 sees
+both planes in its findings.
+
+### Local models: the compute plane
+
+Token dollars are close to meaningless when the GPU is yours. What runs away
+is the machine: concurrency and occupied request time. The proxy tracks both
+and warns at 4 concurrent calls by default. No universal STOP ships for
+hardware we cannot see; set `localCompute.stopConcurrent` or
+`stopOccupiedMs` in `burn-policy.json` for your server. Elapsed request time
+includes queueing and transport, so it is called occupied time, never GPU
+utilisation.
+
+```
+agentguard-burn proxy --upstream http://127.0.0.1:11434 --host ollama
+# point the agent at http://127.0.0.1:18080 and send x-agentguard-session: <id>
+```
+
+Loopback only, both sides, by default. Every upstream chunk is written to the
+client before it is inspected; the observer is a side channel, never a data
+path. A STOP answers the *next* request with 429 and the alarm box. It never
+cuts a stream that is already flowing, and it never kills a running agent.
+Blocking is not killing.
+
+### Raw middleware
+
+```ts
+import { createRawApiGuard } from '@agentguard-run/burn/middleware';
+const burn = createRawApiGuard({ sessionId: 'nightly-refactor-17' });
+
+const spawn = burn.beforeSpawn({ parentDepth: 0 });
+spawn.throwIfBlocked();
+spawn.started();
+try { await worker() } finally { spawn.finished() }
+
+const call = burn.beforeCall({ estimatedTokens: 120_000 });
+call.throwIfBlocked();
+try {
+  const res = await client.chat({ ..., headers: call.headers });   // proxy correlates by call id
+  call.complete({ tokens: res.usage.total_tokens });
+} catch (e) { call.fail(); throw e }
+```
+
+Usage is committed by call ID and *replaces* what was reserved under it.
+When middleware estimated 120K and the proxy later saw 87K for the same call,
+the session moves by 87K, not 207K.
+
+### Cursor and Codex
+
+```
+agentguard-burn init cursor    # ~/.cursor/hooks.json snippet, failClosed on
+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.
+
+### Receipts
+
+Every spawn decision, and every model call that is not OK, is signed with a
+local Ed25519 key (Node built-ins, key generated on first use, 0600) and
+chained to the previous receipt for the session. A receipt carries the host,
+the coverage, the counts, the verdict, the policy digest and a hash of the
+session ID. It carries no prompt, completion, path, or tool input. It can
+leave the machine when a transcript never can.
+
 ## The concurrency guarantee
 
 Ten parallel `Agent` calls launch ten hook processes that all read the same
 transcript and all see the same count. A naive cap is cosmetic during exactly
 the burst it exists for. Spawns are admitted through an atomic, cross-process
 reservation under a machine-wide lock; the test suite launches 60 real OS
-processes against a cap of 40 and asserts exactly 40 are admitted.
+processes against a cap of 40 and asserts exactly 40 are admitted, through
+the Claude hook and again through the Cursor hook.
+
+0.2.0 fixed the lock itself. Under 240 concurrent hook processes the 0.1
+lock could tear down a live sibling's lock (a waiter judged "owner is dead"
+about an instance that had already been released and replaced) and admit
+41 to 46. Lock instances now carry a nonce; a reclaim only counts if it
+grabbed the instance it judged, and every write is fenced on the holder's
+own nonce still being on the path. 192 runs at 240 concurrent processes:
+exactly 40, every time.
 
 Single-machine by design. Two laptops on one account do not share state, and
 that is stated rather than hidden.

package/dist/src/adapters/codex.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Codex CLI hooks adapter.
+ *
+ * Codex gates tool calls through PreToolUse, and `spawn_agent` matches as
+ * `Agent` in the hook matcher, so the admission point is structurally the
+ * same as Claude Code's. The output schema is not: Codex accepts the nested
+ * hookSpecificOutput object and `systemMessage`, and FAILS on the Claude
+ * common fields `continue`, `stopReason` and `suppressOutput`. A failed hook
+ * is a fail-open hook, so this renderer never emits them. There is a test
+ * that forbids them by name.
+ *
+ * Verified against the Codex hooks docs (learn.chatgpt.com/docs/hooks,
+ * 2026-09-03):
+ *   input   session_id, transcript_path, cwd, hook_event_name, model,
+ *           permission_mode, turn_id, tool_name, tool_use_id, tool_input
+ *   output  { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *             permissionDecision: "deny", permissionDecisionReason } }
+ *   config  ~/.codex/hooks.json, matcher regex on tool name; exit 2 = deny
+ *
+ * `transcript_path` is a locator, not a schema. Usage read from it is
+ * best-effort and marked `estimated`; unknown records lower coverage instead
+ * of becoming a silent zero. That is the honest version, and it is why Codex
+ * ships as experimental until an installed-version deny canary has passed.
+ */
+import { type ModelUsageObserved } from '../events';
+import type { Gateway } from '../gateway';
+export interface CodexHookOutput {
+    systemMessage?: string;
+    hookSpecificOutput?: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow' | 'deny';
+        permissionDecisionReason?: string;
+    };
+}
+/** Fields this renderer must never emit. Codex rejects the whole object if they appear. */
+export declare const CODEX_FORBIDDEN_FIELDS: readonly ["continue", "stopReason", "suppressOutput", "decision", "reason"];
+export declare function handleCodexHook(raw: unknown, gateway: Gateway, now?: number): CodexHookOutput;
+/**
+ * Pull usage records out of whatever the Codex transcript turns out to be.
+ * Accepts the common shapes (`usage.input_tokens`, `usage.prompt_tokens`,
+ * nested under `response` or `message`). Event IDs are content digests, so
+ * re-reading the file on every hook call is idempotent at the gateway.
+ */
+export declare function readCodexTranscriptUsage(path: string, sessionId: string, now: number): ModelUsageObserved[];
+export declare function parseCodexTranscript(text: string, sessionId: string, now: number): ModelUsageObserved[];
+/** The ~/.codex/hooks.json fragment. spawn_agent matches as Agent. */
+export declare function codexHooksSnippet(command: string): Record<string, unknown>;
+export declare const CODEX_SPAWN_TOOLS: Set<string>;

package/dist/src/adapters/codex.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Codex CLI hooks adapter.
+ *
+ * Codex gates tool calls through PreToolUse, and `spawn_agent` matches as
+ * `Agent` in the hook matcher, so the admission point is structurally the
+ * same as Claude Code's. The output schema is not: Codex accepts the nested
+ * hookSpecificOutput object and `systemMessage`, and FAILS on the Claude
+ * common fields `continue`, `stopReason` and `suppressOutput`. A failed hook
+ * is a fail-open hook, so this renderer never emits them. There is a test
+ * that forbids them by name.
+ *
+ * Verified against the Codex hooks docs (learn.chatgpt.com/docs/hooks,
+ * 2026-09-03):
+ *   input   session_id, transcript_path, cwd, hook_event_name, model,
+ *           permission_mode, turn_id, tool_name, tool_use_id, tool_input
+ *   output  { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *             permissionDecision: "deny", permissionDecisionReason } }
+ *   config  ~/.codex/hooks.json, matcher regex on tool name; exit 2 = deny
+ *
+ * `transcript_path` is a locator, not a schema. Usage read from it is
+ * best-effort and marked `estimated`; unknown records lower coverage instead
+ * of becoming a silent zero. That is the honest version, and it is why Codex
+ * ships as experimental until an installed-version deny canary has passed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_SPAWN_TOOLS = exports.CODEX_FORBIDDEN_FIELDS = void 0;
+exports.handleCodexHook = handleCodexHook;
+exports.readCodexTranscriptUsage = readCodexTranscriptUsage;
+exports.parseCodexTranscript = parseCodexTranscript;
+exports.codexHooksSnippet = codexHooksSnippet;
+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");
+/** 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 input = parse(raw);
+    if (!input)
+        return {};
+    // Usage from the transcript, if it is readable. Best effort, estimated.
+    if (input.transcriptPath) {
+        const events = readCodexTranscriptUsage(input.transcriptPath, input.sessionId, now);
+        if (events.length)
+            quietly(() => gateway.observe(events));
+    }
+    if (input.event !== 'PreToolUse' || !SPAWN_TOOLS.has(input.toolName))
+        return {};
+    const spawnId = input.toolUseId ?? `${input.sessionId}:${now}`;
+    const decision = gateway.beforeSpawn({
+        schemaVersion: 1,
+        kind: 'spawn_requested',
+        eventId: `codex:${spawnId}`,
+        host: HOST,
+        sessionId: input.sessionId,
+        at: now,
+        spawnId,
+        // Codex PreToolUse does not say which agent is calling. Depth is estimated.
+        proposedDepth: 1,
+        attribution: 'high',
+    });
+    if (decision.blocked) {
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: (0, render_1.renderStop)(decision.report, { colour: false }),
+            },
+        };
+    }
+    // Never crash after deciding: a crashed hook is a fail-open on most hosts.
+    // 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') {
+        return {
+            systemMessage: `AgentGuard ${decision.verdict}${decision.mode === 'shadow' && decision.wouldBlock ? ' (shadow: would have blocked)' : ''}: ${decision.report.findings[0]?.summary ?? ''}`,
+        };
+    }
+    return {};
+}
+function quietly(fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        process.stderr.write(`agentguard-burn: could not record observation: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function parse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const v = value;
+    const str = (k) => (typeof v[k] === 'string' && v[k].length > 0 ? v[k] : undefined);
+    const session = str('session_id');
+    return {
+        event: str('hook_event_name') ?? '',
+        sessionId: session && (0, events_1.isValidSessionId)(session) ? session : 'codex:unknown',
+        toolName: str('tool_name') ?? '',
+        toolUseId: str('tool_use_id'),
+        transcriptPath: str('transcript_path'),
+    };
+}
+// ---- transcript usage (best effort) ---------------------------------------
+/**
+ * Pull usage records out of whatever the Codex transcript turns out to be.
+ * Accepts the common shapes (`usage.input_tokens`, `usage.prompt_tokens`,
+ * nested under `response` or `message`). Event IDs are content digests, so
+ * re-reading the file on every hook call is idempotent at the gateway.
+ */
+function readCodexTranscriptUsage(path, sessionId, now) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    return parseCodexTranscript(text, sessionId, now);
+}
+function parseCodexTranscript(text, sessionId, now) {
+    const out = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const usage = extractUsage(rec);
+        if (!usage)
+            continue;
+        // Digest of the line's position and counts, never its content.
+        const digest = (0, node_crypto_1.createHash)('sha256').update(`${sessionId}:${i}:${usage.tokens}:${usage.cacheRead}`).digest('hex').slice(0, 24);
+        out.push({
+            schemaVersion: 1,
+            kind: 'model_usage',
+            eventId: `codex:usage:${digest}`,
+            host: HOST,
+            sessionId,
+            at: usage.at ?? now,
+            tokens: usage.tokens,
+            cacheRead: usage.cacheRead,
+            usageCoverage: 'estimated',
+        });
+    }
+    return out;
+}
+function extractUsage(rec) {
+    const num = (...paths) => {
+        for (const p of paths) {
+            const v = walk(rec, p);
+            if (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+                return Math.trunc(v);
+        }
+        return undefined;
+    };
+    const input = num(['usage', 'input_tokens'], ['usage', 'prompt_tokens'], ['response', 'usage', 'input_tokens'], ['response', 'usage', 'prompt_tokens'], ['message', 'usage', 'input_tokens'], ['message', 'usage', 'prompt_tokens'], ['token_usage', 'input_tokens']);
+    const output = num(['usage', 'output_tokens'], ['usage', 'completion_tokens'], ['response', 'usage', 'output_tokens'], ['response', 'usage', 'completion_tokens'], ['message', 'usage', 'output_tokens'], ['message', 'usage', 'completion_tokens'], ['token_usage', 'output_tokens']);
+    const total = num(['usage', 'total_tokens'], ['response', 'usage', 'total_tokens'], ['message', 'usage', 'total_tokens'], ['token_usage', 'total_tokens']);
+    const cached = num(['usage', 'cache_read_input_tokens'], ['usage', 'input_tokens_details', 'cached_tokens'], ['response', 'usage', 'input_tokens_details', 'cached_tokens'], ['token_usage', 'cached_input_tokens']);
+    if (input === undefined && output === undefined && total === undefined)
+        return null;
+    const tokens = Math.max(total ?? 0, (input ?? 0) + (output ?? 0) + (cached ?? 0));
+    const tsRaw = walk(rec, ['timestamp']) ?? walk(rec, ['created_at']);
+    const at = typeof tsRaw === 'string' ? Date.parse(tsRaw) : typeof tsRaw === 'number' ? tsRaw : NaN;
+    return { tokens, cacheRead: cached ?? 0, at: Number.isFinite(at) ? at : undefined };
+}
+function walk(value, path) {
+    let cur = value;
+    for (const k of path) {
+        if (!cur || typeof cur !== 'object' || Array.isArray(cur))
+            return undefined;
+        cur = cur[k];
+    }
+    return cur;
+}
+/** The ~/.codex/hooks.json fragment. spawn_agent matches as Agent. */
+function codexHooksSnippet(command) {
+    return {
+        hooks: {
+            PreToolUse: [{ matcher: '^(Agent|spawn_agent)$', hooks: [{ type: 'command', command, timeout: 5 }] }],
+        },
+    };
+}
+exports.CODEX_SPAWN_TOOLS = SPAWN_TOOLS;

package/dist/src/adapters/cursor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cursor hooks adapter.
+ *
+ * Cursor exposes `subagentStart` as a native, prospective admission point and
+ * `subagentStop` for reconciliation. That is a stronger spawn signal than a
+ * transcript: the host names the subagent and its parent conversation. What
+ * Cursor never exposes is hosted-model token usage, so usage coverage for a
+ * pure Cursor session is `missing` and status says so.
+ *
+ * Verified against cursor.com/docs/agent/hooks (2026-09-03):
+ *   input   conversation_id, hook_event_name, subagent_id, subagent_type,
+ *           parent_conversation_id, tool_call_id, is_parallel_worker
+ *   output  { "permission": "allow" | "deny", "user_message", "agent_message" }
+ *   config  ~/.cursor/hooks.json  { version: 1, hooks: { subagentStart: [...] } }
+ *           "failClosed": true makes a crashed or timed-out hook deny.
+ *
+ * Cursor's own hooks can deny a subagent. The value here is not the deny; it
+ * is that the deny follows the same policy, writes the same receipt and
+ * shares the same machine-wide reservation as every other host.
+ */
+import type { Gateway } from '../gateway';
+export interface CursorHookOutput {
+    permission?: 'allow' | 'deny';
+    user_message?: string;
+    agent_message?: string;
+}
+/**
+ * Handle one hook invocation. Unknown events allow. Returns the object to
+ * print on stdout; the CLI wraps it. Never throws: Cursor treats invalid
+ * output as fail-open unless failClosed is set, so a crash here would be a
+ * silent allow with no receipt.
+ */
+export declare function handleCursorHook(raw: unknown, gateway: Gateway, now?: number): CursorHookOutput;
+/** The ~/.cursor/hooks.json fragment. failClosed is on: a dead hook denies. */
+export declare function cursorHooksSnippet(command: string): Record<string, unknown>;

package/dist/src/adapters/cursor.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Cursor hooks adapter.
+ *
+ * Cursor exposes `subagentStart` as a native, prospective admission point and
+ * `subagentStop` for reconciliation. That is a stronger spawn signal than a
+ * transcript: the host names the subagent and its parent conversation. What
+ * Cursor never exposes is hosted-model token usage, so usage coverage for a
+ * pure Cursor session is `missing` and status says so.
+ *
+ * Verified against cursor.com/docs/agent/hooks (2026-09-03):
+ *   input   conversation_id, hook_event_name, subagent_id, subagent_type,
+ *           parent_conversation_id, tool_call_id, is_parallel_worker
+ *   output  { "permission": "allow" | "deny", "user_message", "agent_message" }
+ *   config  ~/.cursor/hooks.json  { version: 1, hooks: { subagentStart: [...] } }
+ *           "failClosed": true makes a crashed or timed-out hook deny.
+ *
+ * Cursor's own hooks can deny a subagent. The value here is not the deny; it
+ * is that the deny follows the same policy, writes the same receipt and
+ * shares the same machine-wide reservation as every other host.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCursorHook = handleCursorHook;
+exports.cursorHooksSnippet = cursorHooksSnippet;
+const events_1 = require("../events");
+const render_1 = require("../replay/render");
+const HOST = 'cursor';
+/**
+ * Handle one hook invocation. Unknown events allow. Returns the object to
+ * print on stdout; the CLI wraps it. Never throws: Cursor treats invalid
+ * output as fail-open unless failClosed is set, so a crash here would be a
+ * silent allow with no receipt.
+ */
+function handleCursorHook(raw, gateway, now = Date.now()) {
+    const input = parse(raw);
+    if (!input)
+        return {};
+    const at = input.at ?? now;
+    if (input.event === 'subagentStart') {
+        const spawnId = input.subagentId ?? input.toolCallId ?? `${input.sessionId}:${at}`;
+        const decision = gateway.beforeSpawn({
+            schemaVersion: 1,
+            kind: 'spawn_requested',
+            eventId: `cursor:${spawnId}`,
+            host: HOST,
+            sessionId: input.sessionId,
+            at,
+            spawnId,
+            // If the issuing conversation is itself a subagent we admitted, the
+            // child sits one level below it. Otherwise it is a root child.
+            issuerId: input.parentConversationId,
+            attribution: 'high',
+        });
+        if (decision.blocked) {
+            return {
+                permission: 'deny',
+                user_message: (0, render_1.renderStop)(decision.report, { colour: false }),
+                agent_message: `AgentGuard STOP: ${decision.report.findings[0]?.summary ?? 'policy ceiling reached'} Do not start another subagent.`,
+            };
+        }
+        // Admitted: the subagent will run. Record it so depth and count are live.
+        // If the record cannot be taken (lock contention), the reservation simply
+        // stays pending until its TTL: the conservative direction. Never crash a
+        // 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)) {
+            return {
+                permission: 'allow',
+                agent_message: `AgentGuard ${decision.verdict}${decision.mode === 'shadow' && decision.wouldBlock ? ' (shadow: would have blocked)' : ''}: ${decision.report.findings[0]?.summary ?? ''}`,
+            };
+        }
+        return { permission: 'allow' };
+    }
+    if (input.event === 'subagentStop') {
+        const spawnId = input.subagentId ?? input.toolCallId;
+        if (spawnId) {
+            quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'spawn_finished', eventId: `cursor:stop:${spawnId}`, host: HOST, sessionId: input.sessionId, at, spawnId }]));
+        }
+        return {};
+    }
+    if (input.event === 'sessionEnd') {
+        quietly(() => gateway.observe([{ schemaVersion: 1, kind: 'session_closed', eventId: `cursor:end:${input.sessionId}:${at}`, host: HOST, sessionId: input.sessionId, at }]));
+        return {};
+    }
+    return {};
+}
+function quietly(fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        process.stderr.write(`agentguard-burn: could not record observation: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
+function parse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const v = value;
+    const str = (...keys) => {
+        for (const k of keys) {
+            const x = v[k];
+            if (typeof x === 'string' && x.length > 0)
+                return x;
+        }
+        return undefined;
+    };
+    const name = (str('hook_event_name') ?? '').toLowerCase();
+    const event = name === 'subagentstart' ? 'subagentStart' : name === 'subagentstop' ? 'subagentStop' : name === 'sessionend' ? 'sessionEnd' : 'other';
+    const conversation = str('conversation_id');
+    const sessionId = conversation && (0, events_1.isValidSessionId)(conversation) ? conversation : 'cursor:unknown';
+    const ts = v.timestamp_ms ?? v.occurred_at_ms;
+    return {
+        event,
+        sessionId,
+        subagentId: str('subagent_id'),
+        parentConversationId: str('parent_conversation_id'),
+        toolCallId: str('tool_call_id'),
+        at: typeof ts === 'number' && Number.isFinite(ts) ? ts : undefined,
+    };
+}
+/** The ~/.cursor/hooks.json fragment. failClosed is on: a dead hook denies. */
+function cursorHooksSnippet(command) {
+    return {
+        version: 1,
+        hooks: {
+            subagentStart: [{ command, timeout: 5, failClosed: true }],
+            subagentStop: [{ command, timeout: 5 }],
+            sessionEnd: [{ command, timeout: 3 }],
+        },
+    };
+}

package/dist/src/adapters/raw-api.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Raw orchestrator middleware.
+ *
+ * The strongest position of the adapter shapes, because the orchestrator
+ * knows things no host exposes: stable spawn IDs, the parent of each child,
+ * and the request before it leaves the process. That is why this adapter is
+ * the one that makes the full "40 spawns, depth 2, 5B tokens" claim true for
+ * an open-weights agent. A proxy alone sees tokens and no tree; a hook alone
+ * sees the tree and no tokens; this sees both.
+ *
+ *   const burn = createRawApiGuard({ sessionId: 'nightly-refactor-17' });
+ *
+ *   const spawn = burn.beforeSpawn({ parentDepth: 0 });
+ *   spawn.throwIfBlocked();
+ *   spawn.started();
+ *   try { await worker() } finally { spawn.finished() }
+ *
+ *   const call = burn.beforeCall({ estimatedTokens: 120_000 });
+ *   call.throwIfBlocked();
+ *   try {
+ *     const res = await client.chat({ ..., headers: call.headers });
+ *     call.complete({ tokens: res.usage.total_tokens });
+ *   } catch (e) { call.fail(); throw e }
+ *
+ * A model call reserves an estimate and then commits the real number under
+ * the same call ID, so a proxy observing the same request (via call.headers)
+ * supersedes rather than duplicates it.
+ */
+import { Gateway, type Decision } from '../gateway';
+export declare class BurnStopError extends Error {
+    readonly decision: Decision;
+    constructor(decision: Decision);
+}
+export interface RawGuardOptions {
+    sessionId: string;
+    /** Defaults to $AGENTGUARD_HOME or ~/.agentguard. */
+    home?: string;
+    /** Skip receipt signing (tests, throwaway scripts). */
+    sign?: boolean;
+    now?: () => number;
+}
+export declare function createRawApiGuard(opts: RawGuardOptions): {
+    sessionId: string;
+    gateway: Gateway;
+    beforeSpawn(args?: {
+        parentDepth: number;
+        spawnId?: string;
+    }): {
+        spawnId: string;
+        depth: number;
+        decision: Decision;
+        readonly blocked: boolean;
+        throwIfBlocked(): void;
+        started(): void;
+        finished(): void;
+    };
+    beforeCall(args?: {
+        estimatedTokens?: number;
+        callId?: string;
+    }): {
+        callId: string;
+        decision: Decision;
+        /** Attach to the outbound request so a local proxy correlates it. */
+        headers: Record<string, string>;
+        readonly blocked: boolean;
+        throwIfBlocked(): void;
+        complete(usage: {
+            tokens: number;
+            cacheRead?: number;
+        }): void;
+        fail(): void;
+    };
+    /** Current state without deciding anything. */
+    status(): import("../gateway").GatewaySessionView | null;
+};
+export type RawApiGuard = ReturnType<typeof createRawApiGuard>;