@raishin/vanguard-frontier-agentic 3.15.0 → 3.17.0

package/mods/context-burn/lib/core.mjs

@@ -0,0 +1,79 @@
+// Pure counter and threshold logic for context-burn. The native module and the Node hook
+// both import it, so the status file means the same thing on every harness.
+import { parseJson, sha256Hex } from './common.mjs'
+
+const STATUS_DIR = Object.freeze({
+  'claude-code': '.claude/context-burn-status',
+  kiro: '.kiro/context-burn-status',
+  codex: '.codex/context-burn-status',
+})
+
+// Never interpolate a raw session id into a filesystem path.
+export async function defaultStatusPath(harness, sessionId) {
+  return `${STATUS_DIR[harness]}/${await sha256Hex(sessionId)}.json`
+}
+
+const THRESHOLDS = [
+  [70, 'WARNING'],
+  [90, 'CRITICAL'],
+]
+
+// A new session starts at zero with no threshold events.
+export function freshStatus(sessionId, at) {
+  return { session_id: sessionId, tool_call_count: 0, last_updated: at, threshold_events: [] }
+}
+
+// Rejects anything that is not a context-burn status so a stray file is never extended.
+export function parseStatus(text) {
+  const s = parseJson(text, 'context-burn status')
+  const ok =
+    s !== null &&
+    typeof s === 'object' &&
+    !Array.isArray(s) &&
+    typeof s.session_id === 'string' &&
+    Number.isInteger(s.tool_call_count) &&
+    s.tool_call_count >= 0 &&
+    typeof s.last_updated === 'string' &&
+    Array.isArray(s.threshold_events) &&
+    s.threshold_events.every((t) =>
+      t !== null && typeof t === 'object' && !Array.isArray(t) &&
+      THRESHOLDS.some(([threshold]) => t.threshold === threshold) &&
+      Number.isFinite(t.tokens) && t.tokens >= 0 &&
+      Number.isFinite(t.window) && t.window > 0 &&
+      typeof t.at === 'string',
+    )
+  if (!ok) throw new Error('status file is not a context-burn status')
+  return s
+}
+
+// Counts one tool call and, when token data exists, records each threshold crossed for the
+// first time. Never mutates prev.
+export function recordCall(prev, sessionId, at, context) {
+  const base = prev?.session_id === sessionId ? prev : freshStatus(sessionId, at)
+  const status = {
+    ...base,
+    tool_call_count: base.tool_call_count + 1,
+    last_updated: at,
+    threshold_events: [...base.threshold_events],
+  }
+  const messages = []
+  const window = context?.window
+  const tokens =
+    context?.tokens ??
+    (context?.percent !== undefined && window > 0 ? Math.round((context.percent * window) / 100) : undefined)
+  if (tokens !== undefined && window > 0) {
+    const pct = context.percent ?? (tokens / window) * 100
+    for (const [threshold, label] of THRESHOLDS) {
+      if (pct >= threshold && !status.threshold_events.some((t) => t.threshold === threshold)) {
+        status.threshold_events.push({ threshold, tokens, window, at })
+        messages.push(`[context-burn] ${label}: ${threshold}% context used (${tokens} / ${window} tokens)`)
+      }
+    }
+  }
+  return { status, messages }
+}
+
+// Pretty JSON with a trailing newline; the whole file is rewritten each event.
+export function serializeStatus(status) {
+  return JSON.stringify(status, null, 2) + '\n'
+}

package/mods/context-burn/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/context-burn/mod.toml

@@ -0,0 +1,37 @@
+[mod]
+id = "context-burn"
+name = "Context Burn"
+description = "Tracks context use per session in a status file and warns at 70% and 90% where the harness reports token use."
+version = "1.0.0"
+reach_level = 1
+events = ["PostToolUse", "SessionStart"]
+
+[footprint]
+env_reads = ["VANGUARD_CONTEXT_BURN_STATUS_PATH"]
+file_writes = [".claude/context-burn-status/*.json", ".kiro/context-burn-status/*.json", ".codex/context-burn-status/*.json"]
+spawns = []
+egress_hosts = []
+
+[harnesses.claude-code]
+supported = true
+surfaces = ["native", "classic"]
+events = ["PostToolUse", "SessionStart"]
+
+[harnesses.claude-code.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."
+
+[harnesses.kiro]
+supported = true
+requires = ["node"]
+events = ["PostToolUse", "SessionStart"]
+
+[harnesses.kiro.degraded]
+PostToolUse = "Kiro hooks receive no token counts; only the tool-call counter is kept and no threshold warnings are emitted."
+
+[harnesses.codex]
+supported = true
+requires = ["node"]
+events = ["PostToolUse", "SessionStart"]
+
+[harnesses.codex.degraded]
+PostToolUse = "Codex hooks receive no token counts; only the tool-call counter is kept and no threshold warnings are emitted."

package/mods/live-guard-gate/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "live-guard-gate",
+  "version": "1.0.0",
+  "description": "Asks before live cloud mutations and names the guard agent that should review them."
+}

package/mods/live-guard-gate/README.md

@@ -0,0 +1,43 @@
+# Live Guard Gate
+
+Asks before a tool call that would mutate live cloud infrastructure, and names the
+guard agents that should review it first. It covers Terraform and Pulumi, the AWS, Azure,
+Google Cloud and OCI CLIs, `kubectl`, Helm, Argo CD, Velero and Snowflake role changes.
+
+## Reach and declared footprint
+
+**L0 (no declared file writes, subprocess spawns or network egress).** All four
+manifest footprint arrays (`env_reads`, `file_writes`, `spawns` and `egress_hosts`)
+are empty. This is capability disclosure, not enforced isolation.
+
+## How agent names are chosen
+
+Each pattern in `patterns.json` carries an `agents` list. When several patterns match,
+the reason lists the union of their agents in first-seen order. `lib/live-agents.mjs`
+lists the live guard agents the patterns cover (`covered`) and those with no pattern yet
+(`uncovered`). It is regenerated by `npm run mods:write`.
+
+## Per-harness behavior
+
+| Harness | Surface | Behavior |
+| --- | --- | --- |
+| Claude Code | native module | `tool.check` asks; the engine's own deny is never loosened |
+| Claude Code | classic hook | `PreToolUse` asks |
+| Kiro | Node hook | the whole payload is scanned; a hit is denied (no confirmation protocol) |
+| Codex | Node hook | a hit is denied with a reason (Codex rejects ask) |
+
+The mod reads no environment variables, writes no files and makes no network calls.
+
+## Limitations
+
+- It matches shell text in every string of the tool input, so a file whose content
+  mentions such a command also asks.
+- It does not know which cloud account or context is live; a command against a sandbox asks too.
+- An `ask` may be auto-approved under a bypass permission mode.
+- Input over the size limit is not evaluated and asks.
+- The native API was verified against Claude Code 2.1.296 (early access). Other harnesses
+  need Node 22+.
+
+## Install
+
+See [mods/README.md](../README.md).

package/mods/live-guard-gate/bin/hook.mjs

@@ -0,0 +1,12 @@
+// Node entry for Kiro, Codex and classic Claude Code. Reads the hook payload on stdin.
+import { runHook } from '../lib/runtime.mjs'
+import { checkToolUse, toolUseFromPayload } from '../lib/core.mjs'
+
+const handlers = {
+  PreToolUse: (payload) => checkToolUse(toolUseFromPayload(payload)),
+}
+
+// Fail closed: a payload we cannot read is denied rather than let through.
+const onError = (err) => ({ decision: 'deny', reason: `live-guard-gate: check failed; denied (${err.message})` })
+
+process.exitCode = await runHook({ name: 'live-guard-gate', handlers, onError })

package/mods/live-guard-gate/claude-code/settings.hooks.json

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

package/mods/live-guard-gate/codex/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Live Guard Gate on Codex
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PreToolUse`: Codex rejects ask; a hit is denied with a reason.

package/mods/live-guard-gate/codex/hooks.json

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

package/mods/live-guard-gate/hooks/hooks.json

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

package/mods/live-guard-gate/hooks/register.test.ts

@@ -0,0 +1,59 @@
+import { test, expect, mock } from 'claude-code/testing'
+
+const allow = () => ({ decision: 'allow' as const })
+const check = ($: any, input: unknown) => $.tool.check({ tool: 'Bash', input })
+
+test('terraform apply asks and names the IaC guard', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await check($, { command: 'terraform apply -auto-approve' })
+  expect(v.decision).toBe('ask')
+  expect(v.reason).toContain('aws-live-iac-change-guard-agent')
+})
+
+test('az role assignment create asks and names the Entra guard', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await check($, { command: 'az role assignment create --role Reader' })
+  expect(v.decision).toBe('ask')
+  expect(v.reason).toContain('azure-live-entra-role-assignment-guard-agent')
+})
+
+test('kubectl delete asks and names the rollout guard', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await check($, { command: 'kubectl delete pod web-0' })
+  expect(v.decision).toBe('ask')
+  expect(v.reason).toContain('gcp-live-gke-rollout-guard-agent')
+})
+
+test('argv-array input asks', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await check($, { argv: ['terraform', 'apply'] })
+  expect(v.decision).toBe('ask')
+})
+
+test('read-only commands pass the engine verdict through', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  for (const command of ['terraform plan', 'ls', 'az account show', 'kubectl get pods']) {
+    expect((await check($, { command })).decision).toBe('allow')
+  }
+})
+
+test('engine deny stays deny', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', () => ({ decision: 'deny' as const, reason: 'engine' }))
+  const v = await check($, { command: 'terraform apply' })
+  expect(v.decision).toBe('deny')
+  expect(v.reason).toBe('engine')
+})
+
+test('oversized input asks', async ($, on) => {
+  mock.env(on, {})
+  on('tool.check', allow)
+  const v = await check($, { command: 'a'.repeat(70000) })
+  expect(v.decision).toBe('ask')
+  expect(v.reason).toContain('input too large')
+})

package/mods/live-guard-gate/hooks/register.ts

@@ -0,0 +1,11 @@
+import type { Register } from 'claude-code'
+import { checkToolUse } from '../lib/core.mjs'
+
+export const register: Register = (on) => {
+  // Never loosens the engine: its deny stays deny; a live mutation raises allow to ask.
+  on('tool.check', async ($, e, next) => {
+    const v = await next(e)
+    if (v.decision === 'deny') return v
+    return checkToolUse({ input: e.input }) ?? v
+  }).catch(() => ({ decision: 'deny', reason: 'live-guard-gate: check failed; denied' }))
+}

package/mods/live-guard-gate/kiro/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Live Guard Gate on Kiro
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Degraded
+
+- `PreToolUse`: Kiro documents no confirmation protocol or stdin field names; the whole payload is scanned and a hit is denied.

package/mods/live-guard-gate/kiro/live-guard-gate-pre-tool-use-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "live-guard-gate:PreToolUse",
+      "description": "Asks before live cloud mutations and names the guard agent that should review them.",
+      "trigger": "PreToolUse",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/live-guard-gate/bin/hook.mjs --harness kiro --event PreToolUse"
+      }
+    }
+  ]
+}