@raishin/vanguard-frontier-agentic 3.15.0 → 3.16.0

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.

package/mods/context-burn/kiro/context-burn-post-tool-use-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "context-burn:PostToolUse",
+      "description": "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use.",
+      "trigger": "PostToolUse",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/context-burn/bin/hook.mjs --harness kiro --event PostToolUse"
+      }
+    }
+  ]
+}

package/mods/context-burn/kiro/context-burn-session-start-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "context-burn:SessionStart",
+      "description": "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use.",
+      "trigger": "SessionStart",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/context-burn/bin/hook.mjs --harness kiro --event SessionStart"
+      }
+    }
+  ]
+}