@raishin/vanguard-frontier-agentic 3.14.0 → 3.16.0

package/mods/blast-radius-guard/lib/runtime.mjs

@@ -0,0 +1,140 @@
+// Command-hook runtime for the mods under mods/. scripts/generate-mods.mjs copies this file
+// byte-for-byte to mods/<id>/lib/runtime.mjs, so edit it here and run `npm run mods:write`.
+//
+// A mod's bin/hook.mjs hands its handlers to runHook, which reads the harness payload from
+// stdin and renders the handler's decision in that harness's protocol. It writes no files
+// and reads no environment; Claude Code's native runtime never imports it.
+import { readFileSync } from 'node:fs'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+const HARNESSES = new Set(['claude-code', 'kiro', 'codex'])
+const EVENTS = new Set(['PreToolUse', 'PostToolUse', 'SessionStart'])
+const DECISIONS = new Set(['allow', 'deny', 'ask', 'replace', 'context'])
+
+const nodeIo = () => ({
+  argv: process.argv.slice(2),
+  readStdin: () => readFileSync(0, 'utf8'),
+  out: (s) => process.stdout.write(s),
+  err: (s) => process.stderr.write(s),
+})
+
+const message = (err) => (err instanceof Error ? err.message : String(err))
+
+// JSON.parse errors quote the text they failed on, and stdin can carry a tool's input or
+// output: report the failure without echoing any of it.
+function parseStdin(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error('stdin is not valid JSON')
+  }
+}
+
+export function parseArgs(argv) {
+  const usage = 'usage: hook.mjs --harness <claude-code|kiro|codex> --event <PreToolUse|PostToolUse|SessionStart>'
+  if (argv.length !== 4) throw new Error(usage)
+  const args = {}
+  for (let i = 0; i < 4; i += 2) {
+    const key = { '--harness': 'harness', '--event': 'event' }[argv[i]]
+    if (!key || key in args) throw new Error(usage)
+    args[key] = argv[i + 1]
+  }
+  if (!HARNESSES.has(args.harness)) throw new Error(`unknown harness ${args.harness}; ${usage}`)
+  if (!EVENTS.has(args.event)) throw new Error(`unknown event ${args.event}; ${usage}`)
+  return args
+}
+
+// Where an observer writes `path`. A relative path resolves against the project root when
+// the hook runs from its install location <root>/.<harness dir>/vanguard-mods/<id>/bin/,
+// otherwise against the working directory. Never CLAUDE_PROJECT_DIR: mods read only their
+// own VANGUARD_<ID>_* variables.
+export function projectPath(path, harness, binDir) {
+  if (isAbsolute(path)) return path
+  const parts = resolve(binDir).split(sep)
+  const n = parts.length
+  const dir = { 'claude-code': '.claude', kiro: '.kiro', codex: '.codex' }[harness]
+  const installed = n >= 5 && parts[n - 1] === 'bin' && parts[n - 3] === 'vanguard-mods' && parts[n - 4] === dir
+  return resolve(installed ? parts.slice(0, n - 4).join(sep) || sep : process.cwd(), path)
+}
+
+// Rejects decisions the harness cannot express, so a handler bug surfaces as an error
+// instead of a silently dropped verdict.
+function normalize(d, { harness, event }) {
+  if (d === undefined) return { decision: 'allow', log: [] }
+  if (d === null || typeof d !== 'object' || !DECISIONS.has(d.decision)) {
+    throw new Error(`handler returned an invalid decision: ${JSON.stringify(d)}`)
+  }
+  const log = d.log ?? []
+  if (!Array.isArray(log) || !log.every((l) => typeof l === 'string')) throw new Error('decision log must be a string array')
+  const needs = { deny: 'reason', ask: 'reason', context: 'text' }[d.decision]
+  if (needs && (typeof d[needs] !== 'string' || d[needs] === '')) throw new Error(`${d.decision} needs a ${needs}`)
+  if ((d.decision === 'deny' || d.decision === 'ask') && event !== 'PreToolUse') {
+    throw new Error(`${d.decision} is only valid for PreToolUse, not ${event}`)
+  }
+  if (d.decision === 'replace' && (harness !== 'claude-code' || event !== 'PostToolUse')) {
+    throw new Error(`replace is only valid for claude-code PostToolUse, not ${harness} ${event}`)
+  }
+  return { ...d, log }
+}
+
+function render(d, { harness, event }, io) {
+  const json = (hookSpecificOutput) => io.out(JSON.stringify({ hookSpecificOutput: { hookEventName: event, ...hookSpecificOutput } }) + '\n')
+  for (const line of d.log) io.err(line + '\n')
+  switch (d.decision) {
+    case 'allow':
+      return 0
+    case 'deny':
+    case 'ask':
+      if (harness === 'claude-code') {
+        json({ permissionDecision: d.decision, permissionDecisionReason: d.reason })
+        return 0
+      }
+      // Kiro and Codex have no confirmation step; exit 2 blocks the call in both.
+      io.err(d.decision === 'ask' ? `${d.reason} (confirmation unsupported on ${harness}; denied)\n` : `${d.reason}\n`)
+      return 2
+    case 'replace':
+      json({ updatedToolOutput: d.output })
+      return 0
+    case 'context':
+      if (harness === 'kiro') io.err(d.text + '\n')
+      else json({ additionalContext: d.text })
+      return 0
+  }
+}
+
+// Runs one hook invocation and returns the exit code; bin/hook.mjs sets process.exitCode
+// with it rather than calling process.exit, so buffered stdout is never cut short.
+//
+// - Bad arguments, or an event this mod has no handler for: exit 2, which blocks a
+//   PreToolUse call in every harness (a broken install must not allow silently).
+// - Invalid stdin or a throwing handler: `onError(err, payload, ctx)` supplies the decision
+//   (guards deny, the redactor withholds). Without onError: stderr and exit 1, which is
+//   loud but does not block.
+// - An onError that throws or returns an invalid decision: exit 2.
+export async function runHook({ name, handlers, onError }, io = nodeIo()) {
+  let ctx
+  try {
+    ctx = parseArgs(io.argv)
+    if (!Object.hasOwn(handlers, ctx.event)) throw new Error(`no handler for ${ctx.event}`)
+  } catch (err) {
+    io.err(`${name}: ${message(err)}\n`)
+    return 2
+  }
+  let payload
+  let decision
+  try {
+    payload = parseStdin(io.readStdin())
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('stdin is not a JSON object')
+    decision = normalize(await handlers[ctx.event](payload, ctx), ctx)
+  } catch (err) {
+    io.err(`${name}: ${message(err)}\n`)
+    if (typeof onError !== 'function') return 1
+    try {
+      decision = normalize(await onError(err, payload, ctx), ctx)
+    } catch (err2) {
+      io.err(`${name}: error handler failed: ${message(err2)}\n`)
+      return 2
+    }
+  }
+  return render(decision, ctx, io)
+}

package/mods/blast-radius-guard/mod.toml

@@ -0,0 +1,34 @@
+[mod]
+id = "blast-radius-guard"
+name = "Blast Radius Guard"
+description = "Asks before, or blocks, destructive shell commands and writes to system paths."
+version = "1.0.0"
+reach_level = 0
+events = ["PreToolUse"]
+
+[footprint]
+env_reads = ["VANGUARD_BLAST_RADIUS_GUARD_MODE", "VANGUARD_BLAST_RADIUS_GUARD_PATTERNS"]
+file_writes = []
+spawns = []
+egress_hosts = []
+
+[harnesses.claude-code]
+supported = true
+surfaces = ["native", "classic"]
+events = ["PreToolUse"]
+
+[harnesses.kiro]
+supported = true
+requires = ["node"]
+events = ["PreToolUse"]
+
+[harnesses.kiro.degraded]
+PreToolUse = "Kiro documents no confirmation protocol or stdin field names; the whole payload is scanned, the system-path rule applies to the path keys whatever the tool, and confirm mode denies."
+
+[harnesses.codex]
+supported = true
+requires = ["node"]
+events = ["PreToolUse"]
+
+[harnesses.codex.degraded]
+PreToolUse = "Codex rejects ask; confirm mode denies with a reason."

package/mods/blast-radius-guard/patterns.json

@@ -0,0 +1,101 @@
+[
+  {
+    "id": "rm-rf-root-or-home",
+    "name": "rm -r on /, /*, ~, ~/, $HOME or a top-level system dir",
+    "description": "rm with a recursive flag (any of -r -R -rf -fr -Rf -rfv, split -r -f, --recursive) AND a whole-token target of / /* ~ ~/ ~/* $HOME ${HOME} (optionally quoted) or a top-level system dir (/etc /usr /var ...). Flag/target order-independent (lookahead AND). Force flag deliberately not required: rm -r / is as destructive. Known FP: the text inside echo/grep/commit messages.",
+    "regex": "(?:^|[^A-Za-z0-9_.-])rm(?=[ \\t])(?=[^;&|\\n]*[ \\t](?:-[A-Za-z]*[rR][A-Za-z]*|--recursive)(?![^ \\t\\r\\n;&|)]))(?=[^;&|\\n]*[ \\t][\"']?(?:/(?:(?:bin|boot|dev|etc|home|lib|lib32|lib64|opt|proc|root|sbin|srv|sys|usr|var)/?)?\\*?|~/?\\*?|\\$HOME/?\\*?|\\$\\{HOME\\}/?\\*?)[\"']?(?![^ \\t\\r\\n;&|)]))",
+    "flags": "",
+    "severity": "critical",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "sql-drop-object",
+    "name": "SQL DROP TABLE/DATABASE/SCHEMA",
+    "description": "DROP followed by whitespace/newline and TABLE|DATABASE|SCHEMA, case-insensitive, left/right word-bounded. Matches the SQL text inside psql -c / mysql -e / sqlcmd -Q strings. Does not see SQL inside files (psql -f x.sql) nor the dropdb CLI.",
+    "regex": "(?:^|[^A-Za-z0-9_])drop[ \\t\\r\\n]+(?:table|database|schema)(?![A-Za-z0-9_])",
+    "flags": "i",
+    "severity": "critical",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "git-force-push-protected",
+    "name": "git push --force / -f / --force-with-lease / +refspec to protected branch",
+    "description": "git [global opts] push with (a force flag AND a protected-branch token) OR a +refspec of a protected branch. Protected = main, master, release/*, prod, production, prod-*, prod_*, prod/*. Branch token may be bare, src:dst, or refs/heads/*. --force-with-lease IS included: the lease only guards against clobbering unseen commits, it still rewrites protected history. 'prod*' from the spec narrowed so product-page does not match. Bare 'git push -f' (current branch unknown) is NOT matched.",
+    "regex": "(?:^|[^A-Za-z0-9_.-])git(?:[ \\t]+-[^ \\t\\r\\n;&|]+(?:[ \\t]+[^ \\t\\r\\n;&|-][^ \\t\\r\\n;&|]*)?){0,6}[ \\t]+push(?![A-Za-z0-9_-])(?:(?=[^;&|\\n]*[ \\t](?:--force(?:-with-lease|-if-includes)?(?:=[^ \\t\\r\\n;&|]*)?|-[A-Za-z]*f[A-Za-z]*)(?![^ \\t\\r\\n;&|)]))(?=[^;&|\\n]*[ \\t][\"']?\\+?(?:[^ \\t\\r\\n;&|:]*:)?(?:refs/heads/)?(?:main|master|release/[^ \\t\\r\\n;&|\"']+|prod(?:uction)?|prod[-_/][^ \\t\\r\\n;&|\"']*)[\"']?(?![^ \\t\\r\\n;&|)]))|(?=[^;&|\\n]*[ \\t][\"']?\\+(?:[^ \\t\\r\\n;&|:]*:)?(?:refs/heads/)?(?:main|master|release/[^ \\t\\r\\n;&|\"']+|prod(?:uction)?|prod[-_/][^ \\t\\r\\n;&|\"']*)[\"']?(?![^ \\t\\r\\n;&|)])))",
+    "flags": "",
+    "severity": "high",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "pipe-remote-to-shell",
+    "name": "curl|wget piped to a shell",
+    "description": "curl or wget whose output is piped (possibly through intermediate filters) into sh/bash/zsh/dash/ksh/csh, optionally via sudo/env and an absolute path. '||' is not treated as a pipe. Interpreters other than shells (python, node, perl) are not covered.",
+    "regex": "(?:^|[^A-Za-z0-9_.-])(?:curl|wget)(?![A-Za-z0-9_-])[^;&\\n|]*(?:\\|(?!\\|)[^;&\\n|]*)*\\|(?!\\|)[ \\t]*(?:sudo(?:[ \\t]+-[^ \\t\\r\\n;&|]+(?:[ \\t]+[^ \\t\\r\\n;&|-][^ \\t\\r\\n;&|]*)?){0,4}[ \\t]+|env[ \\t]+)?(?:/[A-Za-z0-9_./-]*/)?(?:ba|z|da|k|c)?sh(?![A-Za-z0-9_.-])",
+    "flags": "",
+    "severity": "high",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "remote-script-substitution",
+    "name": "shell/source/eval of curl|wget command substitution",
+    "description": "bash <(curl ...), sh -c \"$(curl ...)\", eval \"$(wget ...)\", source <(curl ...), . <(curl ...). Same threat as pipe-to-shell via process/command substitution.",
+    "regex": "(?:^|[^A-Za-z0-9_.-])(?:(?:ba|z|da|k)?sh(?:[ \\t]+-[A-Za-z]+)*|source|eval|\\.)[ \\t]+[\"']?(?:<\\(|\\$\\()[ \\t]*(?:curl|wget)(?![A-Za-z0-9_-])",
+    "flags": "",
+    "severity": "high",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "terraform-destroy-auto-approve",
+    "name": "terraform/tofu/terragrunt destroy with -auto-approve",
+    "description": "terraform|tofu|terragrunt with a destroy token (destroy or -destroy, so 'apply -destroy' is included) AND -auto-approve/--auto-approve, in either order. Plain 'terraform destroy' (interactive confirm; no TTY in agent shells) and plain 'terraform apply -auto-approve' are deliberately NOT matched: apply is covered by live-guard-gate, and matching all auto-approved applies would double-prompt and flag routine CI-style usage.",
+    "regex": "(?:^|[^A-Za-z0-9_.-])(?:terraform|tofu|terragrunt)(?![A-Za-z0-9_-])(?=[^;&|\\n]*[ \\t]-?destroy(?![^ \\t\\r\\n;&|)]))(?=[^;&|\\n]*[ \\t]--?auto-approve(?:=[^ \\t\\r\\n;&|]*)?(?![^ \\t\\r\\n;&|)]))",
+    "flags": "",
+    "severity": "critical",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "kubectl-delete-namespace",
+    "name": "kubectl/oc delete namespace",
+    "description": "kubectl|oc ... delete [flags] namespace|namespaces|ns (also ns/<name>). Flags between delete and the resource kind are allowed (--force --grace-period=0).",
+    "regex": "(?:^|[^A-Za-z0-9_.-])(?:kubectl|oc)(?![A-Za-z0-9_-])(?:[ \\t]+-[^ \\t\\r\\n;&|]+(?:[ \\t]+[^ \\t\\r\\n;&|-][^ \\t\\r\\n;&|]*)?){0,8}[ \\t]+delete(?:[ \\t]+-[^ \\t\\r\\n;&|]+(?:[ \\t]+[^ \\t\\r\\n;&|-][^ \\t\\r\\n;&|]*)?){0,6}[ \\t]+(?:namespaces?|ns)(?:/|,|(?![^ \\t\\r\\n;&|)]))",
+    "flags": "",
+    "severity": "critical",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "kubectl-delete-all",
+    "name": "kubectl/oc delete ... --all",
+    "description": "kubectl|oc with a delete token AND --all (or --all=true). --all-namespaces is excluded by the terminator check.",
+    "regex": "(?:^|[^A-Za-z0-9_.-])(?:kubectl|oc)(?![A-Za-z0-9_-])(?:[ \\t]+-[^ \\t\\r\\n;&|]+(?:[ \\t]+[^ \\t\\r\\n;&|-][^ \\t\\r\\n;&|]*)?){0,8}[ \\t]+delete(?![^ \\t\\r\\n;&|)])(?=[^;&|\\n]*[ \\t]--all(?:=[^ \\t\\r\\n;&|]*)?(?![^ \\t\\r\\n;&|)]))",
+    "flags": "",
+    "severity": "high",
+    "context": [
+      "bash"
+    ]
+  },
+  {
+    "id": "file-write-system-path",
+    "name": "File write into a system directory",
+    "description": "Anchored at path start: /etc/ /usr/ /bin/ /sbin/ /boot/ /sys/ /proc/ (leading // tolerated). Anchoring avoids matching myproject/etc/x or /home/u/usr/x, which the spec's unanchored /(etc|usr|...)/ would. The caller MUST resolve the path (path.resolve / realpath -m) first; ../../etc/passwd or symlinks are not caught by the pattern.",
+    "regex": "^/+(?:etc|usr|bin|sbin|boot|sys|proc)/",
+    "flags": "",
+    "severity": "critical",
+    "context": [
+      "file-write"
+    ]
+  }
+]

package/mods/context-burn/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "context-burn",
+  "version": "1.0.0",
+  "description": "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use."
+}

package/mods/context-burn/README.md

@@ -0,0 +1,66 @@
+# context-burn
+
+Counts tool calls per session in a small status file. Where the harness reports token use,
+it also warns once at 70% and once at 90% of the context window. It only observes: it never
+blocks a tool and never changes a tool result.
+
+## Reach and declared footprint
+
+**L1 (file writes).** The manifest declares default writes to
+`.claude/context-burn-status/*.json`, `.kiro/context-burn-status/*.json` and
+`.codex/context-burn-status/*.json`, and reads `VANGUARD_CONTEXT_BURN_STATUS_PATH`.
+It declares no subprocess spawns or network egress. This is capability disclosure,
+not isolation; the status-path override can write outside these defaults.
+
+## Status file
+
+Fields (pretty-printed JSON, rewritten in full on every event):
+
+- `session_id`: the session the counts belong to.
+- `tool_call_count`: tool calls seen in that session.
+- `last_updated`: ISO 8601 time of the last event.
+- `threshold_events`: `{ threshold, tokens, window, at }` for each threshold crossed, at most
+  one per threshold per session. Empty where no token data exists.
+
+Default paths, relative to the project:
+
+| Harness | Path |
+|---|---|
+| Claude Code | `.claude/context-burn-status/<session-hash>.json` |
+| Kiro | `.kiro/context-burn-status/<session-hash>.json` |
+| Codex | `.codex/context-burn-status/<session-hash>.json` |
+
+`<session-hash>` is the full lowercase SHA-256 of the UTF-8 `session_id`; raw session IDs
+never appear in the path. Missing or empty Node session IDs use `unsessioned`, so those
+events share one fallback file rather than isolated session state.
+
+`VANGUARD_CONTEXT_BURN_STATUS_PATH` (when non-empty) is an exact path override. Using the
+same override across sessions opts out of default isolation. It can point outside the
+declared `file_writes` globs. Old single-file state is not migrated automatically.
+
+## Per harness
+
+| Harness | Behavior |
+|---|---|
+| Claude Code native | `session.start` resets the file. After each tool call it reads context use from the session, toasts the 70% warning and the 90% critical message once each, and updates the file. |
+| Claude Code classic | Counter only. No token data, so no warnings. |
+| Kiro | Counter only, as above. See `kiro/UNSUPPORTED.md`. |
+| Codex | Counter only, as above. See `codex/UNSUPPORTED.md`. |
+
+Messages: `[context-burn] WARNING: 70% context used (<tokens> / <window> tokens)` and
+`[context-burn] CRITICAL: 90% context used (<tokens> / <window> tokens)`.
+
+## Limitations
+
+- Install either the native or the classic surface, not both: they share
+  the same session status file and would double count.
+- Updates are unlocked read-modify-write operations, so same-session parallel hooks can
+  lose increments. There is no automatic cleanup of old status files.
+- Classic PostToolUse fires only after a tool succeeds, so failed calls are not counted.
+- An unreadable or invalid status file, including malformed threshold event objects or
+  fields, starts a fresh count; the Node hook says so on stderr.
+- The native API was verified against Claude Code 2.1.296. The Node hooks need Node 22+.
+
+## Install
+
+See `mods/README.md`.

package/mods/context-burn/bin/hook.mjs

@@ -0,0 +1,38 @@
+// Command hook for classic Claude Code, Kiro and Codex: counter only, no token data.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { defaultStatusPath, freshStatus, parseStatus, recordCall, serializeStatus } from '../lib/core.mjs'
+import { projectPath, runHook } from '../lib/runtime.mjs'
+
+const target = async (ctx, sessionId) =>
+  projectPath(process.env.VANGUARD_CONTEXT_BURN_STATUS_PATH || await defaultStatusPath(ctx.harness, sessionId), ctx.harness, import.meta.dirname)
+const sessionOf = (p) => (typeof p.session_id === 'string' && p.session_id !== '' ? p.session_id : 'unsessioned')
+
+function save(file, status) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, serializeStatus(status))
+}
+
+const handlers = {
+  async SessionStart(payload, ctx) {
+    const sessionId = sessionOf(payload)
+    save(await target(ctx, sessionId), freshStatus(sessionId, new Date().toISOString()))
+  },
+  // ponytail: parallel hooks can lose an increment (read-modify-write, no lock); add the
+  // audit-trail lock if exact counts matter.
+  async PostToolUse(payload, ctx) {
+    const sessionId = sessionOf(payload)
+    const file = await target(ctx, sessionId)
+    const log = []
+    let prev
+    try {
+      prev = parseStatus(readFileSync(file, 'utf8'))
+    } catch (err) {
+      if (err?.code !== 'ENOENT') log.push(`[context-burn] status file unreadable; starting a fresh count: ${err.message}`)
+    }
+    save(file, recordCall(prev, sessionId, new Date().toISOString(), undefined).status)
+    return log.length ? { decision: 'allow', log } : undefined
+  },
+}
+
+process.exitCode = await runHook({ name: 'context-burn', handlers })

package/mods/context-burn/claude-code/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Context Burn on Claude Code
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `classic`: Classic hooks receive no token counts, so only the tool-call counter is kept and no threshold warnings are emitted; PostToolUse fires only after a tool succeeds, so failed calls are not counted.

package/mods/context-burn/claude-code/settings.hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/context-burn/bin/hook.mjs\" --harness claude-code --event PostToolUse"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/context-burn/bin/hook.mjs\" --harness claude-code --event SessionStart"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/context-burn/codex/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Context Burn on Codex
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PostToolUse`: Codex hooks receive no token counts; only the tool-call counter is kept and no threshold warnings are emitted.

package/mods/context-burn/codex/hooks.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/context-burn/bin/hook.mjs --harness codex --event PostToolUse"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/context-burn/bin/hook.mjs --harness codex --event SessionStart"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/context-burn/hooks/hooks.json

@@ -0,0 +1,5 @@
+{
+  "modules": [
+    "./register.ts"
+  ]
+}

package/mods/context-burn/hooks/register.test.ts

@@ -0,0 +1,151 @@
+import { test, expect, mock } from 'claude-code/testing'
+
+const ENV = 'VANGUARD_CONTEXT_BURN_STATUS_PATH'
+const DEFAULT = '.claude/context-burn-status/e8bc163c82eee18733288c7d4ac636db3a6deb013ef2d37b68322be20edc45cc.json'
+const RESULT = { result: { stdout: 'x', stderr: '', interrupted: false } }
+const call = { tool: 'Bash', command: 'echo x' }
+const status = (over: object = {}) => ({
+  session_id: 's1',
+  tool_call_count: 4,
+  last_updated: '1970-01-01T00:00:00.000Z',
+  threshold_events: [],
+  ...over,
+})
+
+// Wires every `$` noun a tool.call touches. Returns what the mod wrote and toasted.
+function rig(on: any, o: { env?: object; prev?: object | null; readFails?: boolean; writeFails?: boolean; context?: object; session?: { id: string }; files?: Map<string, string> } = {}) {
+  const writes: { path: string; text: string }[] = []
+  const toasts: string[] = []
+  mock.env(on, o.env ?? {})
+  mock.clock(on, { now: 0 })
+  on('session.id', () => ({ value: o.session?.id ?? 's1' }))
+  on('session.usage', () => ({
+    value: { startedAt: 0, context: o.context ?? { window: 10000 }, rateLimits: [] },
+  }))
+  on('fs.read', ($: any, e: any) => {
+    if (o.files) {
+      if (!o.files.has(e.path)) throw new Error('ENOENT')
+      return { value: o.files.get(e.path) }
+    }
+    if (o.readFails || !o.prev) throw new Error('ENOENT')
+    return { value: JSON.stringify(o.prev) }
+  })
+  on('fs.write', ($: any, e: any) => {
+    if (o.writeFails) throw new Error('disk full')
+    writes.push({ path: e.path, text: e.text })
+    o.files?.set(e.path, e.text)
+    return { value: undefined }
+  })
+  on('ui.toast', ($: any, e: any) => {
+    toasts.push(e.text)
+    return { value: undefined }
+  })
+  on('tool.call', () => RESULT)
+  on('session.start', ($: any, e: any) => ({ cwd: e.cwd }))
+  return { writes, toasts, last: () => JSON.parse(writes[writes.length - 1].text) }
+}
+
+test('session.start writes a fresh status', async ($, on) => {
+  const r = rig(on)
+  await $.session.start({ cwd: '/w', surface: 'terminal', isInteractive: true })
+  expect(r.writes[0].path.endsWith(DEFAULT)).toBe(true)
+  expect(r.last()).toEqual({ session_id: 's1', tool_call_count: 0, last_updated: '1970-01-01T00:00:00.000Z', threshold_events: [] })
+})
+
+test('session.start honors the env override', async ($, on) => {
+  const r = rig(on, { env: { [ENV]: 'custom/out.json' } })
+  await $.session.start({ cwd: '/w', surface: 'terminal', isInteractive: true })
+  expect(r.writes[0].path.endsWith('custom/out.json')).toBe(true)
+})
+
+test('tool.call passes the result through and increments the count', async ($, on) => {
+  const r = rig(on, { prev: status() })
+  expect(await $.tool.call(call)).toEqual(RESULT)
+  expect(r.last().tool_call_count).toBe(5)
+})
+
+test('a status for another session restarts at 1', async ($, on) => {
+  const r = rig(on, { prev: status({ session_id: 'other' }) })
+  await $.tool.call(call)
+  expect(r.last().session_id).toBe('s1')
+  expect(r.last().tool_call_count).toBe(1)
+})
+
+test('75 percent toasts one warning and records the event', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { tokens: 7500, window: 10000, percent: 75 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual(['[context-burn] WARNING: 70% context used (7500 / 10000 tokens)'])
+  expect(r.last().threshold_events.length).toBe(1)
+  expect(r.last().threshold_events[0].threshold).toBe(70)
+})
+
+test('an already recorded 70 event does not toast again', async ($, on) => {
+  const prev = status({ threshold_events: [{ threshold: 70, tokens: 7500, window: 10000, at: 'x' }] })
+  const r = rig(on, { prev, context: { tokens: 7600, window: 10000, percent: 76 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual([])
+})
+
+test('95 percent toasts warning then critical', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { tokens: 9500, window: 10000, percent: 95 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual([
+    '[context-burn] WARNING: 70% context used (9500 / 10000 tokens)',
+    '[context-burn] CRITICAL: 90% context used (9500 / 10000 tokens)',
+  ])
+})
+
+test('percent without tokens computes and rounds tokens', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { window: 3333, percent: 71.5 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual(['[context-burn] WARNING: 70% context used (2383 / 3333 tokens)'])
+})
+
+test('no token data means no toast but the count still rises', async ($, on) => {
+  const r = rig(on, { prev: status(), context: { window: 10000 } })
+  await $.tool.call(call)
+  expect(r.toasts).toEqual([])
+  expect(r.last().tool_call_count).toBe(5)
+})
+
+test('a failing read starts a fresh count', async ($, on) => {
+  const r = rig(on, { readFails: true })
+  await $.tool.call(call)
+  expect(r.last().tool_call_count).toBe(1)
+})
+
+test('malformed threshold events restart counting and still toast the threshold', async ($, on) => {
+  const r = rig(on, { prev: status({ threshold_events: [null] }), context: { tokens: 7500, window: 10000 } })
+  expect(await $.tool.call(call)).toEqual(RESULT)
+  expect(r.last().tool_call_count).toBe(1)
+  expect(r.last().threshold_events.length).toBe(1)
+  expect(r.toasts.length).toBe(1)
+})
+
+test('interleaved sessions retain independent counts and warn only once per session', async ($, on) => {
+  const session = { id: '../first' }
+  const files = new Map<string, string>()
+  const r = rig(on, { session, files, context: { tokens: 7500, window: 10000 } })
+  for (const id of ['../first', '..\\second']) {
+    session.id = id
+    await $.session.start({ cwd: '/w', surface: 'terminal', isInteractive: true })
+    expect(await $.tool.call(call)).toEqual(RESULT)
+  }
+  for (const id of ['../first', '..\\second']) {
+    session.id = id
+    expect(await $.tool.call(call)).toEqual(RESULT)
+  }
+  expect(files.size).toBe(2)
+  for (const [path, text] of files) {
+    expect(/\/context-burn-status\/[a-f0-9]{64}\.json$/.test(path)).toBe(true)
+    const saved = JSON.parse(text)
+    expect(saved.tool_call_count).toBe(2)
+    expect(saved.threshold_events.length).toBe(1)
+  }
+  expect(r.toasts.length).toBe(2)
+})
+
+test('a failing write still returns the tool result', async ($, on) => {
+  rig(on, { prev: status(), writeFails: true })
+  expect(await $.tool.call(call)).toEqual(RESULT)
+})

package/mods/context-burn/hooks/register.ts

@@ -0,0 +1,35 @@
+import type { Register } from 'claude-code'
+import { defaultStatusPath, freshStatus, parseStatus, recordCall, serializeStatus } from '../lib/core.mjs'
+
+async function statusPath($: any, sessionId: string): Promise<string> {
+  return (await $.env.get('VANGUARD_CONTEXT_BURN_STATUS_PATH')) || await defaultStatusPath('claude-code', sessionId)
+}
+
+export const register: Register = (on) => {
+  // A new session resets the file; a failure must never block startup.
+  on('session.start', async ($, e, next) => {
+    const at = new Date(await $.clock.now()).toISOString()
+    const sessionId = await $.session.id()
+    await $.fs.write(await statusPath($, sessionId), serializeStatus(freshStatus(sessionId, at)))
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // Observer: the tool runs first and its result is returned untouched, whatever happens here.
+  on('tool.call', async ($, e, next) => {
+    const r = await next(e)
+    const sessionId = await $.session.id()
+    const path = await statusPath($, sessionId)
+    let prev
+    try {
+      prev = parseStatus(await $.fs.read(path))
+    } catch {
+      prev = undefined
+    }
+    const at = new Date(await $.clock.now()).toISOString()
+    const { context } = await $.session.usage()
+    const { status, messages } = recordCall(prev, sessionId, at, context)
+    for (const m of messages) await $.ui.toast(m)
+    await $.fs.write(path, serializeStatus(status))
+    return r
+  }).catch(($, e, next) => next(e))
+}

package/mods/context-burn/kiro/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Context Burn on Kiro
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PostToolUse`: Kiro hooks receive no token counts; only the tool-call counter is kept and no threshold warnings are emitted.