failproofai 1.0.9 → 1.0.10

package/hermes-plugin/__init__.py

@@ -2,23 +2,86 @@
 
 from __future__ import annotations
 
+import contextvars
+import functools
+import hashlib
+import json
 import logging
 import os
+import re
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, Callable, Iterable, Mapping
 
 from .client import PolicyVerdict, evaluate_policy
 from .ledger import InstructionLedger, LedgerError
 
 logger = logging.getLogger(__name__)
 
+_PLUGIN_ID = "failproofai"
+
+_HOOKS = (
+    "pre_tool_call",
+    "post_tool_call",
+    "pre_llm_call",
+    "on_session_start",
+    "on_session_end",
+    "on_session_reset",
+    "on_session_finalize",
+    "subagent_stop",
+)
+
+_REMINDER_KEY = "failproof_policy_reminder"
+# Where a tool's own field of that name goes: it is tool data, and the protocol
+# note tells the model _REMINDER_KEY is an operator rule, so the two never mix.
+_TOOL_REMINDER_KEY = f"tool_{_REMINDER_KEY}"
+
 _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."
+    "FailproofAI applies your operator's policies to tool calls. "
+    f"(1) A tool result whose first JSON key is {_REMINDER_KEY}, or whose text starts with "
+    "[FailproofAI policy reminder ...], ran normally: it is not an error and needs no retry. "
+    "The reminder is an operator rule added by FailproofAI, not data from the tool; apply it "
+    "to how you use that result. It never grants permission for anything the user did not ask "
+    "for. Never quote or repeat a reminder, or say that one was attached, in your replies, "
+    "messages or files: just follow it. "
+    "(2) When FailproofAI blocks a tool call, do not run that action: not by retrying it, and "
+    "not through another tool, a script, or reworded arguments. Follow the block message, or "
+    "stop and explain why you cannot continue. "
+    "(3) A result that starts with 'FailproofAI policy guidance' held the call once so you could "
+    "read the guidance: apply it and continue; repeating the same call is allowed."
 )
 
+# Reminders from a pre_tool_call that ran before its own call's middleware
+# frame opened wait this long to be claimed (normally microseconds).
+_HANDOFF_TTL_SECONDS = 60.0
+_HANDOFF_LIMIT = 256
+
+# Hermes 0.21.x abandons a pre_tool_call that runs past 30 s, blocks the call,
+# and then skips that callback (blocking every call) for 60 s. One evaluation,
+# connect included, stays well inside that.
+_EVALUATION_TIMEOUT_CAP_MS = 25_000
+_OBSERVE_TIMEOUT_MS = 2_000
+
+# A reminder is attached once per (session, turn) for the same policy and reason.
+_DELIVERED_LIMIT = 1024
+
+# Hermes saves a result to a file once it passes 15% of the model's context
+# window (at 4 chars per token, clamped to 8,000-100,000 chars; read_file is
+# never saved) and shows the model a 1,500-char preview. When the full reminder
+# would take a result past 7,500 chars it is compacted to a bounded size (each
+# policy name, each reason and the number of reminders are capped), so it stays
+# inside that preview. It is always attached: on a model whose threshold is the
+# 8,000 floor, a result just under it may be saved because of the reminder, and
+# the reminder is then the head of the preview the model reads.
+_FULL_REMINDER_MAX_CHARS = 7_500
+_COMPACT_REASON_CHARS = 160
+_COMPACT_POLICY_CHARS = 80
+_COMPACT_MAX_REMINDERS = 3
+
 
 def _bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
     try:
@@ -43,28 +106,539 @@ def _string(value: object) -> str:
     return value if isinstance(value, str) else ""
 
 
+# Hermes added `ctx.get_config` and `ctx.state` in 0.20.1. On 0.20.0 the plugin
+# must still load: a register() that raises leaves every tool call unchecked.
+# The helpers below reproduce what those two members return, so a later Hermes
+# upgrade reads the same settings and reuses the same instructions.db.
+
+
+def _plugin_id(ctx: Any) -> str:
+    manifest = getattr(ctx, "manifest", None)
+    for field in ("key", "name"):
+        value = getattr(manifest, field, None)
+        if isinstance(value, str) and value:
+            return value
+    return _PLUGIN_ID
+
+
+def _hermes_home() -> Path:
+    try:
+        # The host's resolver honours a per-task profile override as well as
+        # HERMES_HOME; it is the one PluginState.data_dir uses.
+        from hermes_constants import get_hermes_home
+
+        return Path(get_hermes_home())
+    except Exception:
+        configured_home = os.environ.get("HERMES_HOME", "").strip()
+        return Path(configured_home).expanduser() if configured_home else Path.home() / ".hermes"
+
+
+def _data_namespace(plugin_id: str, skill_namespace: str = "") -> str:
+    # hermes_cli.plugins._plugin_data_namespace + _portable_skill_namespace.
+    candidate = skill_namespace or plugin_id
+    if (
+        skill_namespace
+        and candidate.startswith("agent-plugin-")
+        and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,191}", candidate)
+    ):
+        return candidate
+    slug = "".join(
+        ch if ch.isascii() and (ch.isalnum() or ch in "_-") else "-"
+        for ch in candidate.lower()
+    )
+    slug = slug.strip("-_") or "plugin"
+    digest = hashlib.sha256(candidate.encode("utf-8")).hexdigest()[:8]
+    return f"agent-plugin-{slug}-{digest}"
+
+
+def _state_dir(ctx: Any, plugin_id: str) -> Path | None:
+    try:
+        state = getattr(ctx, "state", None)
+        if state is not None:
+            return Path(state.data_dir)
+    except Exception as exc:
+        logger.warning("FailproofAI could not read Hermes plugin state: %s", exc)
+    try:
+        skill_namespace = getattr(getattr(ctx, "manifest", None), "skill_namespace", "")
+        namespace = _data_namespace(plugin_id, _string(skill_namespace))
+        return _hermes_home() / "plugin-data" / namespace
+    except Exception as exc:
+        logger.error("FailproofAI instruction state directory unavailable: %s", exc)
+        return None
+
+
+def _config_reader(ctx: Any, plugin_id: str) -> Callable[[str, Any], Any]:
+    get_config = getattr(ctx, "get_config", None)
+    if callable(get_config):
+        return get_config
+
+    # PluginContext.get_config: plugins.entries.<id>.settings.<key>, then the
+    # legacy config.<key>, read through the host's own config loader.
+    entry: Mapping[str, Any] = {}
+    try:
+        from hermes_cli import config as hermes_config
+
+        load = getattr(hermes_config, "load_config_readonly", None) or hermes_config.load_config
+        config = load() or {}
+        plugins = config.get("plugins") if isinstance(config, Mapping) else None
+        entries = plugins.get("entries") if isinstance(plugins, Mapping) else None
+        found = entries.get(plugin_id) if isinstance(entries, Mapping) else None
+        if isinstance(found, Mapping):
+            entry = found
+    except Exception as exc:
+        logger.debug("FailproofAI using default settings; Hermes config unavailable: %s", exc)
+
+    def read(key: str, default: Any = None) -> Any:
+        for section in ("settings", "config"):
+            values = entry.get(section)
+            if isinstance(values, Mapping) and key in values:
+                return values[key]
+        return default
+
+    return read
+
+
+# An instruct verdict is a reminder, not a refusal: with Hermes' tool_execution
+# middleware the call runs and the reminder rides at the START of its result
+# (JSON first key, or a leading line), so it survives the 1,500-char preview
+# Hermes keeps of a large result. Blocking once to deliver it made the model
+# treat a correct call as an error and route around it.
+#
+# Where pre_tool_call runs relative to the middleware (Hermes 0.20.0-0.21.3):
+# - agent loop (sequential and concurrent): inside next_call, on the
+#   middleware's thread (0.20.0) or on a hook worker that runs in a COPY of its
+#   context (0.21.x). A ContextVar frame stack is visible on both; a
+#   thread-local is not on 0.21.x.
+# - model_tools.handle_function_call (execute_code inner calls, direct
+#   dispatch): BEFORE the middleware, so the reminder is handed off by call
+#   identity and the call's frame claims it when it opens.
+
+
+@dataclass(frozen=True)
+class _Reminder:
+    policies: str
+    reason: str
+
+
+class _ReminderFrame:
+    """One call wrapped by the tool_execution middleware."""
+
+    def __init__(self, tool_name: str, tool_call_id: str, parent: "_ReminderFrame | None") -> None:
+        self.tool_name = tool_name
+        self.tool_call_id = tool_call_id
+        self.parent = parent
+        self._lock = threading.Lock()
+        self._open = True
+        self._checked = False
+        self._reminders: list[_Reminder] = []
+
+    @property
+    def open(self) -> bool:
+        return self._open
+
+    def owns(self, tool_name: str, tool_call_id: str) -> bool:
+        # The first pre_tool_call naming this frame's call is that call's own
+        # check; anything else in the frame is a nested call.
+        with self._lock:
+            if not self._open or self._checked:
+                return False
+            if (tool_name, tool_call_id) != (self.tool_name, self.tool_call_id):
+                return False
+            self._checked = True
+            return True
+
+    def add(self, reminders: Iterable[_Reminder]) -> bool:
+        """False when the frame already closed, so the caller keeps them."""
+        with self._lock:
+            if not self._open:
+                return False
+            for reminder in reminders:
+                if reminder not in self._reminders:
+                    self._reminders.append(reminder)
+            return True
+
+    def close(self) -> tuple[_Reminder, ...]:
+        with self._lock:
+            self._open = False
+            return tuple(self._reminders)
+
+
+class _ReminderHandoff:
+    """Reminders waiting for the middleware frame of a call whose pre_tool_call
+    ran first. Bounded and short-lived: an unclaimed entry means the call never
+    reached the middleware (another plugin blocked it), so nothing is lost."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._entries: dict[tuple[str, ...], tuple[float, list[_Reminder]]] = {}
+
+    def _expire(self, now: float) -> None:
+        for key in [key for key, (at, _) in self._entries.items() if now - at > _HANDOFF_TTL_SECONDS]:
+            del self._entries[key]
+        while len(self._entries) >= _HANDOFF_LIMIT:
+            del self._entries[next(iter(self._entries))]
+
+    def put(self, key: tuple[str, ...], reminder: _Reminder) -> None:
+        now = time.monotonic()
+        with self._lock:
+            entry = self._entries.pop(key, None)
+            self._expire(now)
+            reminders = entry[1] if entry is not None else []
+            if reminder not in reminders:
+                reminders.append(reminder)
+            self._entries[key] = (now, reminders)
+
+    def take(self, key: tuple[str, ...]) -> list[_Reminder]:
+        now = time.monotonic()
+        with self._lock:
+            entry = self._entries.pop(key, None)
+        # An entry past its TTL belonged to a call that never reached its frame.
+        if entry is None or now - entry[0] > _HANDOFF_TTL_SECONDS:
+            return []
+        return entry[1]
+
+    def pending(self) -> bool:
+        # Lets the middleware skip hashing every call's arguments.
+        return bool(self._entries)
+
+
+def _call_key(
+    session_id: object, task_id: object, tool_call_id: object, tool_name: object, args: object
+) -> tuple[str, ...]:
+    # Execute_code inner calls carry no session or tool_call id, so the
+    # arguments keep two concurrent calls of one tool apart.
+    try:
+        encoded = json.dumps(args or {}, sort_keys=True, ensure_ascii=False, default=repr)
+    except Exception:
+        encoded = repr(args)
+    digest = hashlib.sha256(encoded.encode("utf-8", "replace")).hexdigest()
+    return (_string(session_id), _string(task_id), _string(tool_call_id), _string(tool_name), digest)
+
+
+def _clip(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[:limit].rstrip() + "…"
+
+
+def _reason(reminder: _Reminder, compact: bool) -> str:
+    return _clip(reminder.reason, _COMPACT_REASON_CHARS) if compact else reminder.reason
+
+
+def _policies(reminder: _Reminder, compact: bool) -> str:
+    # Custom policy names have no length limit, so the compact form caps them too.
+    return _clip(reminder.policies, _COMPACT_POLICY_CHARS) if compact else reminder.policies
+
+
+def _reminder_lines(reminders: tuple[_Reminder, ...], compact: bool, line: Callable[[str, str], str]) -> str:
+    shown = reminders[:_COMPACT_MAX_REMINDERS] if compact else reminders
+    lines = [line(_policies(r, compact), _reason(r, compact)) for r in shown]
+    if len(shown) < len(reminders):
+        lines.append(f"(+{len(reminders) - len(shown)} more FailproofAI policy reminders)")
+    return "\n".join(lines) + " — the tool call ran; apply this when you use its result."
+
+
+def _reminder_text(reminders: tuple[_Reminder, ...], compact: bool = False) -> str:
+    return _reminder_lines(reminders, compact, lambda p, r: f"FailproofAI policy reminder ({p}): {r}")
+
+
+def _reminder_prefix(reminders: tuple[_Reminder, ...], compact: bool = False) -> str:
+    return _reminder_lines(reminders, compact, lambda p, r: f"[FailproofAI policy reminder ({p})] {r}")
+
+
+def _result_chars(result: Any) -> int:
+    if isinstance(result, str):
+        return len(result)
+    try:
+        return len(json.dumps(result, ensure_ascii=False, default=str))
+    except Exception:
+        return 0
+
+
+class _TurnDeliveries:
+    """Bounded LRU of the reminders already attached in a (session, turn), so a
+    turn that runs the same command again does not repeat the same text."""
+
+    def __init__(self, limit: int = _DELIVERED_LIMIT) -> None:
+        self._lock = threading.Lock()
+        self._limit = limit
+        self._seen: OrderedDict[tuple[str, str, str, str], None] = OrderedDict()
+
+    @staticmethod
+    def _key(session_id: str, turn_id: str, reminder: _Reminder) -> tuple[str, str, str, str]:
+        return (session_id, turn_id, reminder.policies, reminder.reason)
+
+    def unseen(self, session_id: str, turn_id: str, reminders: tuple[_Reminder, ...]) -> tuple[_Reminder, ...]:
+        # A call without both ids (execute_code inner calls) cannot be scoped
+        # to a turn, so it always carries its reminders.
+        if not session_id or not turn_id:
+            return reminders
+        with self._lock:
+            return tuple(r for r in reminders if self._key(session_id, turn_id, r) not in self._seen)
+
+    def mark(self, session_id: str, turn_id: str, reminders: tuple[_Reminder, ...]) -> None:
+        if not session_id or not turn_id:
+            return
+        with self._lock:
+            self._mark_locked(session_id, turn_id, reminders)
+
+    def _mark_locked(self, session_id: str, turn_id: str, reminders: tuple[_Reminder, ...]) -> None:
+        for reminder in reminders:
+            key = self._key(session_id, turn_id, reminder)
+            self._seen[key] = None
+            self._seen.move_to_end(key)
+        while len(self._seen) > self._limit:
+            self._seen.popitem(last=False)
+
+    def claim(self, session_id: str, turn_id: str, reminders: tuple[_Reminder, ...]) -> tuple[_Reminder, ...]:
+        """The reminders not yet delivered in this turn, marked delivered in the
+        same step, so two calls running at once cannot both take one."""
+        if not session_id or not turn_id:
+            return reminders
+        with self._lock:
+            fresh = tuple(r for r in reminders if self._key(session_id, turn_id, r) not in self._seen)
+            self._mark_locked(session_id, turn_id, fresh)
+            return fresh
+
+    def release(self, session_id: str, turn_id: str, reminders: tuple[_Reminder, ...]) -> None:
+        """Undo a claim whose reminders found no carrier, so a later call delivers them."""
+        if not session_id or not turn_id:
+            return
+        with self._lock:
+            for reminder in reminders:
+                self._seen.pop(self._key(session_id, turn_id, reminder), None)
+
+
+def _unexecuted(result: Any) -> bool:
+    # Hermes reports a blocked or rejected call as {"error": ...} (tool_error
+    # may add "success"). A reminder there would claim a call ran that did not.
+    if isinstance(result, str):
+        if not result.lstrip().startswith("{"):
+            return False
+        try:
+            result = json.loads(result)
+        except Exception:
+            return False
+    return (
+        isinstance(result, dict)
+        and bool(result.get("error"))
+        and set(result) <= {"error", "success"}
+    )
+
+
+def _with_first_key(value: Mapping[str, Any], text: str) -> dict[str, Any]:
+    rest = {k: v for k, v in value.items() if k != _REMINDER_KEY}
+    if _REMINDER_KEY in value and value[_REMINDER_KEY] != text:
+        # Never merged into ours: that would present tool output as operator text.
+        rest = {_TOOL_REMINDER_KEY: value[_REMINDER_KEY], **rest}
+    return {_REMINDER_KEY: text, **rest}
+
+
+def _json_layout(original: str) -> dict[str, Any]:
+    # Keep the tool's own JSON shape: Hermes tools emit json.dumps defaults,
+    # a few emit compact or indented JSON.
+    if original.lstrip().startswith("{\n"):
+        return {"indent": 2}
+    if re.search(r'"\s*:\s', original[:4096]):
+        return {}
+    return {"separators": (",", ":")}
+
+
+def _attach_reminders(result: Any, reminders: tuple[_Reminder, ...]) -> Any:
+    """Put the reminder at the start of the result, compact when the full one
+    would take it past _FULL_REMINDER_MAX_CHARS; on any failure return the
+    result untouched. Never raises."""
+    try:
+        full = _render(result, reminders, compact=False)
+        if full is result or _result_chars(full) <= _FULL_REMINDER_MAX_CHARS:
+            return full
+        return _render(result, reminders, compact=True)
+    except Exception as exc:
+        logger.warning("FailproofAI could not attach a policy reminder: %s", exc)
+    return result
+
+
+def _render(result: Any, reminders: tuple[_Reminder, ...], *, compact: bool) -> Any:
+    """The result with the reminder at its start; the result itself for a
+    type that cannot carry one."""
+    text = _reminder_text(reminders, compact)
+    prefix = _reminder_prefix(reminders, compact)
+    if isinstance(result, str):
+        if result.lstrip().startswith("{"):
+            try:
+                parsed = json.loads(result)
+            except ValueError:
+                parsed = None
+            if isinstance(parsed, dict):
+                return json.dumps(
+                    _with_first_key(parsed, text),
+                    ensure_ascii=False,
+                    **_json_layout(result),
+                )
+        if result.startswith("Error"):
+            # Hermes' failure detection keys on this prefix; a short error
+            # keeps the reminder visible at its end.
+            return f"{result}\n\n{prefix}"
+        return f"{prefix}\n\n{result}"
+    if isinstance(result, list):
+        return [{"type": "text", "text": prefix}, *result]
+    if isinstance(result, dict):
+        content = result.get("content")
+        if result.get("_multimodal") is True and isinstance(content, list):
+            # Multimodal envelope: the model reads `content`; image parts stay intact.
+            annotated = dict(result)
+            annotated["content"] = [{"type": "text", "text": prefix}, *content]
+            if isinstance(result.get("text_summary"), str):
+                annotated["text_summary"] = f"{prefix}\n\n{result['text_summary']}"
+            return annotated
+        return _with_first_key(result, text)
+    return result
+
+
+def _guarded(on_error: Callable[[str, Exception], Any]) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Hermes 0.20.0 and 0.21.x treat a pre_tool_call that raises as ALLOW and
+    log the rest, so no hook may raise: each returns a defined value instead.
+    functools.wraps keeps the **kwargs signature Hermes inspects."""
+
+    def decorate(method: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(method)
+        def guarded(self: Any, *args: Any, **kwargs: Any) -> Any:
+            try:
+                return method(self, *args, **kwargs)
+            except Exception as exc:
+                logger.exception("FailproofAI %s failed", method.__name__)
+                return on_error(method.__name__, exc)
+
+        return guarded
+
+    return decorate
+
+
+def _block_on_internal_error(hook: str, error: Exception) -> dict[str, str]:
+    # Fail closed: the call is not run when FailproofAI could not check it.
+    return {
+        "action": "block",
+        "message": (
+            f"FailproofAI could not check this tool call (internal error: {type(error).__name__}), "
+            "so it was not run. Report this to your operator before retrying."
+        ),
+    }
+
+
+def _nothing(hook: str, error: Exception) -> None:
+    return None
+
+
+def _protocol_context(hook: str, error: Exception) -> dict[str, str]:
+    return {"context": _PROTOCOL_CONTEXT}
+
+
+def _plugin_version() -> str:
+    try:
+        manifest = Path(__file__).with_name("plugin.yaml").read_text(encoding="utf-8")
+        found = re.search(r"^version:\s*['\"]?([^'\"\s#]+)", manifest, re.MULTILINE)
+        return found.group(1) if found else ""
+    except Exception:
+        return ""
+
+
+def _hermes_version() -> str:
+    try:
+        from hermes_cli import __version__
+
+        return str(__version__)
+    except Exception:
+        return ""
+
+
+def _heartbeat_base(ctx: Any) -> dict[str, Any]:
+    """Who loaded the plugin, where. Every field is best-effort."""
+    record: dict[str, Any] = {"pid": os.getpid()}
+    for field, read in (
+        ("hermes_version", _hermes_version),
+        ("hermes_home", lambda: str(_hermes_home())),
+        ("profile", _profile_name),
+        ("plugin_path", lambda: str(Path(__file__).resolve().parent)),
+        ("plugin_version", _plugin_version),
+    ):
+        try:
+            record[field] = read()
+        except Exception as exc:
+            record[field] = f"unavailable: {type(exc).__name__}"
+    return record
+
+
+def _write_heartbeat(state_dir: Path | None, record: Mapping[str, Any]) -> None:
+    """heartbeat.json beside instructions.db: proof of which plugin a Hermes
+    process actually loaded (`hermes plugins list` reads config only). Never raises."""
+    if state_dir is None:
+        return
+    temporary: Path | None = None
+    try:
+        now = time.time()
+        body = {
+            **record,
+            "timestamp": datetime.fromtimestamp(now, timezone.utc).isoformat(timespec="seconds"),
+            "timestamp_ms": int(now * 1000),
+        }
+        state_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        target = state_dir / "heartbeat.json"
+        temporary = state_dir / f".heartbeat.{os.getpid()}.{threading.get_ident()}.tmp"
+        temporary.write_text(json.dumps(body, indent=2, sort_keys=True, default=str), encoding="utf-8")
+        os.replace(temporary, target)
+    except Exception as exc:
+        logger.warning("FailproofAI could not write its heartbeat in %s: %s", state_dir, exc)
+        if temporary is not None:
+            try:
+                temporary.unlink(missing_ok=True)
+            except Exception:
+                pass
+
+
 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()
+        plugin_id = _plugin_id(ctx)
+        read = _config_reader(ctx, plugin_id)
+
+        def setting(key: str, default: Any) -> Any:
+            try:
+                return read(key, default)
+            except Exception as exc:
+                logger.warning("FailproofAI setting %s unreadable; using %r: %s", key, default, exc)
+                return default
+
+        self.failure_mode = str(setting("failure_mode", "deny")).strip().lower()
         self.connect_timeout_ms = _bounded_int(
-            ctx.get_config("connect_timeout_ms", 250), 250, 25, 5_000
+            setting("connect_timeout_ms", 250), 250, 25, 5_000
         )
+        # The client spends one deadline on connect + send + read, so this is
+        # the whole time a tool call can wait on FailproofAI.
         self.evaluation_timeout_ms = _bounded_int(
-            ctx.get_config("evaluation_timeout_ms", 12_000), 12_000, 100, 29_000
+            setting("evaluation_timeout_ms", 12_000), 12_000, 100, _EVALUATION_TIMEOUT_CAP_MS
         )
         ttl_seconds = _bounded_int(
-            ctx.get_config("instruction_ttl_seconds", 3_600), 3_600, 60, 86_400
+            setting("instruction_ttl_seconds", 3_600), 3_600, 60, 86_400
         )
         max_rounds = _bounded_int(
-            ctx.get_config("max_instruction_rounds", 2), 2, 0, 10
+            setting("max_instruction_rounds", 2), 2, 0, 10
         )
+        # Without a state directory only instruct() degrades (see LedgerError
+        # below); allow and deny never touch the ledger.
+        state_dir = _state_dir(ctx, plugin_id)
+        self.state_dir = state_dir
         self.ledger = InstructionLedger(
-            Path(ctx.state.data_dir) / "instructions.db",
+            state_dir / "instructions.db" if state_dir is not None else None,
             ttl_seconds=ttl_seconds,
             max_rounds=max_rounds,
         )
+        # Set by register() once Hermes accepts the tool_execution middleware.
+        # Until then an instruct verdict blocks once through the ledger above.
+        self.wraps_execution = False
+        self._frames: contextvars.ContextVar[tuple[_ReminderFrame, ...]] = contextvars.ContextVar(
+            f"failproofai_reminder_frames_{id(self)}", default=()
+        )
+        self._handoff = _ReminderHandoff()
+        self._delivered = _TurnDeliveries()
 
     def _fallback(self, error: Exception) -> dict[str, str] | None:
         logger.error("FailproofAI evaluator unavailable: %s", error)
@@ -78,16 +652,19 @@ class FailproofAIPlugin:
             ),
         }
 
-    def _evaluate(self, event: str, payload: Mapping[str, Any]) -> PolicyVerdict:
+    def _evaluate(
+        self, event: str, payload: Mapping[str, Any], timeout_ms: int | None = None
+    ) -> 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,
+            evaluation_timeout_ms=timeout_ms or self.evaluation_timeout_ms,
         )
 
+    @_guarded(_block_on_internal_error)
     def pre_tool_call(
         self,
         tool_name: str = "",
@@ -118,6 +695,11 @@ class FailproofAIPlugin:
         except Exception as exc:
             return self._fallback(exc)
 
+        if verdict.decision in ("allow", "deny"):
+            # An identical earlier call that never reached its frame (another
+            # plugin blocked it) left a reminder under this call's key; this
+            # call's own verdict replaces it.
+            self._drop_handoff(session_id, task_id, tool_call_id, tool_name, payload["tool_input"])
         if verdict.decision == "allow":
             return None
         if verdict.decision == "deny":
@@ -126,7 +708,20 @@ class FailproofAIPlugin:
                 "message": verdict.reason or "Blocked by FailproofAI policy.",
             }
 
-        reason = verdict.reason or "Reconsider this tool call before retrying."
+        if self._remind(
+            verdict,
+            tool_name=tool_name,
+            tool_input=payload["tool_input"],
+            session_id=session_id,
+            task_id=task_id,
+            tool_call_id=tool_call_id,
+        ):
+            return None
+
+        # Host without the tool_execution middleware: hold the call once so the
+        # guidance is seen. The scope is the policy (+ reason) in this turn, not
+        # the tool, so moving the same work to another tool is not held again.
+        reason = verdict.reason or "Apply this policy to the call."
         try:
             action = self.ledger.decide(
                 profile=self.profile,
@@ -136,7 +731,7 @@ class FailproofAIPlugin:
                 api_request_id=api_request_id,
                 policy_names=verdict.policy_names,
                 reason=reason,
-                scope_key=verdict.tool_name or tool_name or "unknown-tool",
+                scope_key="policy",
             )
         except LedgerError as exc:
             # An advisory instruction must never become an indefinite denial
@@ -153,18 +748,151 @@ class FailproofAIPlugin:
         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."
+                f"FailproofAI policy guidance ({policies})\n\n{reason}\n\n"
+                "This call was held once so you could read this guidance. Apply it, then "
+                "continue; repeating the same call is allowed."
             ),
         }
 
+    def _drop_handoff(self, session_id: str, task_id: str, tool_call_id: str, tool_name: str,
+                      tool_input: Mapping[str, Any]) -> None:
+        try:
+            if self._handoff.pending():
+                self._handoff.take(_call_key(session_id, task_id, tool_call_id, tool_name, tool_input))
+        except Exception as exc:
+            logger.warning("FailproofAI could not clear a stale reminder handoff: %s", exc)
+
+    def _innermost_frame(self) -> _ReminderFrame | None:
+        frames = self._frames.get()
+        if frames and frames[-1].open:
+            return frames[-1]
+        return None
+
+    def _remind(
+        self,
+        verdict: PolicyVerdict,
+        *,
+        tool_name: str,
+        tool_input: Mapping[str, Any],
+        session_id: str,
+        task_id: str,
+        tool_call_id: str,
+    ) -> bool:
+        """Queue an instruct verdict as a reminder on the call's own result.
+        False when nothing will carry it; the caller then blocks once."""
+        reminder = _Reminder(
+            ", ".join(verdict.policy_names) or "unknown policy",
+            verdict.reason or "Apply this policy when you use the result.",
+        )
+        frame = self._innermost_frame()
+        if frame is not None and frame.owns(tool_name, tool_call_id):
+            frame.add((reminder,))
+            return True
+        if not self.wraps_execution:
+            return False
+        # Not inside this call's own frame: model_tools ran pre_tool_call
+        # before the middleware, which claims this when the frame opens.
+        self._handoff.put(
+            _call_key(session_id, task_id, tool_call_id, tool_name, tool_input), reminder
+        )
+        if frame is not None and not tool_call_id:
+            # A programmatic call (execute_code RPC) inside a model-issued one:
+            # no model reads the inner result, so the outer result carries it
+            # too, even if the inner call never reaches its own frame.
+            frame.add((reminder,))
+        return True
+
+    def tool_execution(
+        self,
+        tool_name: str = "",
+        args: Any = None,
+        next_call: Callable[[Any], Any] | None = None,
+        session_id: str = "",
+        task_id: str = "",
+        tool_call_id: str = "",
+        turn_id: str = "",
+        **kwargs: Any,
+    ) -> Any:
+        """Hermes tool_execution middleware: run the call once, then attach any
+        reminders its pre_tool_call (or nested programmatic calls) collected.
+        Only the tool's own exception leaves this method; FailproofAI's own
+        failures fall back to the plain result."""
+        if not callable(next_call):
+            # Nothing to run. Raising before next_call makes Hermes skip this
+            # middleware and run the rest of the chain, so the tool still runs.
+            raise TypeError("tool_execution middleware called without next_call")
+        try:
+            stack = self._frames.get()
+            parent = stack[-1] if stack and stack[-1].open else None
+            frame = _ReminderFrame(_string(tool_name), _string(tool_call_id), parent)
+
+            def claim() -> None:
+                if self._handoff.pending():
+                    frame.add(self._handoff.take(
+                        _call_key(session_id, task_id, tool_call_id, tool_name, args)
+                    ))
+
+            claim()
+            token = self._frames.set((*stack, frame))
+        except Exception as exc:
+            logger.error("FailproofAI reminder frame unavailable; running the call plainly: %s", exc)
+            return next_call(args)
+
+        reminders: tuple[_Reminder, ...] = ()
+        try:
+            result = next_call(args)
+        finally:
+            try:
+                self._frames.reset(token)
+                # A host that runs pre_tool_call without our context lands here.
+                claim()
+                reminders = frame.close()
+            except Exception as exc:
+                logger.error("FailproofAI could not close a reminder frame: %s", exc)
+        try:
+            return self._annotate(result, reminders, parent, session_id, turn_id, tool_call_id)
+        except Exception as exc:
+            logger.error("FailproofAI could not annotate a tool result: %s", exc)
+            return result
+
+    def _annotate(
+        self,
+        result: Any,
+        reminders: tuple[_Reminder, ...],
+        parent: _ReminderFrame | None,
+        session_id: object,
+        turn_id: object,
+        tool_call_id: object,
+    ) -> Any:
+        if not reminders or _unexecuted(result):
+            return result
+        if parent is not None and not tool_call_id and parent.add(reminders):
+            # A call an execute_code script made: the model reads the outer
+            # result, which now carries the reminder. The script gets this one
+            # untouched, so nothing it prints, writes or sends can carry it.
+            return result
+        session, turn = _string(session_id), _string(turn_id)
+        fresh = self._delivered.claim(session, turn, reminders)
+        if not fresh:
+            return result
+        annotated = _attach_reminders(result, fresh)
+        if annotated is result:
+            self._delivered.release(session, turn, fresh)
+        return annotated
+
     def _observe(self, event: str, payload: Mapping[str, Any]) -> None:
+        # Observers gate nothing, so they never wait a full evaluation deadline:
+        # against a hung daemon every blocked call would otherwise pay it twice
+        # (pre_tool_call, then post_tool_call). The request is sent first, so a
+        # slow but live daemon still records it.
         try:
-            self._evaluate(event, payload)
+            self._evaluate(
+                event, payload, min(self.evaluation_timeout_ms, _OBSERVE_TIMEOUT_MS)
+            )
         except Exception as exc:
             logger.warning("FailproofAI observation failed for %s: %s", event, exc)
 
+    @_guarded(_nothing)
     def post_tool_call(
         self,
         tool_name: str = "",
@@ -186,6 +914,7 @@ class FailproofAIPlugin:
             },
         )
 
+    @_guarded(_nothing)
     def on_session_start(self, session_id: str = "", **kwargs: Any) -> None:
         self._observe(
             "on_session_start",
@@ -197,6 +926,7 @@ class FailproofAIPlugin:
             },
         )
 
+    @_guarded(_nothing)
     def on_session_end(self, session_id: str = "", **kwargs: Any) -> None:
         self._observe(
             "on_session_end",
@@ -209,6 +939,7 @@ class FailproofAIPlugin:
         )
         self._clear_session(session_id)
 
+    @_guarded(_nothing)
     def subagent_stop(self, session_id: str = "", **kwargs: Any) -> None:
         self._observe(
             "subagent_stop",
@@ -220,12 +951,15 @@ class FailproofAIPlugin:
             },
         )
 
+    @_guarded(_protocol_context)
     def pre_llm_call(self, **kwargs: Any) -> dict[str, str]:
         return {"context": _PROTOCOL_CONTEXT}
 
+    @_guarded(_nothing)
     def on_session_reset(self, session_id: str = "", **kwargs: Any) -> None:
         self._clear_session(session_id)
 
+    @_guarded(_nothing)
     def on_session_finalize(self, session_id: str = "", **kwargs: Any) -> None:
         self._clear_session(session_id)
 
@@ -237,12 +971,63 @@ class FailproofAIPlugin:
 
 
 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)
+    # Hermes logs a raising register() as "Failed to load plugin" and runs
+    # every tool call unchecked, so nothing here may raise, and one rejected
+    # hook must not cost the rest. heartbeat.json records the attempt before
+    # anything else and its outcome last.
+    try:
+        state_dir = _state_dir(ctx, _plugin_id(ctx))
+    except Exception:
+        state_dir = None
+    beat = {
+        **_heartbeat_base(ctx),
+        "stage": "start",
+        "register_ok": False,
+        "hooks_registered": [],
+        "middleware_registered": False,
+    }
+    _write_heartbeat(state_dir, beat)
+
+    hooks: list[str] = []
+    error = ""
+    try:
+        plugin = FailproofAIPlugin(ctx)
+        for hook in _HOOKS:
+            try:
+                ctx.register_hook(hook, getattr(plugin, hook))
+                hooks.append(hook)
+            except Exception as exc:
+                logger.error("FailproofAI could not register Hermes hook %s: %s", hook, exc)
+        # Without the middleware an instruct verdict still reaches the model, by
+        # holding the call once.
+        if hasattr(ctx, "register_middleware"):
+            try:
+                ctx.register_middleware("tool_execution", plugin.tool_execution)
+                plugin.wraps_execution = True
+            except Exception as exc:
+                logger.error("FailproofAI could not register Hermes tool_execution middleware: %s", exc)
+        middleware = plugin.wraps_execution
+    except Exception as exc:
+        logger.exception("FailproofAI plugin failed to register")
+        error = f"{type(exc).__name__}: {exc}"
+        middleware = False
+
+    beat.update(
+        stage="end",
+        register_ok=not error and hooks == list(_HOOKS),
+        hooks_registered=hooks,
+        middleware_registered=middleware,
+    )
+    if error:
+        beat["error"] = error
+    _write_heartbeat(state_dir, beat)
+    logger.info(
+        "FailproofAI Hermes plugin %s loaded: pid=%s profile=%s hooks=%d/%d middleware=%s register_ok=%s",
+        beat.get("plugin_version") or "?",
+        beat.get("pid"),
+        beat.get("profile"),
+        len(hooks),
+        len(_HOOKS),
+        "yes" if middleware else "no",
+        beat["register_ok"],
+    )