failproofai 0.0.13-beta.0 → 0.0.13-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.13-beta.0",
+  "version": "0.0.13-beta.2",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -22,7 +22,7 @@
   "scripts": {
     "predev": "bun run build:cli && bun link",
     "dev": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/dev.ts --port 8020",
-    "build:cli": "bun build --target=node --format=esm --outfile=dist/cli.mjs bin/failproofai.mjs --external posthog-node && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli.mjs','utf8');fs.writeFileSync('dist/cli.mjs',c.replace('#!/usr/bin/env bun','#!/usr/bin/env node').replace('// @bun\\n',''))\"",
+    "build:cli": "bun build --target=node --format=esm --outfile=dist/cli.mjs bin/failproofai.mjs --external posthog-node --external sql.js && node -e \"const fs=require('fs');const c=fs.readFileSync('dist/cli.mjs','utf8');fs.writeFileSync('dist/cli.mjs',c.replace('#!/usr/bin/env bun','#!/usr/bin/env node').replace('// @bun\\n',''))\"",
     "build": "bun build --target=node --format=cjs --outfile=dist/index.js src/index.ts && bun run build:cli && bun --bun next build && node -e \"const {cpSync}=require('fs');cpSync('.next/static','.next/standalone/.next/static',{recursive:true});\" && node scripts/prune-standalone.mjs",
     "prestart": "bun run build:cli && bun link",
     "start": "FAILPROOFAI_TELEMETRY_DISABLED=1 bun scripts/start.ts",
@@ -99,7 +99,9 @@
   "dependencies": {
     "html-to-image": "^1.11.13",
     "html2canvas": "^1.4.1",
-    "posthog-node": "^5.37.1"
+    "posthog-node": "^5.37.1",
+    "sql.js": "^1.14.1",
+    "yaml": "^2.9.0"
   },
   "overrides": {
     "postcss": "8.5.14",

package/src/audit/cli-adapters/hermes.ts

@@ -0,0 +1,58 @@
+/**
+ * Hermes (hermes-agent) transcript adapter — AUDIT-ONLY (Pillar 2).
+ *
+ * Hermes keeps every gateway user's sessions in one SQLite DB. We read it
+ * directly via the bundled sql.js reader (lib/hermes-projects.ts enumerates the
+ * `sessions` table; lib/hermes-sessions.ts parses each session's `messages`),
+ * producing the same LogEntry[] shape the other adapters do — so
+ * `logEntriesToEvents` handles the rest.
+ *
+ * Gateway sessions have no `cwd` (Slack/Telegram runs aren't in a repo), so they
+ * group by `source` (slack/telegram/cli/cron) instead of working directory.
+ */
+import { getHermesSessions } from "../../../lib/hermes-projects";
+import { getHermesSessionLog } from "../../../lib/hermes-sessions";
+import type { NormalizedToolEvent, TranscriptMetadata } from "../types";
+import type { ListOpts } from "./claude";
+import { logEntriesToEvents } from "./shared";
+
+export async function listHermesTranscriptMetadata(
+  opts: ListOpts = {},
+): Promise<TranscriptMetadata[]> {
+  // `audit --project <cwd>` filters on working directory; gateway sessions have
+  // none, so Hermes contributes nothing to a cwd-scoped audit.
+  if (opts.projects && opts.projects.length > 0) return [];
+
+  const sinceMs = opts.sinceMs ?? 0;
+  const sessions = await getHermesSessions();
+  const out: TranscriptMetadata[] = [];
+  for (const s of sessions) {
+    if (s.mtimeMs < sinceMs) continue;
+    if (s.messageCount <= 0 && !s.hasMessages) continue; // empty → no events (message_count can lag; trust real messages)
+    out.push({
+      cli: "hermes",
+      // Group by channel; gateway sessions are cwd-less.
+      projectName: s.source ? `hermes:${s.source}` : "hermes",
+      sessionId: s.sessionId,
+      transcriptPath: `hermes://${s.sessionId}`,
+      mtimeMs: s.mtimeMs,
+      // message_count is stable for an ended session, so (mtime, size) forms a
+      // real per-transcript cache key — an ended session is parsed once.
+      sizeBytes: s.messageCount,
+    });
+  }
+  return out;
+}
+
+export async function streamHermesEvents(
+  meta: TranscriptMetadata,
+): Promise<NormalizedToolEvent[]> {
+  const log = await getHermesSessionLog(meta.sessionId);
+  if (!log) return [];
+  return logEntriesToEvents(log.entries, {
+    cli: "hermes",
+    sessionId: meta.sessionId,
+    transcriptPath: meta.transcriptPath,
+    cwd: log.cwd ?? "",
+  });
+}

package/src/audit/cli-adapters/index.ts

@@ -18,6 +18,7 @@ import { listCursorTranscriptMetadata, streamCursorEvents } from "./cursor";
 import { listOpenCodeTranscriptMetadata, streamOpenCodeEvents } from "./opencode";
 import { listPiTranscriptMetadata, streamPiEvents } from "./pi";
 import { listGeminiTranscriptMetadata, streamGeminiEvents } from "./gemini";
+import { listHermesTranscriptMetadata, streamHermesEvents } from "./hermes";
 
 export type { ListOpts };
 
@@ -63,6 +64,11 @@ export const ADAPTERS: Record<IntegrationType, CliAdapter> = {
     listTranscripts: listGeminiTranscriptMetadata,
     streamEvents: streamGeminiEvents,
   },
+  hermes: {
+    cli: "hermes",
+    listTranscripts: listHermesTranscriptMetadata,
+    streamEvents: streamHermesEvents,
+  },
 };
 
 export function getAdapter(cli: IntegrationType): CliAdapter {

package/src/hooks/builtin-policies.ts

@@ -1088,7 +1088,19 @@ function warnBackgroundProcess(ctx: PolicyContext): PolicyResult {
 
 // -- Workflow (Stop event) policies --
 
+/**
+ * Claude Code plan mode (permission_mode: "plan") is research-and-plan-only — the
+ * agent makes no commits, pushes, or PRs by design. The Stop-workflow gates below
+ * all assume the agent produced code changes, so in plan mode they demand actions
+ * plan mode forbids (e.g. a push with nothing to push). Skip them there. Only Claude
+ * reports "plan" today; every other CLI resolves to "default".
+ */
+function isPlanMode(ctx: PolicyContext): boolean {
+  return ctx.session?.permissionMode === "plan";
+}
+
 function requireCommitBeforeStop(ctx: PolicyContext): PolicyResult {
+  if (isPlanMode(ctx)) return allow("Plan mode — no changes made, skipping commit check.");
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow("No working directory available, skipping commit check.");
 
@@ -1111,6 +1123,7 @@ function requireCommitBeforeStop(ctx: PolicyContext): PolicyResult {
 }
 
 function requirePushBeforeStop(ctx: PolicyContext): PolicyResult {
+  if (isPlanMode(ctx)) return allow("Plan mode — no changes made, skipping push check.");
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow("No working directory available, skipping push check.");
 
@@ -1205,6 +1218,7 @@ function requirePushBeforeStop(ctx: PolicyContext): PolicyResult {
 }
 
 function requirePrBeforeStop(ctx: PolicyContext): PolicyResult {
+  if (isPlanMode(ctx)) return allow("Plan mode — no changes made, skipping PR check.");
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow("No working directory available, skipping PR check.");
 
@@ -1298,6 +1312,7 @@ function requirePrBeforeStop(ctx: PolicyContext): PolicyResult {
 }
 
 function requireNoConflictsBeforeStop(ctx: PolicyContext): PolicyResult {
+  if (isPlanMode(ctx)) return allow("Plan mode — no changes made, skipping conflict check.");
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow("No working directory available, skipping conflict check.");
 
@@ -1396,6 +1411,7 @@ function requireNoConflictsBeforeStop(ctx: PolicyContext): PolicyResult {
 }
 
 function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
+  if (isPlanMode(ctx)) return allow("Plan mode — no changes made, skipping CI check.");
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow("No working directory available, skipping CI check.");
 

package/src/hooks/handler.ts

@@ -13,12 +13,14 @@ import type {
   CursorHookEventType,
   PiHookEventType,
   GeminiHookEventType,
+  HermesHookEventType,
 } from "./types";
 import {
   CODEX_EVENT_MAP,
   CURSOR_EVENT_MAP,
   PI_EVENT_MAP,
   GEMINI_EVENT_MAP,
+  HERMES_EVENT_MAP,
 } from "./types";
 import { canonicalizeToolName, canonicalizeToolInput } from "./tool-name-canonicalize";
 import type { PolicyFunction, PolicyResult } from "./policy-types";
@@ -65,6 +67,12 @@ function canonicalizeEventType(raw: string, cli: IntegrationType): HookEventType
     const mapped = GEMINI_EVENT_MAP[raw as GeminiHookEventType];
     if (mapped) return mapped;
   }
+  if (cli === "hermes") {
+    // Hermes sends snake_case event names (pre_tool_call, on_session_start, …);
+    // map to PascalCase. Has no turn-end Stop event, so no Stop mapping exists.
+    const mapped = HERMES_EVENT_MAP[raw as HermesHookEventType];
+    if (mapped) return mapped;
+  }
   // claude / copilot / unknown — already PascalCase, pass through.
   // HOOK_EVENT_TYPES type-checks downstream.
   return raw as HookEventType;

package/src/hooks/install-prompt.ts

@@ -11,8 +11,8 @@
  */
 import * as readline from "node:readline";
 import { BUILTIN_POLICIES } from "./builtin-policies";
-import { detectInstalledClis, getIntegration } from "./integrations";
-import { INTEGRATION_TYPES, type IntegrationType } from "./types";
+import { detectInstalledClis, getIntegration, listInstallableIds } from "./integrations";
+import { type IntegrationType } from "./types";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 
@@ -139,7 +139,11 @@ export function buildCliMenuOptions(
 ): { options: CliMenuOption[]; undetected: IntegrationType[] } {
   const undetected: IntegrationType[] =
     action === "install"
-      ? INTEGRATION_TYPES.filter((id) => !detected.includes(id))
+      ? // Only CLIs that support live-hook install — a future audit-only CLI
+        // (one with no INTEGRATIONS entry) has no install path and must not
+        // appear as a forward-install option. (hermes IS installable, so it
+        // correctly appears here.)
+        listInstallableIds().filter((id) => !detected.includes(id))
       : [];
 
   const options: CliMenuOption[] = [];

package/src/hooks/integrations.ts

@@ -11,6 +11,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
+import { parseDocument, type Document } from "yaml";
 import {
   HOOK_EVENT_TYPES,
   HOOK_SCOPES,
@@ -27,6 +28,8 @@ import {
   PI_HOOK_SCOPES,
   GEMINI_HOOK_EVENT_TYPES,
   GEMINI_HOOK_SCOPES,
+  HERMES_HOOK_EVENT_TYPES,
+  HERMES_HOOK_SCOPES,
   FAILPROOFAI_HOOK_MARKER,
   INTEGRATION_TYPES,
   type IntegrationType,
@@ -50,6 +53,23 @@ function writeJsonFile(path: string, data: Record<string, unknown>): void {
   writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf8");
 }
 
+/** Read a YAML file as a `Document` so writes round-trip the user's other keys +
+ *  comments (a plain parse→stringify would strip comments). Empty / missing /
+ *  corrupt → an empty Document. Used by the Hermes integration, whose config
+ *  lives in `~/.hermes/config.yaml`. */
+function readYamlDoc(path: string): Document {
+  try {
+    return existsSync(path) ? parseDocument(readFileSync(path, "utf8")) : parseDocument("");
+  } catch {
+    return parseDocument("");
+  }
+}
+
+function writeYamlDoc(path: string, doc: Document): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, doc.toString(), "utf8");
+}
+
 function isMarkedHook(hook: unknown): boolean {
   if (!hook || typeof hook !== "object") return false;
   const h = hook as Record<string, unknown>;
@@ -1423,9 +1443,146 @@ export const gemini: Integration = {
   },
 };
 
+// ── Hermes (hermes-agent) — live hooks (Pillar 1) ────────────────────────────
+//
+// External-command CLI like codex/cursor, but its config is YAML
+// (`~/.hermes/config.yaml`) under a `hooks:` map, so the I/O layer uses the yaml
+// Document API (comment-preserving). Flat per-event arrays like cursor:
+// `hooks: { pre_tool_call: [ { command, timeout, <marker> } ], … }`. Hermes
+// reads a `{"decision":"block",…}` JSON response on stdout (see
+// policy-evaluator.ts); exit codes are ignored. User-scope only.
+
+/** One hook entry as stored under a `hooks:` event key in config.yaml. */
+interface HermesHookEntry {
+  command: string;
+  timeout?: number;
+  [key: string]: unknown;
+}
+
+export const hermes: Integration = {
+  id: "hermes",
+  displayName: "Hermes",
+  scopes: HERMES_HOOK_SCOPES,
+  eventTypes: HERMES_HOOK_EVENT_TYPES,
+
+  // Hermes config is USER-scope only (`~/.hermes/config.yaml`); there is no
+  // project/local file, so scope/cwd are irrelevant here.
+  getSettingsPath() {
+    return resolve(homedir(), ".hermes", "config.yaml");
+  },
+
+  readSettings(settingsPath) {
+    // Return the yaml Document (cast) so writeHookEntries/writeSettings can
+    // round-trip it while preserving the user's other keys + comments.
+    return readYamlDoc(settingsPath) as unknown as Record<string, unknown>;
+  },
+
+  writeSettings(settingsPath, settings) {
+    writeYamlDoc(settingsPath, settings as unknown as Document);
+  },
+
+  buildHookEntry(binaryPath, eventType, scope) {
+    // No matcher → fires for ALL tools / all platforms (slack/telegram/cli/cron)
+    // and internal subagents. `timeout` is in seconds; Hermes runs the command
+    // via shlex.split (shell=false).
+    const command =
+      scope === "project"
+        ? `npx -y failproofai --hook ${eventType} --cli hermes`
+        : `"${binaryPath}" --hook ${eventType} --cli hermes`;
+    return {
+      command,
+      timeout: 30,
+      [FAILPROOFAI_HOOK_MARKER]: true,
+    };
+  },
+
+  isFailproofaiHook: isMarkedHook,
+
+  writeHookEntries(settings, binaryPath, scope) {
+    const doc = settings as unknown as Document;
+    // Read the current hooks map as plain JS, then re-set ONLY the `hooks` key —
+    // preserving comments on every other part of config.yaml.
+    const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+    const hooks: Record<string, HermesHookEntry[]> =
+      js.hooks && typeof js.hooks === "object" ? js.hooks : {};
+
+    for (const eventType of HERMES_HOOK_EVENT_TYPES) {
+      const entry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as HermesHookEntry;
+      const arr = Array.isArray(hooks[eventType]) ? hooks[eventType] : [];
+      const idx = arr.findIndex((h) => isMarkedHook(h));
+      if (idx >= 0) arr[idx] = entry;
+      else arr.push(entry);
+      hooks[eventType] = arr;
+    }
+    doc.set("hooks", hooks);
+    // The headless gateway has no TTY to answer Hermes's first-use hook-consent
+    // prompt, so auto-accept declared hooks. Tradeoff: also auto-accepts any
+    // other hook the operator adds; a targeted `shell-hooks-allowlist.json`
+    // pre-seed is a future refinement.
+    doc.set("hooks_auto_accept", true);
+  },
+
+  removeHooksFromFile(settingsPath) {
+    if (!existsSync(settingsPath)) return 0;
+    const doc = readYamlDoc(settingsPath);
+    const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+    const hooks = js.hooks;
+
+    let removed = 0;
+    if (hooks && typeof hooks === "object") {
+      for (const eventType of Object.keys(hooks)) {
+        const entries = hooks[eventType];
+        if (!Array.isArray(entries)) continue;
+        const before = entries.length;
+        const filtered = entries.filter((h) => !isMarkedHook(h));
+        removed += before - filtered.length;
+        if (filtered.length === 0) delete hooks[eventType];
+        else hooks[eventType] = filtered;
+      }
+      if (removed > 0) {
+        if (Object.keys(hooks).length === 0) doc.delete("hooks");
+        else doc.set("hooks", hooks);
+      }
+    }
+
+    // Always drop our headless-consent flag on uninstall — even if the hooks were
+    // already removed manually — so it can't silently auto-accept future operator
+    // hooks. `doc.delete` returns true iff the key was present.
+    const droppedAutoAccept = doc.delete("hooks_auto_accept");
+    if (removed > 0 || droppedAutoAccept) writeYamlDoc(settingsPath, doc);
+    return removed;
+  },
+
+  hooksInstalledInSettings(scope, cwd) {
+    const settingsPath = this.getSettingsPath(scope, cwd);
+    if (!existsSync(settingsPath)) return false;
+    try {
+      const doc = readYamlDoc(settingsPath);
+      const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+      const hooks = js.hooks;
+      if (!hooks || typeof hooks !== "object") return false;
+      for (const entries of Object.values(hooks)) {
+        if (Array.isArray(entries) && entries.some((h) => isMarkedHook(h))) return true;
+      }
+    } catch {
+      // Corrupt config — treat as not installed.
+    }
+    return false;
+  },
+
+  detectInstalled() {
+    return binaryExists("hermes");
+  },
+};
+
 // ── Registry ────────────────────────────────────────────────────────────────
 
-const INTEGRATIONS: Record<IntegrationType, Integration> = {
+// `Partial` is kept (not every IntegrationType is guaranteed installable for
+// LIVE hooks / Pillar 1) so a future audit-only CLI can omit its entry without a
+// type error. `hermes` now has BOTH an audit adapter
+// (src/audit/cli-adapters/hermes.ts) AND live-hook install support, so it is
+// registered here.
+const INTEGRATIONS: Partial<Record<IntegrationType, Integration>> = {
   claude: claudeCode,
   codex,
   copilot,
@@ -1433,21 +1590,38 @@ const INTEGRATIONS: Record<IntegrationType, Integration> = {
   opencode,
   pi,
   gemini,
+  hermes,
 };
 
 export function getIntegration(id: IntegrationType): Integration {
   const integration = INTEGRATIONS[id];
   if (!integration) {
-    throw new Error(`Unknown integration: ${id}. Valid: ${INTEGRATION_TYPES.join(", ")}`);
+    // A future audit-only CLI (one with an audit adapter but no INTEGRATIONS
+    // entry) reaches here when someone tries to install live hooks for it. Be
+    // explicit rather than "unknown integration". (hermes is NOT audit-only — it
+    // has a live-hook entry — so it never reaches this branch.)
+    throw new Error(
+      `"${id}" is audit-only — live-hook install is not supported for it yet. Installable: ${listInstallableIds().join(", ")}`,
+    );
   }
   return integration;
 }
 
+/** IntegrationTypes that support live-hook install (i.e. have an INTEGRATIONS
+ *  entry). Any audit-only CLI (one with an audit adapter but no hook install)
+ *  is excluded so it never appears in install menus. */
+export function listInstallableIds(): IntegrationType[] {
+  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id] !== undefined);
+}
+
 export function listIntegrations(): Integration[] {
-  return INTEGRATION_TYPES.map((id) => INTEGRATIONS[id]);
+  return INTEGRATION_TYPES.map((id) => INTEGRATIONS[id]).filter(
+    (i): i is Integration => i !== undefined,
+  );
 }
 
-/** Detect which agent CLIs are installed on PATH. */
+/** Detect which agent CLIs are installed on PATH. Only considers CLIs that
+ *  support live-hook install (audit-only CLIs have no INTEGRATIONS entry). */
 export function detectInstalledClis(): IntegrationType[] {
-  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id].detectInstalled());
+  return INTEGRATION_TYPES.filter((id) => INTEGRATIONS[id]?.detectInstalled());
 }

package/src/hooks/policy-evaluator.ts

@@ -256,6 +256,25 @@ export async function evaluatePolicies(
         };
       }
 
+      // Hermes: the block contract is `{"decision":"block","reason"}` on stdout;
+      // Hermes IGNORES exit codes, so the JSON is the only channel. This one
+      // return covers every Hermes event we install (PreToolUse / PostToolUse /
+      // SubagentStop) — there is no Stop/turn-end event to special-case (Hermes
+      // has no turn boundary; the 5 require-*-before-stop builtins never fire for
+      // it — see CLAUDE.md / the audit plan). A block on PreToolUse stops the
+      // tool before it runs, regardless of the originating platform
+      // (slack/telegram/cli/cron) or subagent.
+      if (session?.cli === "hermes") {
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify({ decision: "block", reason: blockedMessage }),
+          stderr: "",
+          policyName: policy.name,
+          reason,
+          decision: "deny",
+        };
+      }
+
       // OpenCode: `session.idle` is a notification-only bus event — by the
       // time the plugin handler fires, OpenCode has already gone idle and
       // throwing from the handler does not force-retry. The only working
@@ -552,6 +571,29 @@ export async function evaluatePolicies(
       };
     }
 
+    // Hermes: no additional-context channel on any event (the only actionable
+    // response is `{"decision":"block"}`). So instruct degrades to allow +
+    // log — we emit a non-blocking `{decision:"allow", reason}` (Hermes lets
+    // the tool run) and surface the note on stderr for the operator's logs.
+    // Documented limitation; there is no Stop event to force-retry into.
+    if (session?.cli === "hermes") {
+      const stderrMsg = instructEntries
+        .map((e) => `[failproofai] ${e.policyName}: ${e.reason}`)
+        .join("\n");
+      return {
+        exitCode: 0,
+        stdout: JSON.stringify({
+          decision: "allow",
+          reason: `Instruction from failproofai: ${combined}`,
+        }),
+        stderr: stderrMsg + "\n",
+        policyName: policyNames[0],
+        policyNames,
+        reason: combined,
+        decision: "instruct",
+      };
+    }
+
     // OpenCode: same rationale as the deny branch above — emit
     // additionalContext so the shim submits a follow-up via
     // client.session.prompt instead of throwing into a dead handler.

package/src/hooks/resolve-transcript-path.ts

@@ -63,6 +63,10 @@ export function resolveTranscriptPath(
       return findGeminiTranscript(sessionId) ?? undefined;
     case "opencode":
       return `opencode-db://${sessionId}`;
+    case "hermes":
+      // Hermes live-hook payloads carry no transcript file; the audit path
+      // reads sessions straight from ~/.hermes/state.db (see hermes-sessions.ts).
+      return undefined;
     default:
       return undefined;
   }

package/src/hooks/tool-name-canonicalize.ts

@@ -15,6 +15,8 @@ import {
   PI_TOOL_MAP,
   PI_TOOL_INPUT_MAP,
   GEMINI_TOOL_MAP,
+  HERMES_TOOL_MAP,
+  HERMES_TOOL_INPUT_MAP,
 } from "./types";
 
 /**
@@ -33,6 +35,7 @@ export function canonicalizeToolName(
   if (cli === "gemini") return GEMINI_TOOL_MAP[raw] ?? raw;
   if (cli === "opencode") return OPENCODE_TOOL_MAP[raw] ?? raw;
   if (cli === "pi") return PI_TOOL_MAP[raw] ?? raw;
+  if (cli === "hermes") return HERMES_TOOL_MAP[raw] ?? raw;
   return raw;
 }
 
@@ -56,6 +59,9 @@ export function canonicalizeToolInput(
   let perToolMap: Record<string, string> | undefined;
   if (cli === "opencode") perToolMap = OPENCODE_TOOL_INPUT_MAP[toolName];
   else if (cli === "pi") perToolMap = PI_TOOL_INPUT_MAP[toolName];
+  // Hermes read_file/write_file/patch deliver the file path as `path`; map it to
+  // `file_path` so path/content builtins fire (verified against a live state.db).
+  else if (cli === "hermes") perToolMap = HERMES_TOOL_INPUT_MAP[toolName];
   if (!perToolMap) return rawInput;
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(rawInput as Record<string, unknown>)) {

package/src/hooks/types.ts

@@ -5,7 +5,7 @@
 export const HOOK_SCOPES = ["user", "project", "local"] as const;
 export type HookScope = (typeof HOOK_SCOPES)[number];
 
-export const INTEGRATION_TYPES = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"] as const;
+export const INTEGRATION_TYPES = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini", "hermes"] as const;
 export type IntegrationType = (typeof INTEGRATION_TYPES)[number];
 
 export const CODEX_HOOK_SCOPES = ["user", "project"] as const;
@@ -61,6 +61,72 @@ export const CODEX_TOOL_MAP: Record<string, string> = {
   write_stdin: "Bash",
 };
 
+// ── Hermes (hermes-agent) ───────────────────────────────────────────────────
+//
+// Hermes supports BOTH audit (Pillar 2) and live hooks (Pillar 1). This tool
+// map is consumed by the audit adapter (via `logEntriesToEvents`) AND the
+// live-hook handler, both through `canonicalizeToolName`. Tool names are the
+// granular toolset tools verified
+// against a live ~/.hermes/state.db (frequency in a real gateway session:
+// terminal 574, read_file 124, patch 94, write_file 54, web_search 42, …).
+// Names with a Claude canonical are mapped so builtin policies fire; Hermes-
+// specific tools (skill_view, cronjob, browser_*, memory, session_search,
+// clarify, process) pass through unchanged so they still appear in the audit,
+// just unmatched by builtin policies.
+export const HERMES_TOOL_MAP: Record<string, string> = {
+  terminal: "Bash",
+  bash: "Bash",
+  read_file: "Read",
+  write_file: "Write",
+  patch: "Edit",
+  web_search: "WebSearch",
+  web_extract: "WebFetch",
+  search_files: "Grep",
+  todo: "TodoWrite",
+};
+
+// Hermes tool-INPUT key canonicalization, keyed by the *canonical* tool name
+// (the handler canonicalizes the name before calling canonicalizeToolInput).
+// Verified against a live ~/.hermes/state.db: read_file / write_file / patch
+// deliver the file path as `path`, but Claude builtins read `file_path`
+// (block-env-files, block-secrets-write, block-read-outside-cwd) — so map it.
+// write_file's `content`, patch's `old_string`/`new_string`, and search_files'
+// `pattern`/`path` are already canonical, so Grep needs no entry. Mirrors
+// PI_TOOL_INPUT_MAP (Pi has the same `path` → `file_path` shape).
+export const HERMES_TOOL_INPUT_MAP: Record<string, Record<string, string>> = {
+  Read: { path: "file_path" },
+  Write: { path: "file_path" },
+  Edit: { path: "file_path" },
+};
+
+// Hermes live-hook (Pillar 1) events + scopes. Hermes fires these snake_case
+// events with a JSON payload on stdin; the command we install runs
+// `failproofai --hook <event> --cli hermes`. Config is USER-scope only
+// (`~/.hermes/config.yaml`; Hermes has no project scope). `pre_tool_call` is the
+// core deny point — it fires for tool calls from every source
+// (slack/telegram/cli/cron) and internal subagents, so a single install
+// intercepts all platforms. Hermes has NO turn-end `Stop` event, so the
+// `require-*-before-stop` builtins never fire for it (see the audit plan).
+export const HERMES_HOOK_SCOPES = ["user"] as const;
+export type HermesHookScope = (typeof HERMES_HOOK_SCOPES)[number];
+
+export const HERMES_HOOK_EVENT_TYPES = [
+  "pre_tool_call",
+  "post_tool_call",
+  "on_session_start",
+  "on_session_end",
+  "subagent_stop",
+] as const;
+export type HermesHookEventType = (typeof HERMES_HOOK_EVENT_TYPES)[number];
+
+export const HERMES_EVENT_MAP: Record<HermesHookEventType, HookEventType> = {
+  pre_tool_call: "PreToolUse",
+  post_tool_call: "PostToolUse",
+  on_session_start: "SessionStart",
+  on_session_end: "SessionEnd",
+  subagent_stop: "SubagentStop",
+};
+
 // ── GitHub Copilot CLI ─────────────────────────────────────────────────────
 //
 // Copilot CLI accepts two payload formats. We install with PascalCase event