@raishin/vanguard-frontier-agentic 3.15.0 → 3.16.0

package/catalog/index.json

@@ -1,12 +1,13 @@
 {
   "name": "vanguard-frontier-agentic",
-  "summary": "Curated cross-harness marketplace for cloud-focused agent skills, agents, rules, MCP references, and delegation workflows.",
+  "summary": "Curated cross-harness marketplace for cloud-focused agent skills, agents, rules, MCP references, delegation workflows, and mods.",
   "last_updated": "2026-05-09",
   "catalogs": {
     "skills": "catalog/skills.json",
     "agents": "catalog/agents.json",
     "rules": "catalog/rules.json",
     "mcp_references": "catalog/mcp-references.json",
-    "workflows": "catalog/workflows.json"
+    "workflows": "catalog/workflows.json",
+    "mods": "catalog/mods.json"
   }
 }

package/catalog/mods.json

@@ -0,0 +1,131 @@
+[
+  {
+    "id": "audit-trail",
+    "name": "Audit Trail",
+    "version": "1.0.0",
+    "description": "Appends one JSON line per tool call to a per-session log with sha256 hashes of the arguments and result.",
+    "reach_level": 1,
+    "events": [
+      "PostToolUse"
+    ],
+    "harnesses": [
+      "claude-code",
+      "codex",
+      "kiro"
+    ],
+    "path": "mods/audit-trail",
+    "footprint": {
+      "env_reads": [
+        "VANGUARD_AUDIT_TRAIL_LOG_DIR",
+        "VANGUARD_AUDIT_TRAIL_SESSION_ID",
+        "VANGUARD_AUDIT_TRAIL_AGENT_ID"
+      ],
+      "file_writes": [
+        ".audit/**"
+      ],
+      "spawns": [],
+      "egress_hosts": []
+    }
+  },
+  {
+    "id": "blast-radius-guard",
+    "name": "Blast Radius Guard",
+    "version": "1.0.0",
+    "description": "Asks before, or blocks, destructive shell commands and writes to system paths.",
+    "reach_level": 0,
+    "events": [
+      "PreToolUse"
+    ],
+    "harnesses": [
+      "claude-code",
+      "codex",
+      "kiro"
+    ],
+    "path": "mods/blast-radius-guard",
+    "footprint": {
+      "env_reads": [
+        "VANGUARD_BLAST_RADIUS_GUARD_MODE",
+        "VANGUARD_BLAST_RADIUS_GUARD_PATTERNS"
+      ],
+      "file_writes": [],
+      "spawns": [],
+      "egress_hosts": []
+    }
+  },
+  {
+    "id": "context-burn",
+    "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.",
+    "reach_level": 1,
+    "events": [
+      "PostToolUse",
+      "SessionStart"
+    ],
+    "harnesses": [
+      "claude-code",
+      "codex",
+      "kiro"
+    ],
+    "path": "mods/context-burn",
+    "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": []
+    }
+  },
+  {
+    "id": "live-guard-gate",
+    "name": "Live Guard Gate",
+    "version": "1.0.0",
+    "description": "Asks before live cloud mutations and names the guard agent that should review them.",
+    "reach_level": 0,
+    "events": [
+      "PreToolUse"
+    ],
+    "harnesses": [
+      "claude-code",
+      "codex",
+      "kiro"
+    ],
+    "path": "mods/live-guard-gate",
+    "footprint": {
+      "env_reads": [],
+      "file_writes": [],
+      "spawns": [],
+      "egress_hosts": []
+    }
+  },
+  {
+    "id": "secret-redactor",
+    "name": "Secret Redactor",
+    "version": "1.0.0",
+    "description": "Asks before tool calls whose input carries a credential and redacts credentials from tool output.",
+    "reach_level": 0,
+    "events": [
+      "PreToolUse",
+      "PostToolUse"
+    ],
+    "harnesses": [
+      "claude-code",
+      "codex",
+      "kiro"
+    ],
+    "path": "mods/secret-redactor",
+    "footprint": {
+      "env_reads": [
+        "VANGUARD_SECRET_REDACTOR_PATTERNS"
+      ],
+      "file_writes": [],
+      "spawns": [],
+      "egress_hosts": []
+    }
+  }
+]

package/mods/README.md

@@ -0,0 +1,220 @@
+# Vanguard Mods
+
+<div align="center">
+
+  <img src="../assets/logos/vanguard-frontier-agentic-logo.png" alt="Vanguard Frontier Agentic" width="140" />
+
+  <p><strong>Less “oops.” More visibility.</strong></p>
+  <p>Tool-call guardrails and observers for Claude Code, Kiro and Codex.</p>
+
+  <p>
+    <a href="#pick-a-mod">Pick a mod</a> &nbsp;·&nbsp;
+    <a href="#get-started">Get started</a> &nbsp;·&nbsp;
+    <a href="#know-the-limits">Know the limits</a> &nbsp;·&nbsp;
+    <a href="#under-the-hood">Under the hood</a>
+  </p>
+
+</div>
+
+---
+
+Skills guide the agent. **Mods inspect its tool calls.** Ask before risky actions,
+redact supported output, or record what happened. Pick what you need—not everything at once.
+
+<a id="pick-a-mod"></a>
+
+## 🧰 Pick your guardrails
+
+| Mod | The job | Reach |
+| --- | --- | --- |
+| [Secret Redactor](secret-redactor/README.md) | Spot credential-shaped input; redact supported output. | L0 |
+| [Blast Radius Guard](blast-radius-guard/README.md) | Ask or deny on destructive commands and system-path writes. | L0 |
+| [Live Guard Gate](live-guard-gate/README.md) | Flag cloud mutations and name guard agents to consult. | L0 |
+| [Context Burn](context-burn/README.md) | Count tool calls; warn on reported context use where supported. | L1 |
+| [Audit Trail](audit-trail/README.md) | Append call hashes and per-session sequence numbers. | L1 |
+
+**Reach is a label, not a sandbox:** L0 = no declared writes/spawns/network;
+L1 = file writes; L2 = subprocesses; L3 = network (warned, not blocked).
+Reads are allowed at L0; starting the Node adapter is not a mod-spawned subprocess.
+
+**Support differs:** Kiro/Codex deny instead of asking and cannot redact output.
+Claude Code Audit Trail needs classic. Classic Post hooks miss failed calls.
+
+<details>
+<summary><strong>🔎 Same mod, different harness? Check the fine print.</strong></summary>
+
+| Mod | Claude Code native | Claude Code classic | Kiro / Codex |
+| --- | --- | --- | --- |
+| Secret Redactor | Ask on input; redact or withhold output | Ask on input; replace successful output only | Deny matching input; no output redaction |
+| Blast Radius Guard | Ask in confirm mode; deny in block mode | Same | Deny in either mode |
+| Live Guard Gate | Ask and name guard agents | Same | Deny and name guard agents |
+| Context Burn | Session context usage and threshold toasts | Tool-call counter only | Tool-call counter only |
+| Audit Trail | Unsupported—use classic | Append after successful calls | Append; Kiro payload interpretation is degraded |
+
+Guards use `PreToolUse`; supported redaction and observers use `PostToolUse`;
+Context Burn also uses `SessionStart`.
+Native equivalents are `tool.check`, `tool.call` and `session.start`.
+
+Kiro's stdin fields are undocumented: guards scan the whole payload if input is
+unrecognized; Audit Trail hashes that payload as arguments and `null` as the result.
+Set `VANGUARD_AUDIT_TRAIL_SESSION_ID` to avoid its shared `unsessioned` fallback.
+See generated `<harness>/UNSUPPORTED.md` for remaining limits.
+
+</details>
+
+---
+
+<a id="get-started"></a>
+
+## 🚀 Get started
+
+Use a local checkout. Command adapters need **Node 22+**; native modules use the
+harness runtime. No service needed.
+
+```bash
+source=/absolute/path/to/vanguard-frontier-agentic
+target=/absolute/path/to/your/project
+mod=blast-radius-guard
+```
+
+> [!IMPORTANT]
+> **Native or classic. Not both for the same mod.** They duplicate checks and can
+> double-count Context Burn. Audit Trail has no native adapter—use classic.
+
+<details>
+<summary><strong>🤖 Claude Code native</strong> — load a plugin root</summary>
+
+```bash
+cd "$target"
+claude --plugin-dir "$source/mods/$mod"
+```
+
+Not for `audit-trail`. Native API: early access. Check the verified build in the
+[implementation notes](#under-the-hood) before upgrading.
+
+</details>
+
+<details>
+<summary><strong>🤖 Claude Code classic</strong> — copy, then merge hooks</summary>
+
+```bash
+mkdir -p "$target/.claude/vanguard-mods/$mod"
+cp -R "$source/mods/$mod/bin" "$source/mods/$mod/lib" "$target/.claude/vanguard-mods/$mod/"
+```
+
+Append `mods/<id>/claude-code/settings.hooks.json` entries under `hooks` in the
+target's `.claude/settings.json`. **Keep existing hooks/settings.** Generated command:
+
+```text
+node "$CLAUDE_PROJECT_DIR/.claude/vanguard-mods/<id>/bin/hook.mjs" --harness claude-code --event <event>
+```
+
+`CLAUDE_PROJECT_DIR` stays at the initial project root, even across worktree changes.
+Observers resolve relative writes from the installed adapter location.
+
+</details>
+
+<details>
+<summary><strong>🔮 Kiro</strong> — copy the adapters and hook JSON</summary>
+
+```bash
+mkdir -p "$target/.kiro/hooks" "$target/.kiro/vanguard-mods/$mod"
+cp -R "$source/mods/$mod/bin" "$source/mods/$mod/lib" "$target/.kiro/vanguard-mods/$mod/"
+cp "$source/mods/$mod/kiro/"*-hook.json "$target/.kiro/hooks/"
+```
+
+Copy only `*-hook.json`, not `UNSUPPORTED.md`. Replace the relative script path
+inside each hook with its **absolute installed path**: hook cwd is undocumented.
+Commands use `--harness kiro --event <event>`; confirmation requests deny with exit 2.
+
+</details>
+
+<details>
+<summary><strong>⚡ Codex</strong> — copy, merge, then review trust</summary>
+
+```bash
+mkdir -p "$target/.codex/vanguard-mods/$mod"
+cp -R "$source/mods/$mod/bin" "$source/mods/$mod/lib" "$target/.codex/vanguard-mods/$mod/"
+```
+
+Append event entries from `mods/<id>/codex/hooks.json` to the target's
+`.codex/hooks.json`, preserving existing hooks. Replace relative script paths with
+**absolute installed paths**; hook cwd is undocumented. Complete Codex's hook trust review.
+
+Commands use `--harness codex --event <event>`; asks deny with exit 2.
+Redactor Post is unsupported; the narrower MCP output field is not substituted.
+
+</details>
+
+**Try it before trusting it:** run ordinary and harmless pattern-matching calls in
+the harness. Inspect the decision, output or observer file—not just exit codes.
+Repeat after path, permission, Node or harness changes.
+
+---
+
+<a id="know-the-limits"></a>
+
+## ⚠️ Guardrails, not guarantees
+
+- **A hook must run to help.** Guards deny handler/input errors; missing Node,
+  moved scripts, startup crashes and timeouts can leave calls unguarded.
+  CLI errors may not block; Kiro IDE handling differs.
+- **Regex is not complete DLP.** Pre checks never rewrite arguments; approved input
+  still reaches the tool. Post redaction does not scrub other logs or network traffic.
+  Redactor errors attempt withholding; classic shape mismatches may be ignored.
+  [Withholding has limits, too](secret-redactor/README.md#limitations).
+- **A review prompt is not authorization.** Live Guard Gate names agents—it never
+  spawns them or verifies production accounts. Guards scan strings, not shell semantics;
+  relative paths stay unresolved. Bypass modes can auto-approve an ask.
+- **Observers are not compliance proof.** Node counters track calls, not tokens or
+  spend; only native Context Burn uses reported context data. Unlocked updates can
+  lose increments. Audit logs are mutable, unsigned and not tamper-evident.
+  Observer failures do not block tools.
+
+<details>
+<summary><strong>🗂️ State files and custom patterns</strong></summary>
+
+- **Context Burn:** `.<harness>/context-burn-status/<session-hash>.json`
+  (`.claude` for Claude Code). Filenames use the full lowercase SHA-256 of the UTF-8
+  session ID, never raw IDs. Missing/empty Node IDs share `unsessioned` state.
+  `VANGUARD_CONTEXT_BURN_STATUS_PATH` is an exact override; sharing it opts out of
+  isolation. Old single-file state is not migrated automatically.
+- **Audit Trail:** `.audit/<UTC-date>/<session>.jsonl`; an earlier file is reused
+  across dates. `VANGUARD_AUDIT_TRAIL_LOG_DIR` overrides the directory.
+- **Footprints disclose defaults, not containment.** Overrides can write outside
+  declared globs; overlap checks do not constrain operator overrides.
+- **Patterns append, never replace.** `VANGUARD_SECRET_REDACTOR_PATTERNS` and
+  `VANGUARD_BLAST_RADIUS_GUARD_PATTERNS` accept extra pattern files. Use absolute paths.
+  Unreadable/invalid configured files deny guards or withhold redactor output.
+  Each mod README documents schemas and environment names.
+
+</details>
+
+<a id="under-the-hood"></a>
+
+## 🔧 Under the hood
+
+`mod.toml` declares support and footprint; `lib/core.mjs` holds shared behavior.
+Edit those sources, `patterns.json`, entries and native modules—not generated adapters.
+The generator produces manifests, shared runtime copies, pattern modules and `catalog/mods.json`.
+
+<details>
+<summary><strong>🛠️ Contributing? Run the gates.</strong></summary>
+
+```bash
+npm run mods:write
+npm run validate:mods
+npm run test:fuzz
+npm run asset-integrity:write  # last generator, on its own
+npm run validate
+```
+
+The Python gate needs **Python 3.11+**. For each supported native mod, also run
+`claude plugin validate mods/<id>` and `claude plugin test mods/<id>` locally;
+CI has no native CLI. Spelling and Markdown lint are separate gates.
+Static checks are not proof that an installed hook runs.
+
+</details>
+
+[Implementation plan](https://github.com/VincentChuWaiChow/vanguard-frontier-agentic/blob/dc8b29c823fb89dc4246413f38a7b82fdd34aa18/.claude/plan/cross-harness-mods.md)
+· [Spec deviations](https://github.com/VincentChuWaiChow/vanguard-frontier-agentic/blob/dc8b29c823fb89dc4246413f38a7b82fdd34aa18/.kiro/specs/cross-harness-mods/deviations.md)

package/mods/audit-trail/README.md

@@ -0,0 +1,70 @@
+# Audit Trail
+
+Appends one JSON line per tool call to a per-session log. It is an honest append log: it makes
+no claim of immutability, carries no signatures, and any process with write access can edit or
+delete the file.
+
+## Reach and declared footprint
+
+**L1 (file writes).** The manifest declares default writes to `.audit/**`, reads
+`VANGUARD_AUDIT_TRAIL_LOG_DIR`, `VANGUARD_AUDIT_TRAIL_SESSION_ID` and
+`VANGUARD_AUDIT_TRAIL_AGENT_ID`, and declares no subprocess spawns or network egress.
+This is capability disclosure, not isolation; the log-directory override can write
+outside the declared default footprint.
+
+## What it records
+
+| Field | Value |
+|---|---|
+| `timestamp` | UTC ISO 8601 time of the hook run |
+| `session_id` | The safe session id (see below) |
+| `agent_id` | `VANGUARD_AUDIT_TRAIL_AGENT_ID`, or `null` |
+| `tool_name` | The payload `tool_name`, or `null` |
+| `args_hash` | SHA-256 of the canonical JSON of `tool_input` (`null` when absent) |
+| `result_hash` | SHA-256 of the canonical JSON of `tool_response` (`null` when absent) |
+| `sequence_number` | 1, 2, 3 ... per session file |
+
+Only hashes are stored, never the arguments or results themselves.
+
+## File layout
+
+`<dir>/<YYYY-MM-DD>/<session>.jsonl`, where `<dir>` defaults to `.audit` and dates are UTC. If
+the session already has a file under an earlier date directory, that file is reused, so the
+sequence does not reset at midnight. A relative `<dir>` resolves against the project root when
+the hook runs from its installed location, otherwise against the working directory.
+
+## Session ids
+
+1. `VANGUARD_AUDIT_TRAIL_SESSION_ID`, when set and non-empty.
+2. The payload `session_id`, when a non-empty string.
+3. Otherwise `unsessioned`.
+
+An id that does not match `[A-Za-z0-9._-]{1,128}` is replaced by the first 32 hex characters of
+its SHA-256, so it can never escape the date directory.
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `VANGUARD_AUDIT_TRAIL_LOG_DIR` | Log directory (default `.audit`). It can point outside the declared `.audit/**` write footprint; that is the operator's choice. |
+| `VANGUARD_AUDIT_TRAIL_SESSION_ID` | Session id override |
+| `VANGUARD_AUDIT_TRAIL_AGENT_ID` | Value for `agent_id` |
+
+## Harness support
+
+| Harness | Status |
+|---|---|
+| Claude Code native | Unsupported: the native API has no file append. Install the classic hook instead. |
+| Claude Code classic | Supported. `PostToolUse` fires only after a tool succeeds, so failed calls are not logged. |
+| Kiro | Degraded: stdin field names are undocumented, so `args_hash` covers the whole payload, `result_hash` hashes `null`, and without a session id env var every session shares the `unsessioned` log. |
+| Codex | Supported. |
+
+## Locking and failure
+
+Each append takes an exclusive `<dir>/<session>.lock` before selecting the session file
+(retrying for up to 2 s). Locks are never automatically stolen or removed based on age.
+After a crash, confirm no writer remains before manually removing its orphaned lock.
+A corrupt or unterminated last line, a lock timeout, or any I/O error exits 1 with a message on stderr and
+appends nothing. A failure is loud but never blocks the tool call.
+
+Requires Node 22+. Install: see `mods/README.md`.

package/mods/audit-trail/bin/hook.mjs

@@ -0,0 +1,65 @@
+// Node hook for audit-trail: appends one JSON line per tool call to a per-session log.
+// An honest append log, not tamper-evident: anything with write access can edit it.
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { runHook, projectPath } from '../lib/runtime.mjs'
+import { buildRecord, lastSequence, rawSessionId, safeSessionId } from '../lib/core.mjs'
+
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+
+// Reuses the earliest date dir that already holds this session, so the sequence never
+// resets at midnight.
+// ponytail: scans every date dir, O(days); index it if slow.
+function logFile(base, sid, today) {
+  const days = existsSync(base) ? readdirSync(base).filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d)).sort() : []
+  const hit = days.find((d) => existsSync(join(base, d, `${sid}.jsonl`)))
+  return join(base, hit ?? today, `${sid}.jsonl`)
+}
+
+// Never steal a lock: its age does not prove the owner is dead. Explicit recovery is safer
+// than racing two writers after an automatic stale-lock takeover.
+function acquire(lock, file) {
+  const deadline = Date.now() + 2000
+  for (;;) {
+    try {
+      return openSync(lock, 'wx')
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+    }
+    if (Date.now() > deadline) throw new Error(`audit-trail: could not lock ${file} within 2s`)
+    sleep(20)
+  }
+}
+
+// Read directly instead of exists-then-read, so there is no check/use gap.
+function readIfExists(file) {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return ''
+    throw err
+  }
+}
+
+async function PostToolUse(payload, ctx) {
+  const base = projectPath(process.env.VANGUARD_AUDIT_TRAIL_LOG_DIR || '.audit', ctx.harness, import.meta.dirname)
+  const sid = await safeSessionId(rawSessionId(process.env.VANGUARD_AUDIT_TRAIL_SESSION_ID, payload))
+  const timestamp = new Date().toISOString()
+  mkdirSync(base, { recursive: true })
+  // Serialize session-file selection as well as appends, including across midnight.
+  const lock = join(base, `${sid}.lock`)
+  const fd = acquire(lock, lock)
+  try {
+    const file = logFile(base, sid, timestamp.slice(0, 10))
+    mkdirSync(dirname(file), { recursive: true })
+    const sequence = lastSequence(readIfExists(file), file) + 1
+    const agentId = process.env.VANGUARD_AUDIT_TRAIL_AGENT_ID
+    const record = await buildRecord({ timestamp, sessionId: sid, agentId, payload, harness: ctx.harness, sequence })
+    appendFileSync(file, JSON.stringify(record) + '\n')
+  } finally {
+    closeSync(fd)
+    unlinkSync(lock)
+  }
+}
+
+process.exitCode = await runHook({ name: 'audit-trail', handlers: { PostToolUse } })

package/mods/audit-trail/claude-code/UNSUPPORTED.md

@@ -0,0 +1,11 @@
+# Audit Trail on Claude Code
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## Unsupported
+
+- `native`: The native mod API has no file append; rewriting the whole log would break append-only writes. Install the classic hook instead.
+
+## Degraded
+
+- `classic`: Classic PostToolUse fires only after a tool succeeds, so failed tool calls are not logged.

package/mods/audit-trail/claude-code/settings.hooks.json

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

package/mods/audit-trail/codex/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/vanguard-mods/audit-trail/bin/hook.mjs --harness codex --event PostToolUse"
+          }
+        ]
+      }
+    ]
+  }
+}

package/mods/audit-trail/kiro/UNSUPPORTED.md

@@ -0,0 +1,7 @@
+# Audit Trail on Kiro
+
+<!-- Generated by scripts/generate-mods.mjs from mod.toml. Do not edit. -->
+
+## 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.

package/mods/audit-trail/kiro/audit-trail-post-tool-use-hook.json

@@ -0,0 +1,14 @@
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "audit-trail:PostToolUse",
+      "description": "Appends one JSON line per tool call to a per-session log with sha256 hashes of the arguments and result.",
+      "trigger": "PostToolUse",
+      "action": {
+        "type": "command",
+        "command": "node .kiro/vanguard-mods/audit-trail/bin/hook.mjs --harness kiro --event PostToolUse"
+      }
+    }
+  ]
+}