failproofai 1.0.5 → 1.0.6-beta.1

package/dist/worker.mjs

@@ -3483,7 +3483,7 @@ function parsePackPolicyName(canonicalName) {
 }
 
 // package.json
-var version = "1.0.5";
+var version = "1.0.6-beta.1";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -6388,36 +6388,66 @@ var init_pi_projects = __esm(() => {
 });
 
 // lib/hermes-profiles.ts
-import { readdirSync as readdirSync3 } from "node:fs";
+import { existsSync as existsSync9, readdirSync as readdirSync3 } from "node:fs";
 import { homedir as homedir10 } from "node:os";
 import { basename as basename2, dirname as dirname3, join as join11, resolve as resolve8 } from "node:path";
 function hermesRoot() {
   const env = (process.env.HERMES_HOME || "").trim();
   if (env) {
-    const home = resolve8(env);
+    let home = resolve8(env);
     const parent = dirname3(home);
     if (basename2(parent) === PROFILES_DIR)
-      return dirname3(parent);
+      home = dirname3(parent);
+    const base = basename2(home);
+    if (base === STANDARD_HOME || base.startsWith(SIBLING_HOME_PREFIX)) {
+      return join11(dirname3(home), STANDARD_HOME);
+    }
     return home;
   }
-  return join11(homedir10(), ".hermes");
+  return join11(homedir10(), STANDARD_HOME);
+}
+function uniqueProfileName(preferred, seen) {
+  if (!seen.has(preferred))
+    return preferred;
+  const base = `${preferred}-home`;
+  if (!seen.has(base))
+    return base;
+  let suffix = 2;
+  while (seen.has(`${base}-${suffix}`))
+    suffix += 1;
+  return `${base}-${suffix}`;
 }
 function listHermesProfiles() {
   const root = hermesRoot();
   const out = [{ name: HERMES_DEFAULT_PROFILE, home: root }];
   const seen = new Set([HERMES_DEFAULT_PROFILE]);
-  let names;
+  let names = [];
   try {
     names = readdirSync3(join11(root, PROFILES_DIR), { withFileTypes: true }).filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith(".")).map((e) => e.name).sort();
-  } catch {
-    return out;
-  }
+  } catch {}
   for (const name of names) {
     if (seen.has(name))
       continue;
     seen.add(name);
     out.push({ name, home: join11(root, PROFILES_DIR, name) });
   }
+  if (basename2(root) !== STANDARD_HOME)
+    return out;
+  let siblings = [];
+  const parent = dirname3(root);
+  try {
+    siblings = readdirSync3(parent, { withFileTypes: true }).filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && entry.name.startsWith(SIBLING_HOME_PREFIX) && entry.name.length > SIBLING_HOME_PREFIX.length && existsSync9(join11(parent, entry.name, "config.yaml"))).map((entry) => ({
+      name: entry.name.slice(SIBLING_HOME_PREFIX.length),
+      home: join11(parent, entry.name)
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return out;
+  }
+  for (const sibling of siblings) {
+    const name = uniqueProfileName(sibling.name, seen);
+    seen.add(name);
+    out.push({ name, home: sibling.home });
+  }
   return out;
 }
 function hermesProjectName(profile, source) {
@@ -6443,7 +6473,7 @@ function hermesProjectNameCandidates(name) {
   out.push({ profile: HERMES_DEFAULT_PROFILE, source: rest });
   return out;
 }
-var PROFILES_DIR = "profiles", HERMES_DEFAULT_PROFILE = "default";
+var PROFILES_DIR = "profiles", STANDARD_HOME = ".hermes", SIBLING_HOME_PREFIX = ".hermes-", HERMES_DEFAULT_PROFILE = "default";
 var init_hermes_profiles = () => {};
 
 // lib/format-duration.ts
@@ -6765,7 +6795,7 @@ var init_hermes_projects = __esm(() => {
 });
 
 // lib/openclaw-db.ts
-import { existsSync as existsSync9 } from "node:fs";
+import { existsSync as existsSync10 } from "node:fs";
 import { join as join13 } from "node:path";
 function str(value) {
   return typeof value === "string" && value.length > 0 ? value : undefined;
@@ -6785,7 +6815,7 @@ function listOpenClawDatabases(home, agentIds) {
   const out = [];
   for (const agentId of agentIds) {
     const dbPath = join13(home, "agents", agentId, "agent", DB_NAME);
-    if (existsSync9(dbPath))
+    if (existsSync10(dbPath))
       out.push({ agentId, dbPath });
   }
   return out;
@@ -8962,13 +8992,13 @@ var init_log_entries = __esm(() => {
 });
 
 // lib/codex-sessions.ts
-import { readFileSync as readFileSync8, readdirSync as readdirSync7, existsSync as existsSync10, writeFileSync as writeFileSync4, mkdirSync as mkdirSync5, statSync as statSync10 } from "node:fs";
+import { readFileSync as readFileSync8, readdirSync as readdirSync7, existsSync as existsSync11, writeFileSync as writeFileSync4, mkdirSync as mkdirSync5, statSync as statSync10 } from "node:fs";
 import { readFile as readFile11 } from "node:fs/promises";
 import { dirname as dirname4, join as join24 } from "node:path";
 import { homedir as homedir16 } from "node:os";
 function readCache() {
   try {
-    if (!existsSync10(CACHE_PATH))
+    if (!existsSync11(CACHE_PATH))
       return {};
     return JSON.parse(readFileSync8(CACHE_PATH, "utf-8"));
   } catch {
@@ -8996,7 +9026,7 @@ function dirSearch(dir, sessionId) {
 function findCodexTranscript(sessionId) {
   const cache = readCache();
   const cached = cache[sessionId];
-  if (cached && existsSync10(cached))
+  if (cached && existsSync11(cached))
     return cached;
   const root = join24(homedir16(), ".codex", "sessions");
   const today = new Date;
@@ -9290,7 +9320,7 @@ var init_resolve_permission_mode = __esm(() => {
 });
 
 // lib/copilot-sessions.ts
-import { readFileSync as readFileSync10, readdirSync as readdirSync8, existsSync as existsSync11, statSync as statSync11 } from "node:fs";
+import { readFileSync as readFileSync10, readdirSync as readdirSync8, existsSync as existsSync12, statSync as statSync11 } from "node:fs";
 import { readFile as readFile12 } from "node:fs/promises";
 import { join as join25, resolve as resolve10, sep as sep2 } from "node:path";
 import { homedir as homedir17 } from "node:os";
@@ -9319,13 +9349,13 @@ function findCopilotTranscript(sessionId) {
   const candidate = resolveSessionFile(sessionId, "events.jsonl");
   if (!candidate)
     return null;
-  return existsSync11(candidate) ? candidate : null;
+  return existsSync12(candidate) ? candidate : null;
 }
 function findCopilotWorkspace(sessionId) {
   const candidate = resolveSessionFile(sessionId, "workspace.yaml");
   if (!candidate)
     return null;
-  return existsSync11(candidate) ? candidate : null;
+  return existsSync12(candidate) ? candidate : null;
 }
 function readYamlScalar(path, key) {
   try {
@@ -9507,7 +9537,7 @@ var init_copilot_sessions = __esm(() => {
 });
 
 // lib/cursor-sessions.ts
-import { readFileSync as readFileSync11, readdirSync as readdirSync9, existsSync as existsSync12, statSync as statSync12 } from "node:fs";
+import { readFileSync as readFileSync11, readdirSync as readdirSync9, existsSync as existsSync13, statSync as statSync12 } from "node:fs";
 import { readFile as readFile13 } from "node:fs/promises";
 import { basename as basename3, join as join26, resolve as resolve11, sep as sep3 } from "node:path";
 import { homedir as homedir18 } from "node:os";
@@ -9530,7 +9560,7 @@ function getCursorSessionDir(sessionId) {
     const transcriptRoot = resolve11(projectsRoot, entry.name, NEW_AGENT_TRANSCRIPTS_DIR2);
     if (candidate === transcriptRoot || !candidate.startsWith(`${transcriptRoot}${sep3}`))
       continue;
-    if (existsSync12(candidate))
+    if (existsSync13(candidate))
       return candidate;
   }
   for (const sub of LEGACY_SESSION_ROOT_CANDIDATES2) {
@@ -9538,7 +9568,7 @@ function getCursorSessionDir(sessionId) {
     const candidate = resolve11(root, sessionId);
     if (candidate === root || !candidate.startsWith(`${root}${sep3}`))
       continue;
-    if (existsSync12(candidate))
+    if (existsSync13(candidate))
       return candidate;
   }
   return null;
@@ -9548,11 +9578,11 @@ function findCursorTranscript(sessionId) {
   if (!dir)
     return null;
   const newCandidate = join26(dir, `${basename3(dir)}.jsonl`);
-  if (existsSync12(newCandidate))
+  if (existsSync13(newCandidate))
     return newCandidate;
   for (const name of LEGACY_TRANSCRIPT_FILE_CANDIDATES2) {
     const candidate = join26(dir, name);
-    if (existsSync12(candidate))
+    if (existsSync13(candidate))
       return candidate;
   }
   return null;
@@ -9763,7 +9793,7 @@ var init_cursor_sessions = __esm(() => {
 });
 
 // lib/pi-sessions.ts
-import { readFileSync as readFileSync12, readdirSync as readdirSync10, existsSync as existsSync13, statSync as statSync13 } from "node:fs";
+import { readFileSync as readFileSync12, readdirSync as readdirSync10, existsSync as existsSync14, statSync as statSync13 } from "node:fs";
 import { readFile as readFile14 } from "node:fs/promises";
 import { join as join27, resolve as resolve12, sep as sep4 } from "node:path";
 import { homedir as homedir19 } from "node:os";
@@ -9800,7 +9830,7 @@ function findPiTranscript(sessionId) {
       const candidate = resolve12(cwdPath, f);
       if (!candidate.startsWith(`${cwdPath}${sep4}`))
         continue;
-      if (existsSync13(candidate))
+      if (existsSync14(candidate))
         return candidate;
     }
   }
@@ -10160,7 +10190,7 @@ var init_pack_failclosed = __esm(() => {
 var init_atomic_write = () => {};
 
 // src/hooks/session-pause.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync6, readdirSync as readdirSync11, readFileSync as readFileSync13, rmSync as rmSync2 } from "node:fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync6, readdirSync as readdirSync11, readFileSync as readFileSync13, rmSync as rmSync2 } from "node:fs";
 import { createHash as createHash5 } from "node:crypto";
 import { join as join28, resolve as resolve13 } from "node:path";
 function pauseStateDir() {
@@ -10200,7 +10230,7 @@ function readActivePause(sessionId, now = Date.now()) {
     return null;
   try {
     const path = pauseFilePath(sessionId);
-    if (!existsSync14(path))
+    if (!existsSync15(path))
       return null;
     const stored = parseStored(JSON.parse(readFileSync13(path, "utf8")));
     if (!stored)
@@ -10241,7 +10271,7 @@ var init_daemon_service = __esm(() => {
 // src/hooks/fp-reset.ts
 import {
   copyFileSync,
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   mkdirSync as mkdirSync7,
   readFileSync as readFileSync14,
   readdirSync as readdirSync12,
@@ -10258,7 +10288,7 @@ function layoutWarningForHook() {
   if (state.kind === "future") {
     return `[failproofai] this directory was written by a newer version (layout ${state.found} vs ${LAYOUT_VERSION}) — policies are NOT being enforced. ` + `Upgrade failproofai.`;
   }
-  if (existsSync15(globalPolicyConfigFile()))
+  if (existsSync16(globalPolicyConfigFile()))
     return null;
   return `[failproofai] setup predates this version — global policies are NOT being enforced. ` + `Run \`failproofai config\` to re-create it.`;
 }
@@ -10605,7 +10635,20 @@ async function evaluateHookEvent(eventType, cli = "claude", stdinPayload, opts)
         }
       } catch {}
     }
-    return { exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+    return {
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      evaluation: {
+        decision: result.decision,
+        policyName: result.policyName,
+        policyNames: result.policyNames ?? (result.policyName ? [result.policyName] : []),
+        reason: result.reason,
+        matchedPolicies,
+        durationMs,
+        toolName: parsed.tool_name ?? null
+      }
+    };
   } finally {
     if (opts?.awaitTelemetryFlush ?? true) {
       await flushHookTelemetry();
@@ -10635,7 +10678,7 @@ var init_handler = __esm(() => {
 
 // src/hooks/worker-server.ts
 import { createConnection, createServer } from "node:net";
-import { existsSync as existsSync16, unlinkSync as unlinkSync2 } from "node:fs";
+import { existsSync as existsSync17, unlinkSync as unlinkSync2 } from "node:fs";
 function isWorkerHookRequest(msg) {
   if (!msg || typeof msg !== "object")
     return false;
@@ -10709,7 +10752,8 @@ function handleConnection(socket, shutdown) {
             type: "hookResult",
             exitCode: result.exitCode,
             stdout: result.stdout,
-            stderr: result.stderr
+            stderr: result.stderr,
+            evaluation: result.evaluation
           }));
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -10768,14 +10812,14 @@ function requestExistingWorkerShutdown(socketPath) {
 function startWorkerServer(socketPath, shutdown) {
   const server = createServer((socket) => handleConnection(socket, shutdown ?? (() => server.close())));
   const listen = () => {
-    if (existsSync16(socketPath)) {
+    if (existsSync17(socketPath)) {
       try {
         unlinkSync2(socketPath);
       } catch {}
     }
     server.listen(socketPath);
   };
-  if (!existsSync16(socketPath))
+  if (!existsSync17(socketPath))
     listen();
   else
     requestExistingWorkerShutdown(socketPath).then(listen, (err) => server.emit("error", err));

package/hermes-plugin/README.md

@@ -0,0 +1,138 @@
+# FailproofAI for Hermes
+
+This directory is the native Hermes adapter shipped inside the `failproofai`
+npm package. It keeps policy evaluation in FailproofAI's TypeScript worker and
+translates structured verdicts into Hermes-native hook behavior.
+
+Validated contract: Hermes 0.21.3 at
+`4d55ca91656ac5f83e1506679b7f81e0238e5e16`. The plugin uses only documented
+manifest v2 fields, `PluginContext` methods/state, and keyword hook payloads.
+
+## Installation
+
+Hermes policy evaluation requires a configured, healthy local `failproofaid`
+daemon. If this machine has not been configured yet, run `failproofai config`
+first. The standalone installer refuses to enable the fail-closed plugin until
+the daemon answers an end-to-end health probe.
+
+Then run:
+
+```bash
+failproofai policies --install --cli hermes --scope user
+```
+
+FailproofAI copies this directory to every discovered profile at
+`<HERMES_HOME>/plugins/failproofai/` and adds `failproofai` to
+`plugins.enabled` in that profile's `config.yaml`. Reinstall replaces only a
+directory carrying `.failproofai-managed`; an unrelated plugin with the same
+directory name is never overwritten.
+
+Legacy FailproofAI shell hooks are removed during migration. Operator-owned
+hooks and unrelated plugin settings are preserved. No dashboard deployment or
+backtest is part of installation.
+
+## Runtime path
+
+```text
+Hermes pre_tool_call
+  -> native Python plugin
+  -> owner-only failproofaid Unix socket
+  -> warm TypeScript policy worker
+  -> structured allow | deny | instruct verdict
+  -> Hermes-native return value
+```
+
+There is no cloud request and no new CLI process in the tool-call path.
+
+## Decision behavior
+
+- `allow`: return no directive; Hermes runs the tool.
+- `deny`: always return `{"action":"block","message":"..."}`.
+- `instruct`: persist delivery state, block the first attempt with a
+  model-visible `FAILPROOF INSTRUCTION`, keep the same API request blocked, then
+  allow a later API iteration for the same instruction scope.
+
+The default instruction scope is profile + session + task + turn + policy
+fingerprint + canonical tool. The persistent SQLite ledger lives below Hermes'
+profile-scoped plugin data directory. Two distinct instruction interruptions
+are allowed per turn by default; after that, advisory instructions fail open so
+they cannot create an infinite retry loop. A real deny is never bypassed by the
+ledger.
+
+## Configuration
+
+Settings live under `plugins.entries.failproofai.settings`:
+
+```yaml
+plugins:
+  enabled:
+    - failproofai
+  entries:
+    failproofai:
+      settings:
+        failure_mode: deny
+        connect_timeout_ms: 250
+        evaluation_timeout_ms: 12000
+        instruction_ttl_seconds: 3600
+        max_instruction_rounds: 2
+```
+
+`failure_mode` controls evaluator/protocol failures only. `deny` is the safe
+default. `allow` favors availability when the local daemon cannot return a
+trusted verdict. Ledger failures always allow only the advisory `instruct`
+decision, because otherwise corrupted retry state could block a turn forever.
+
+## Local protocol
+
+Requests and responses use the existing length-prefixed failproofaid Unix
+socket protocol, version 1.
+
+```json
+{
+  "type": "policyEvaluation",
+  "protocolVersion": 1,
+  "integration": "hermes",
+  "event": "pre_tool_call",
+  "payload": {},
+  "cwd": "/workspace/project"
+}
+```
+
+```json
+{
+  "type": "policyResult",
+  "protocolVersion": 1,
+  "decision": "instruct",
+  "policyNames": ["custom/approved-write-route"],
+  "reason": "Use the approved write route.",
+  "matchedPolicies": ["custom/approved-write-route"],
+  "durationMs": 3,
+  "toolName": "Write"
+}
+```
+
+Requests are limited to 1 MiB and responses to 16 MiB. Invalid JSON, unknown
+message types, version mismatch, timeout, and socket failure are treated as
+untrusted evaluation failures.
+
+## Diagnostics and rollback
+
+`failproofai config --status` reports each existing Hermes profile as healthy,
+disabled, incomplete, or duplicated with a legacy shell hook. Hermes-side load
+errors are available through:
+
+```bash
+HERMES_PLUGINS_DEBUG=1 hermes plugins list
+hermes plugins doctor ~/.hermes/plugins/failproofai --ci
+hermes logs --level WARNING
+```
+
+Use a temporary `HERMES_HOME` for development and compatibility tests. Remove
+the integration with:
+
+```bash
+failproofai policies --uninstall --cli hermes --scope user
+```
+
+Uninstall removes the config registration and only the plugin directory marked
+as FailproofAI-managed.

package/hermes-plugin/__init__.py

@@ -0,0 +1,248 @@
+"""Native Hermes bridge for FailproofAI policy enforcement."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Mapping
+
+from .client import PolicyVerdict, evaluate_policy
+from .ledger import InstructionLedger, LedgerError
+
+logger = logging.getLogger(__name__)
+
+_PROTOCOL_CONTEXT = (
+    "When a tool result starts with FAILPROOF INSTRUCTION, treat it as policy guidance. "
+    "Reconsider the attempted action before retrying. Do not evade or ignore the instruction; "
+    "change tools, arguments, targets, or side effects only when the instruction requires it. "
+    "If you cannot follow the instruction, stop and explain why."
+)
+
+
+def _bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    return min(max(parsed, minimum), maximum)
+
+
+def _profile_name() -> str:
+    explicit = os.environ.get("HERMES_PROFILE", "").strip()
+    if explicit:
+        return explicit
+    configured_home = os.environ.get("HERMES_HOME", "").strip()
+    home = Path(configured_home).expanduser() if configured_home else Path.home() / ".hermes"
+    if home.parent.name == "profiles":
+        return home.name
+    return "default"
+
+
+def _string(value: object) -> str:
+    return value if isinstance(value, str) else ""
+
+
+class FailproofAIPlugin:
+    def __init__(self, ctx: Any) -> None:
+        self.ctx = ctx
+        self.profile = _profile_name()
+        self.failure_mode = str(ctx.get_config("failure_mode", "deny")).strip().lower()
+        self.connect_timeout_ms = _bounded_int(
+            ctx.get_config("connect_timeout_ms", 250), 250, 25, 5_000
+        )
+        self.evaluation_timeout_ms = _bounded_int(
+            ctx.get_config("evaluation_timeout_ms", 12_000), 12_000, 100, 29_000
+        )
+        ttl_seconds = _bounded_int(
+            ctx.get_config("instruction_ttl_seconds", 3_600), 3_600, 60, 86_400
+        )
+        max_rounds = _bounded_int(
+            ctx.get_config("max_instruction_rounds", 2), 2, 0, 10
+        )
+        self.ledger = InstructionLedger(
+            Path(ctx.state.data_dir) / "instructions.db",
+            ttl_seconds=ttl_seconds,
+            max_rounds=max_rounds,
+        )
+
+    def _fallback(self, error: Exception) -> dict[str, str] | None:
+        logger.error("FailproofAI evaluator unavailable: %s", error)
+        if self.failure_mode == "allow":
+            return None
+        return {
+            "action": "block",
+            "message": (
+                "FailproofAI could not verify this tool call because the local policy "
+                "evaluator is unavailable. Check `failproofai status` before retrying."
+            ),
+        }
+
+    def _evaluate(self, event: str, payload: Mapping[str, Any]) -> PolicyVerdict:
+        cwd = _string(payload.get("cwd")) or os.getcwd()
+        return evaluate_policy(
+            event=event,
+            payload=payload,
+            cwd=cwd,
+            connect_timeout_ms=self.connect_timeout_ms,
+            evaluation_timeout_ms=self.evaluation_timeout_ms,
+        )
+
+    def pre_tool_call(
+        self,
+        tool_name: str = "",
+        args: Mapping[str, Any] | None = None,
+        session_id: str = "",
+        task_id: str = "",
+        tool_call_id: str = "",
+        turn_id: str = "",
+        api_request_id: str = "",
+        **kwargs: Any,
+    ) -> dict[str, str] | None:
+        payload = {
+            "hook_event_name": "pre_tool_call",
+            "tool_name": tool_name,
+            "tool_input": dict(args or {}),
+            "session_id": session_id,
+            "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+            "hermes": {
+                "profile": self.profile,
+                "task_id": task_id,
+                "tool_call_id": tool_call_id,
+                "turn_id": turn_id,
+                "api_request_id": api_request_id,
+            },
+        }
+        try:
+            verdict = self._evaluate("pre_tool_call", payload)
+        except Exception as exc:
+            return self._fallback(exc)
+
+        if verdict.decision == "allow":
+            return None
+        if verdict.decision == "deny":
+            return {
+                "action": "block",
+                "message": verdict.reason or "Blocked by FailproofAI policy.",
+            }
+
+        reason = verdict.reason or "Reconsider this tool call before retrying."
+        try:
+            action = self.ledger.decide(
+                profile=self.profile,
+                session_id=session_id,
+                task_id=task_id,
+                turn_id=turn_id,
+                api_request_id=api_request_id,
+                policy_names=verdict.policy_names,
+                reason=reason,
+                scope_key=verdict.tool_name or tool_name or "unknown-tool",
+            )
+        except LedgerError as exc:
+            # An advisory instruction must never become an indefinite denial
+            # because its local retry state is unavailable.
+            logger.error("FailproofAI instruction state unavailable; allowing: %s", exc)
+            return None
+
+        if not action.block:
+            if action.status in {"missing-correlation-id", "turn-cap"}:
+                logger.warning("FailproofAI instruction allowed in degraded state: %s", action.status)
+            return None
+
+        policies = ", ".join(verdict.policy_names) or "unknown policy"
+        return {
+            "action": "block",
+            "message": (
+                f"FAILPROOF INSTRUCTION ({policies})\n\n{reason}\n\n"
+                "Reconsider the attempted action, then make a corrected tool call. "
+                "Do not route around this instruction with an equivalent ungoverned action."
+            ),
+        }
+
+    def _observe(self, event: str, payload: Mapping[str, Any]) -> None:
+        try:
+            self._evaluate(event, payload)
+        except Exception as exc:
+            logger.warning("FailproofAI observation failed for %s: %s", event, exc)
+
+    def post_tool_call(
+        self,
+        tool_name: str = "",
+        args: Mapping[str, Any] | None = None,
+        result: Any = None,
+        session_id: str = "",
+        **kwargs: Any,
+    ) -> None:
+        self._observe(
+            "post_tool_call",
+            {
+                "hook_event_name": "post_tool_call",
+                "tool_name": tool_name,
+                "tool_input": dict(args or {}),
+                "tool_response": result,
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+
+    def on_session_start(self, session_id: str = "", **kwargs: Any) -> None:
+        self._observe(
+            "on_session_start",
+            {
+                "hook_event_name": "on_session_start",
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+
+    def on_session_end(self, session_id: str = "", **kwargs: Any) -> None:
+        self._observe(
+            "on_session_end",
+            {
+                "hook_event_name": "on_session_end",
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+        self._clear_session(session_id)
+
+    def subagent_stop(self, session_id: str = "", **kwargs: Any) -> None:
+        self._observe(
+            "subagent_stop",
+            {
+                "hook_event_name": "subagent_stop",
+                "session_id": session_id,
+                "cwd": _string(kwargs.get("cwd")) or os.getcwd(),
+                "hermes": {"profile": self.profile, **kwargs},
+            },
+        )
+
+    def pre_llm_call(self, **kwargs: Any) -> dict[str, str]:
+        return {"context": _PROTOCOL_CONTEXT}
+
+    def on_session_reset(self, session_id: str = "", **kwargs: Any) -> None:
+        self._clear_session(session_id)
+
+    def on_session_finalize(self, session_id: str = "", **kwargs: Any) -> None:
+        self._clear_session(session_id)
+
+    def _clear_session(self, session_id: str) -> None:
+        try:
+            self.ledger.clear_session(session_id)
+        except LedgerError as exc:
+            logger.warning("FailproofAI instruction cleanup failed: %s", exc)
+
+
+def register(ctx: Any) -> None:
+    plugin = FailproofAIPlugin(ctx)
+    ctx.register_hook("pre_tool_call", plugin.pre_tool_call)
+    ctx.register_hook("post_tool_call", plugin.post_tool_call)
+    ctx.register_hook("pre_llm_call", plugin.pre_llm_call)
+    ctx.register_hook("on_session_start", plugin.on_session_start)
+    ctx.register_hook("on_session_end", plugin.on_session_end)
+    ctx.register_hook("on_session_reset", plugin.on_session_reset)
+    ctx.register_hook("on_session_finalize", plugin.on_session_finalize)
+    ctx.register_hook("subagent_stop", plugin.subagent_stop)