@agentguard-run/burn 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## 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.
+
+### 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

@@ -33,14 +33,144 @@ 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)
+
+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 (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.
+
+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.
+
+**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. After
+`init codex --write`, trust the hook once with `/hooks` inside Codex.
+
+**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
+
+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
 
@@ -48,7 +178,16 @@ 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,197 @@
+"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.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 ?? ''}`,
+        };
+    }
+    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>;