@raishin/vanguard-frontier-agentic 3.15.0 → 3.16.0

package/mods/audit-trail/lib/common.mjs

@@ -0,0 +1,213 @@
+// Shared helpers for the mods under mods/. scripts/generate-mods.mjs copies this file
+// byte-for-byte to mods/<id>/lib/common.mjs, so edit it here and run `npm run mods:write`.
+//
+// Pure on purpose: no imports, no environment, no I/O. Claude Code's native mod runtime
+// imports it and has no Node, and every harness must reach the same verdict on the same
+// input. Regexes compile without the `u` flag so Node and Python `re.ASCII`
+// (tests/validate-mods.py) read them the same way.
+
+export const LIMITS = Object.freeze({
+  // A redaction that still changes after this many passes is withheld as a whole.
+  maxPasses: 8,
+  // A guard candidate longer than this is not evaluated and counts as a hit.
+  maxCandidateChars: 65536,
+  // Guard candidates are not evaluated past this combined length; the call counts as a hit.
+  maxTotalChars: 262144,
+  // Only the tail of a leaf's context (key or previous sibling) is prefixed to it.
+  maxContextChars: 256,
+})
+
+const MARKER_PREFIX = '[REDACTED:'
+export const OVERFLOW_MARKER = '[REDACTED:overflow]'
+const OVERFLOW_HIT = Object.freeze({ id: 'overflow', name: 'redaction did not converge' })
+export const TOO_LARGE_HIT = Object.freeze({ id: 'too-large', name: 'input too large to evaluate' })
+
+const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const PATTERN_KEYS = new Set(['id', 'name', 'description', 'regex', 'flags', 'context', 'severity', 'agents'])
+const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s !== '')
+
+// Parser diagnostics can quote credential-bearing data; never expose it in hook logs.
+export function parseJson(text, source) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error(`${source}: invalid JSON`)
+  }
+}
+
+// Validates a patterns.json-shaped list and compiles it. Throws on anything malformed so a
+// bad extension file fails closed in the caller instead of silently matching nothing.
+export function compilePatterns(list, source = 'patterns') {
+  if (!Array.isArray(list)) throw new Error(`${source}: expected an array of patterns`)
+  const seen = new Set()
+  return list.map((p, i) => {
+    const where = `${source}[${i}]`
+    if (p === null || typeof p !== 'object' || Array.isArray(p)) throw new Error(`${where}: expected an object`)
+    for (const k of Object.keys(p)) if (!PATTERN_KEYS.has(k)) throw new Error(`${where}: unknown key ${k}`)
+    if (typeof p.id !== 'string' || !ID_RE.test(p.id)) throw new Error(`${where}: id must be kebab-case`)
+    if (seen.has(p.id)) throw new Error(`${where}: duplicate id ${p.id}`)
+    seen.add(p.id)
+    if (typeof p.name !== 'string' || p.name === '') throw new Error(`${where}: name must be a non-empty string`)
+    if (typeof p.regex !== 'string' || p.regex === '') throw new Error(`${where}: regex must be a non-empty string`)
+    if (p.flags !== '' && p.flags !== 'i') throw new Error(`${where}: flags must be "" or "i"`)
+    if (!isStringArray(p.context) || p.context.length === 0) throw new Error(`${where}: context must be a non-empty string array`)
+    for (const k of ['description', 'severity']) {
+      if (p[k] !== undefined && typeof p[k] !== 'string') throw new Error(`${where}: ${k} must be a string`)
+    }
+    if (p.agents !== undefined && !isStringArray(p.agents)) throw new Error(`${where}: agents must be a string array`)
+    let rx, rxg
+    try {
+      rx = new RegExp(p.regex, p.flags)
+      rxg = new RegExp(p.regex, 'g' + p.flags)
+    } catch {
+      throw new Error(`${where}: regex does not compile`)
+    }
+    return Object.freeze({
+      id: p.id,
+      name: p.name,
+      severity: p.severity,
+      context: Object.freeze([...p.context]),
+      agents: p.agents ? Object.freeze([...p.agents]) : undefined,
+      rx,
+      rxg,
+      marker: `${MARKER_PREFIX}${p.id}]`,
+    })
+  })
+}
+
+// Every string value (not key) in depth-first order. The order follows the input, so the
+// same payload always yields the same list.
+export function stringLeaves(value, out = []) {
+  if (typeof value === 'string') out.push(value)
+  else if (Array.isArray(value)) for (const v of value) stringLeaves(v, out)
+  else if (value !== null && typeof value === 'object') for (const v of Object.values(value)) stringLeaves(v, out)
+  return out
+}
+
+// Guard candidates: every string leaf, plus every all-string array joined with spaces so
+// an argv-style command (["rm", "-rf", "/"]) reads like the shell line it runs.
+export function candidates(value) {
+  const out = stringLeaves(value)
+  const joinArrays = (v) => {
+    if (Array.isArray(v)) {
+      if (v.length > 1 && v.every((s) => typeof s === 'string')) out.push(v.join(' '))
+      v.forEach(joinArrays)
+    } else if (v !== null && typeof v === 'object') {
+      Object.values(v).forEach(joinArrays)
+    }
+  }
+  joinArrays(value)
+  return out
+}
+
+// The patterns tagged with `context` that match any text, in catalog order. Oversized input
+// is not evaluated (regex cost is unbounded there) and reports TOO_LARGE_HIT instead.
+export function matchPatterns(patterns, texts, context) {
+  let total = 0
+  for (const t of texts) {
+    total += t.length
+    if (t.length > LIMITS.maxCandidateChars || total > LIMITS.maxTotalChars) return [TOO_LARGE_HIT]
+  }
+  return patterns.filter((p) => p.context.includes(context) && texts.some((t) => p.rx.test(t)))
+}
+
+// One pattern pass after another until the text stops changing. Each pass can expose a new
+// match (password-in-url can swallow an earlier marker), so a single pass is not enough.
+function fixedPoint(text, patterns, hits) {
+  let x = text
+  for (let pass = 0; pass <= LIMITS.maxPasses; pass++) {
+    let y = x
+    for (const p of patterns) {
+      y = y.replace(p.rxg, (m) => {
+        if (m === '') return m
+        hits.add(p)
+        return p.marker
+      })
+    }
+    if (y === x) return x
+    x = y
+  }
+  hits.add(OVERFLOW_HIT)
+  return OVERFLOW_MARKER
+}
+
+// Redacts `s` with `ctx` in front so a secret split across a key and its value, or across
+// argv elements ("Bearer", "<token>"), still matches; then strips the context back off.
+function redactLeaf(s, ctx, patterns, hits) {
+  if (ctx === '') return fixedPoint(s, patterns, hits)
+  const pre = ctx.slice(-LIMITS.maxContextChars) + ' '
+  const y = fixedPoint(pre + s, patterns, hits)
+  if (y === OVERFLOW_MARKER) return y
+  const r = fixedPoint(pre, patterns, new Set())
+  if (y.startsWith(r)) return fixedPoint(y.slice(r.length), patterns, hits)
+  // A match spans the boundary: keep from the marker that covers it. Slicing changes
+  // anchors and boundaries, so also check the standalone leaf after contextual matching.
+  let d = 0
+  while (d < r.length && y[d] === r[d]) d++
+  const i = y.lastIndexOf(MARKER_PREFIX, d)
+  return fixedPoint(i >= 0 ? y.slice(i) : y, patterns, hits)
+}
+
+function walk(v, ctx, patterns, hits) {
+  if (typeof v === 'string') {
+    const local = new Set()
+    const out = redactLeaf(v, ctx, patterns, local)
+    if (out !== v) for (const h of local) hits.add(h)
+    return out
+  }
+  if (Array.isArray(v)) {
+    let prev = null
+    return v.map((el) => {
+      const out = walk(el, typeof prev === 'string' ? prev : ctx, patterns, hits)
+      prev = el
+      return out
+    })
+  }
+  if (v !== null && typeof v === 'object') {
+    const named = typeof v.name === 'string' ? v.name : typeof v.key === 'string' ? v.key : null
+    // fromEntries, not assignment: `out[k] = v` would drop an own "__proto__" key.
+    return Object.fromEntries(
+      Object.entries(v).map(([k, x]) => [
+        walk(k, '', patterns, hits),
+        walk(x, k === 'value' && named !== null ? named : k, patterns, hits),
+      ]),
+    )
+  }
+  return v
+}
+
+// Returns a copy of `value` with every match replaced by `[REDACTED:<id>]`, plus the
+// patterns that fired (catalog order, unique). Keys are redacted too; two keys that redact
+// to the same marker collapse into one, which loses data but never leaks it.
+export function redactValue(value, patterns) {
+  const hits = new Set()
+  const out = walk(value, '', patterns, hits)
+  const order = [...patterns, OVERFLOW_HIT]
+  return { value: out, hits: order.filter((p) => hits.has(p)) }
+}
+
+// Same shape as `value`, every string replaced by `text`. The fallback when redaction
+// itself failed: withhold everything rather than pass anything through.
+export function maskValue(value, text) {
+  if (typeof value === 'string') return text
+  if (Array.isArray(value)) return value.map((v) => maskValue(v, text))
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskValue(v, text)]))
+  }
+  return value
+}
+
+// JSON with object keys sorted at every level, so equal values hash equally.
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return '[' + value.map((v) => (v === undefined ? 'null' : canonicalJson(v))).join(',') + ']'
+  if (value !== null && typeof value === 'object') {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}'
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+export async function sha256Hex(text) {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')
+}

package/mods/audit-trail/lib/core.mjs

@@ -0,0 +1,50 @@
+// Pure record logic for audit-trail. The hook adds the file I/O around it.
+import { canonicalJson, sha256Hex } from './common.mjs'
+
+export const SESSION_RE = /^[A-Za-z0-9._-]{1,128}$/
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+// Picks the session id: env override, then the payload, then a shared fallback log.
+export function rawSessionId(envValue, payload) {
+  if (typeof envValue === 'string' && envValue) return envValue
+  const id = isObject(payload) ? payload.session_id : undefined
+  return typeof id === 'string' && id ? id : 'unsessioned'
+}
+
+// Ids become file names, so anything outside SESSION_RE is replaced by a hash prefix.
+export async function safeSessionId(raw) {
+  return SESSION_RE.test(raw) ? raw : (await sha256Hex(raw)).slice(0, 32)
+}
+
+// Last sequence number in an existing log. A corrupt tail throws: restarting at 1 would fake
+// a clean sequence.
+export function lastSequence(text, name = '') {
+  if (text !== '' && !text.endsWith('\n')) throw new Error(`audit log ${name} has an unterminated last line`)
+  const lines = text.split('\n').filter((l) => l.trim() !== '')
+  if (lines.length === 0) return 0
+  let n
+  try {
+    n = JSON.parse(lines[lines.length - 1]).sequence_number
+  } catch {
+    n = undefined
+  }
+  if (!Number.isInteger(n) || n < 1) throw new Error(`audit log ${name} has a corrupt last line`)
+  return n
+}
+
+// One log line. Hashes cover the canonical JSON of the arguments and the result; Kiro's
+// stdin field names are undocumented, so there the whole payload is hashed.
+export async function buildRecord({ timestamp, sessionId, agentId, payload, harness, sequence }) {
+  const p = isObject(payload) ? payload : {}
+  const kiro = harness === 'kiro'
+  return {
+    timestamp,
+    session_id: sessionId,
+    agent_id: agentId || null,
+    tool_name: typeof p.tool_name === 'string' ? p.tool_name : null,
+    args_hash: await sha256Hex(canonicalJson(kiro ? (payload ?? null) : (p.tool_input ?? null))),
+    result_hash: await sha256Hex(canonicalJson(kiro ? null : (p.tool_response ?? null))),
+    sequence_number: sequence,
+  }
+}

package/mods/audit-trail/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/audit-trail/mod.toml

@@ -0,0 +1,37 @@
+[mod]
+id = "audit-trail"
+name = "Audit Trail"
+description = "Appends one JSON line per tool call to a per-session log with sha256 hashes of the arguments and result."
+version = "1.0.0"
+reach_level = 1
+events = ["PostToolUse"]
+
+[footprint]
+env_reads = ["VANGUARD_AUDIT_TRAIL_LOG_DIR", "VANGUARD_AUDIT_TRAIL_SESSION_ID", "VANGUARD_AUDIT_TRAIL_AGENT_ID"]
+file_writes = [".audit/**"]
+spawns = []
+egress_hosts = []
+
+[harnesses.claude-code]
+supported = true
+surfaces = ["classic"]
+events = ["PostToolUse"]
+
+[harnesses.claude-code.degraded]
+classic = "Classic PostToolUse fires only after a tool succeeds, so failed tool calls are not logged."
+
+[harnesses.claude-code.unsupported]
+native = "The native mod API has no file append; rewriting the whole log would break append-only writes. Install the classic hook instead."
+
+[harnesses.kiro]
+supported = true
+requires = ["node"]
+events = ["PostToolUse"]
+
+[harnesses.kiro.degraded]
+PostToolUse = "Kiro does not document stdin field names; args_hash covers the whole payload, result_hash hashes null, and without VANGUARD_AUDIT_TRAIL_SESSION_ID every session shares the unsessioned log."
+
+[harnesses.codex]
+supported = true
+requires = ["node"]
+events = ["PostToolUse"]

package/mods/blast-radius-guard/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "blast-radius-guard",
+  "version": "1.0.0",
+  "description": "Asks before, or blocks, destructive shell commands and writes to system paths."
+}

package/mods/blast-radius-guard/README.md

@@ -0,0 +1,53 @@
+# Blast Radius Guard
+
+## Reach and declared footprint
+
+**L0 (no declared file writes, subprocess spawns or network egress).** The manifest
+only declares environment reads of `VANGUARD_BLAST_RADIUS_GUARD_MODE` and
+`VANGUARD_BLAST_RADIUS_GUARD_PATTERNS`. The `file_writes`, `spawns` and `egress_hosts`
+arrays are empty. This is capability disclosure, not enforced isolation.
+
+## What it does
+
+Checks every tool call before it runs. It asks for confirmation, or blocks, when the call
+looks destructive: a shell command from the built-in pattern list (recursive deletes of
+system or home paths, SQL drops, force pushes to protected branches, piping a download
+into a shell, and similar) or a write to a system path. Paths are normalized lexically
+first, so `/tmp/../etc/passwd` is caught.
+
+## Configuration
+
+- `VANGUARD_BLAST_RADIUS_GUARD_MODE`: `confirm` (the default when unset) asks. Any other
+  value, including a typo, blocks.
+- `VANGUARD_BLAST_RADIUS_GUARD_PATTERNS`: optional path to a JSON file of extra patterns.
+  They are appended to the built-in list and never replace it. If the file is set but
+  cannot be read, is not valid JSON, is malformed, or reuses a built-in id, every call is
+  denied.
+
+The extension file is an array of entries with the same keys as `patterns.json`: `id`
+(kebab-case, unique), `name`, `description`, `regex`, `flags` (`""` or `"i"`), `context`
+(`["bash"]` for shell text or `["file-write"]` for normalized paths) and `severity`.
+
+## Per-harness behavior
+
+| Harness | Surface | Behavior |
+| --- | --- | --- |
+| Claude Code | native | `tool.check` guard. Never loosens the engine verdict; a hit asks (or denies in block mode). |
+| Claude Code | classic | `PreToolUse` command hook; a hit asks (or denies in block mode). |
+| Kiro | hook | Degraded. The whole payload is scanned, the system-path rule applies to the path keys whatever the tool, and confirm mode denies. |
+| Codex | hook | Degraded. Codex rejects ask, so confirm mode denies with a reason. |
+
+## Limitations
+
+- It scans every string in the tool input, so a file write whose content mentions a
+  destructive command also asks. This false positive is by design (fail closed).
+- Relative paths are not resolved against a working directory.
+- Kiro documents no stdin field names, so its whole payload is scanned.
+- An `ask` is settled by the permission mode, so a bypass mode may auto-approve.
+- Input over the size limit is not evaluated and counts as a hit.
+- The native API is early access, verified against Claude Code 2.1.296.
+- Classic, Kiro and Codex hooks need Node 22+.
+
+## Install
+
+See `mods/README.md`.

package/mods/blast-radius-guard/bin/hook.mjs

@@ -0,0 +1,18 @@
+// Command-hook entry for classic Claude Code, Kiro and Codex.
+import { readFileSync } from 'node:fs'
+import { checkToolUse, compileGuardPatterns, modeOf, toolUseFromPayload } from '../lib/core.mjs'
+import { runHook } from '../lib/runtime.mjs'
+
+const PreToolUse = (payload) => {
+  const mode = modeOf(process.env.VANGUARD_BLAST_RADIUS_GUARD_MODE)
+  const file = process.env.VANGUARD_BLAST_RADIUS_GUARD_PATTERNS
+  const patterns = compileGuardPatterns(file ? readFileSync(file, 'utf8') : undefined)
+  return checkToolUse(toolUseFromPayload(payload), patterns, mode)
+}
+
+const onError = (err) => ({
+  decision: 'deny',
+  reason: `blast-radius-guard: check failed; denied (${err instanceof Error ? err.message : String(err)})`,
+})
+
+process.exitCode = await runHook({ name: 'blast-radius-guard', handlers: { PreToolUse }, onError })

package/mods/blast-radius-guard/claude-code/settings.hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/blast-radius-guard/bin/hook.mjs\" --harness claude-code --event PreToolUse"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/blast-radius-guard/codex/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Blast Radius Guard on Codex
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PreToolUse`: Codex rejects ask; confirm mode denies with a reason.

package/mods/blast-radius-guard/codex/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/blast-radius-guard/bin/hook.mjs --harness codex --event PreToolUse"
+          }
+        ]
+      }
+    ]
+  }
+}

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

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

package/mods/blast-radius-guard/hooks/register.test.ts

@@ -0,0 +1,97 @@
+import { test, expect, mock } from 'claude-code/testing'
+
+const ENV_MODE = 'VANGUARD_BLAST_RADIUS_GUARD_MODE'
+const ENV_PATTERNS = 'VANGUARD_BLAST_RADIUS_GUARD_PATTERNS'
+const allow = () => ({ decision: 'allow' as const })
+const bash = (command: string) => ({ tool: 'Bash', input: { command } })
+const ext = (over: object = {}) =>
+  JSON.stringify([{ id: 'danger-cmd', name: 'danger cmd', regex: 'danger-cmd', flags: '', context: ['bash'], ...over }])
+
+test('rm -rf / asks by default', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  expect((await $.tool.check(bash('rm -rf /'))).decision).toBe('ask')
+})
+
+test('block mode denies', async ($, on) => {
+  mock.env(on, { [ENV_MODE]: 'block' })
+  on('tool.check', allow)
+  expect((await $.tool.check(bash('rm -rf /'))).decision).toBe('deny')
+})
+
+test('unknown mode denies', async ($, on) => {
+  mock.env(on, { [ENV_MODE]: 'bogus' })
+  on('tool.check', allow)
+  expect((await $.tool.check(bash('rm -rf /'))).decision).toBe('deny')
+})
+
+test('clean command passes the engine verdict', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  expect((await $.tool.check(bash('ls'))).decision).toBe('allow')
+})
+
+test('engine deny stays deny', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', () => ({ decision: 'deny' as const, reason: 'engine' }))
+  expect((await $.tool.check(bash('ls'))).decision).toBe('deny')
+})
+
+test('Write to a traversal path to /etc asks', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await $.tool.check({ tool: 'Write', input: { file_path: '/tmp/../etc/passwd', content: 'x' } })
+  expect(v.decision).toBe('ask')
+})
+
+test('Read of /etc/passwd is allowed', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await $.tool.check({ tool: 'Read', input: { file_path: '/etc/passwd' } })
+  expect(v.decision).toBe('allow')
+})
+
+test('argv array is read as a command line', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await $.tool.check({ tool: 'Exec', input: { argv: ['rm', '-rf', '/'] } })
+  expect(v.decision).toBe('ask')
+})
+
+test('extension pattern asks', async ($, on) => {
+  mock.env(on, { [ENV_PATTERNS]: '/ext.json' })
+  on('tool.check', allow)
+  on('fs.read', () => ({ value: ext() }))
+  expect((await $.tool.check(bash('run danger-cmd now'))).decision).toBe('ask')
+})
+
+test('unreadable extension file denies', async ($, on) => {
+  mock.env(on, { [ENV_PATTERNS]: '/ext.json' })
+  on('tool.check', allow)
+  on('fs.read', () => {
+    throw new Error('nope')
+  })
+  expect((await $.tool.check(bash('ls'))).decision).toBe('deny')
+})
+
+test('extension that is not JSON denies', async ($, on) => {
+  mock.env(on, { [ENV_PATTERNS]: '/ext.json' })
+  on('tool.check', allow)
+  on('fs.read', () => ({ value: 'not json' }))
+  expect((await $.tool.check(bash('ls'))).decision).toBe('deny')
+})
+
+test('extension reusing a built-in id denies', async ($, on) => {
+  mock.env(on, { [ENV_PATTERNS]: '/ext.json' })
+  on('tool.check', allow)
+  on('fs.read', () => ({ value: ext({ id: 'rm-rf-root-or-home' }) }))
+  expect((await $.tool.check(bash('ls'))).decision).toBe('deny')
+})
+
+test('oversized command asks as too large', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await $.tool.check(bash('a'.repeat(70000)))
+  expect(v.decision).toBe('ask')
+  expect(v.reason).toContain('input too large to evaluate')
+})