ltcai 4.3.3 → 4.5.1

package/latticeai/core/hooks.py

@@ -1,754 +1,11 @@
-"""Hooks platform — a persisted registry of lifecycle extension points.
+"""Compatibility shim: physically moved to ``lattice_brain.runtime.hooks``.
 
-Lattice AI runs several behaviours at well-defined points in the agent / tool /
-workflow lifecycle (audit logging, secret redaction, sensitive-data
-classification, tool-permission gating, memory snapshots, workflow replay
-logging). v3.2.0 makes those points *first-class and inspectable*: every hook is
-listed, ordered, and individually enable/disable-able, and users can register
-their own custom hooks alongside the built-ins.
-
-The registry owns metadata, ordering and the enabled flag (persisted to
-``data_dir/hooks.json``). Built-in hooks carry ``source="builtin"`` and map onto
-behaviour the platform already performs; ``managed`` records whether the
-behaviour is enforced by the platform (``platform``) or is an advisory hook the
-user has registered (``user``). The registry never silently drops a hook: the
-full set is always returned so the UI can show exactly what runs and in which
-order.
+Aliases itself to the physical module so identity, module-level state, and
+monkeypatching keep working through the old import path.
 """
 
-from __future__ import annotations
-
-import json
-import os
-import shlex
-import subprocess
-import tempfile
-import threading
-import time
-from collections import deque
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
-
-
-HOOK_KINDS = (
-    "pre_run",
-    "post_run",
-    "pre_tool",
-    "post_tool",
-    "pre_workflow",
-    "post_workflow",
-    "pre_upload",
-    "post_upload",
-    "pre_index",
-    "post_index",
-    "agent",
-)
-
-# Kinds retired in v3.4.1 in favour of the explicit pre_/post_ lifecycle pairs.
-# Accepted on input and mapped forward so older callers / persisted custom hooks
-# never break.
-LEGACY_KIND_ALIASES = {
-    "workflow": "post_workflow",
-    "pipeline": "post_index",
-}
-
-# Hook statuses a dispatch can record.
-HOOK_STATUSES = ("ok", "blocked", "error", "skipped", "advisory")
-
-
-def _now() -> str:
-    return datetime.now().isoformat(timespec="seconds")
-
-
-class HookContext:
-    """Mutable execution context handed to every hook in a dispatch.
-
-    A bound hook runner may inspect or modify :attr:`payload` (e.g. redact
-    secrets in place), attach data via :meth:`set`, or halt a pending action
-    with :meth:`block`. Blocking is honoured for the ``pre_*`` kinds that gate
-    real work (a blocked ``pre_run`` stops the agent run; a blocked ``pre_tool``
-    stops the tool call).
-    """
-
-    __slots__ = (
-        "kind", "event", "payload", "metadata",
-        "user_email", "workspace_id", "blocked", "block_reason", "notes",
-    )
-
-    def __init__(
-        self,
-        kind: str,
-        event: str = "",
-        payload: Optional[Dict[str, Any]] = None,
-        *,
-        user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ):
-        self.kind = kind
-        self.event = event or kind
-        self.payload = dict(payload or {})
-        self.metadata = dict(metadata or {})
-        self.user_email = user_email
-        self.workspace_id = workspace_id
-        self.blocked = False
-        self.block_reason = ""
-        self.notes: List[str] = []
-
-    def set(self, key: str, value: Any) -> "HookContext":
-        self.payload[key] = value
-        return self
-
-    def block(self, reason: str = "") -> "HookContext":
-        self.blocked = True
-        self.block_reason = reason or "blocked by hook"
-        return self
-
-    def note(self, message: str) -> "HookContext":
-        self.notes.append(str(message))
-        return self
-
-    def as_dict(self) -> Dict[str, Any]:
-        return {
-            "kind": self.kind,
-            "event": self.event,
-            "payload": self.payload,
-            "metadata": self.metadata,
-            "user_email": self.user_email,
-            "workspace_id": self.workspace_id,
-            "blocked": self.blocked,
-            "block_reason": self.block_reason,
-            "notes": list(self.notes),
-        }
-
-
-class HookResult:
-    """The outcome of running a single hook (one entry in a dispatch)."""
-
-    __slots__ = (
-        "hook_id", "name", "kind", "status", "detail", "output",
-        "duration_ms", "blocked", "source", "binding", "started_at",
-    )
-
-    def __init__(
-        self,
-        *,
-        hook_id: str,
-        name: str = "",
-        kind: str = "",
-        status: str = "ok",
-        detail: str = "",
-        output: str = "",
-        duration_ms: int = 0,
-        blocked: bool = False,
-        source: str = "",
-        binding: str = "",
-        started_at: Optional[str] = None,
-    ):
-        self.hook_id = hook_id
-        self.name = name
-        self.kind = kind
-        self.status = status  # ok | blocked | error | skipped | advisory
-        self.detail = detail
-        self.output = output
-        self.duration_ms = duration_ms
-        self.blocked = blocked
-        self.source = source
-        self.binding = binding
-        self.started_at = started_at or _now()
-
-    def as_dict(self) -> Dict[str, Any]:
-        return {
-            "hook_id": self.hook_id,
-            "name": self.name,
-            "kind": self.kind,
-            "status": self.status,
-            "detail": self.detail,
-            "output": self.output,
-            "duration_ms": self.duration_ms,
-            "blocked": self.blocked,
-            "source": self.source,
-            "binding": self.binding,
-            "started_at": self.started_at,
-        }
-
-
-def hook_context(kind: str, event: str = "", **kwargs: Any) -> HookContext:
-    """Factory for a :class:`HookContext` (matches the public hook vocabulary)."""
-    return HookContext(kind, event, **kwargs)
-
-
-def hook_result(**kwargs: Any) -> HookResult:
-    """Factory for a :class:`HookResult`."""
-    return HookResult(**kwargs)
-
-
-def dispatch_tool(
-    hooks: Any,
-    tool_name: str,
-    args: Any,
-    run_fn: Callable[[], Any],
-    *,
-    user_email: Optional[str] = None,
-    workspace_id: Optional[str] = None,
-    source: str = "",
-) -> Any:
-    """Run a tool through the shared ``pre_tool`` → execute → ``post_tool`` lifecycle.
-
-    This is the single tool-dispatch path so every caller (the HTTP ``/tools/*``
-    routes, the single-agent runtime in :mod:`latticeai.core.agent`, and the
-    workflow tool node) fires the same hooks. A blocking ``pre_tool`` hook raises
-    :class:`PermissionError`; a tool error still fires ``post_tool`` (status
-    ``error``) before re-raising. With ``hooks=None`` it is a transparent
-    pass-through, so the tool path is unchanged when hooks are absent.
-    """
-    if hooks is None:
-        return run_fn()
-    try:
-        arg_keys = list(args.keys()) if isinstance(args, dict) else []
-    except Exception:
-        arg_keys = []
-    pre = hooks.fire_hook(
-        "pre_tool", f"tool.{tool_name}",
-        payload={"tool": tool_name, "args_keys": arg_keys, "source": source},
-        user_email=user_email, workspace_id=workspace_id,
-    )
-    if pre.get("blocked"):
-        raise PermissionError(pre.get("block_reason") or f"Tool '{tool_name}' blocked by a pre_tool hook.")
-    try:
-        result = run_fn()
-    except Exception as exc:
-        hooks.fire_hook(
-            "post_tool", f"tool.{tool_name}",
-            payload={"tool": tool_name, "status": "error", "detail": str(exc), "source": source},
-            user_email=user_email, workspace_id=workspace_id,
-        )
-        raise
-    hooks.fire_hook(
-        "post_tool", f"tool.{tool_name}",
-        payload={"tool": tool_name, "status": "ok", "source": source},
-        user_email=user_email, workspace_id=workspace_id,
-    )
-    return result
-
-
-# Built-in hooks describe lifecycle points the platform already exercises. They
-# are honest reflections of existing behaviour (see the `binding` field), made
-# visible and orderable here. Disabling a `managed="platform"` hook is recorded
-# and surfaced, but core safety behaviours remain enforced by their owning
-# subsystem — the UI states this explicitly so nothing is misrepresented.
-BUILTIN_HOOKS: List[Dict[str, Any]] = [
-    {
-        "id": "builtin:redact-secrets",
-        "name": "Redact secrets",
-        "kind": "pre_run",
-        "order": 10,
-        "description": "Strip secret-like fields (token, password, api_key…) from agent context packets before a run.",
-        "binding": "latticeai.core.multi_agent._redact",
-        "managed": "platform",
-    },
-    {
-        "id": "builtin:research-memory-snapshot",
-        "name": "Research memory snapshot",
-        "kind": "agent",
-        "order": 20,
-        "description": "Capture a short-term memory snapshot after the researcher stage gathers context.",
-        "binding": "latticeai.core.multi_agent.default_role_runner",
-        "managed": "platform",
-    },
-    {
-        "id": "builtin:tool-permission-gate",
-        "name": "Tool permission gate",
-        "kind": "pre_tool",
-        "order": 10,
-        "description": "Require explicit approval for tools whose governance policy is not auto-approve.",
-        "binding": "latticeai.core.tool_registry.ToolRegistry.permission",
-        "managed": "platform",
-    },
-    {
-        "id": "builtin:sensitive-data-guard",
-        "name": "Sensitive-data guard",
-        "kind": "pre_tool",
-        "order": 20,
-        "description": "Classify outgoing content for sensitive data before tool execution.",
-        "binding": "server_app.classify_sensitive_message",
-        "managed": "platform",
-    },
-    {
-        "id": "builtin:audit-agent-run",
-        "name": "Audit agent run",
-        "kind": "post_run",
-        "order": 10,
-        "description": "Append every completed agent run to the workspace audit log.",
-        "binding": "latticeai.services.agent_runtime.AgentRuntime.start",
-        "managed": "platform",
-    },
-    {
-        "id": "builtin:workflow-replay-log",
-        "name": "Workflow replay log",
-        "kind": "workflow",
-        "order": 10,
-        "description": "Record each workflow run's timeline so it can be replayed step by step.",
-        "binding": "latticeai.api.workflow_designer",
-        "managed": "platform",
-    },
-    {
-        "id": "builtin:pipeline-index-status",
-        "name": "Pipeline index status",
-        "kind": "pipeline",
-        "order": 10,
-        "description": "Publish ingest / embed / graph-build pipeline state to the retrieval index status.",
-        "binding": "latticeai.api.search",
-        "managed": "platform",
-    },
-]
-
-# Built-in hooks now bucket onto the v3.4.1 lifecycle pairs.
-for _hook in BUILTIN_HOOKS:
-    _hook["kind"] = LEGACY_KIND_ALIASES.get(_hook["kind"], _hook["kind"])
-del _hook
-
-
-class HooksRegistry:
-    """Persisted registry of lifecycle hooks (built-in + user-registered)."""
-
-    def __init__(self, path: Path, *, command_timeout: float = 20.0, run_log_limit: int = 100):
-        self.path = Path(path)
-        self._state: Dict[str, Any] = self._load()
-        # Runtime dispatch state: in-process runners bound to hook ids, plus a
-        # bounded, persisted log of recent executions so the UI can show that
-        # hooks actually ran (not just that they are registered).
-        self._runtime_runners: Dict[str, Callable[[HookContext], Any]] = {}
-        self._command_timeout = float(command_timeout)
-        self._run_lock = threading.Lock()
-        self._runs_path = self.path.parent / "hooks_runs.json"
-        self._runs: deque = deque(self._load_runs(), maxlen=int(run_log_limit))
-
-    # ── persistence ───────────────────────────────────────────────────────
-    def _load(self) -> Dict[str, Any]:
-        if self.path.exists():
-            try:
-                with open(self.path, "r", encoding="utf-8") as fh:
-                    data = json.load(fh)
-                if isinstance(data, dict):
-                    data.setdefault("custom", [])
-                    data.setdefault("overrides", {})
-                    return data
-            except Exception:
-                pass
-        return {"custom": [], "overrides": {}}
-
-    def _save(self) -> None:
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        fd, tmp = tempfile.mkstemp(dir=str(self.path.parent), suffix=".tmp")
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as fh:
-                json.dump(self._state, fh, ensure_ascii=False, indent=2)
-            os.replace(tmp, self.path)
-        finally:
-            if os.path.exists(tmp):
-                os.unlink(tmp)
-
-    # ── views ─────────────────────────────────────────────────────────────
-    def _materialize(self) -> List[Dict[str, Any]]:
-        overrides: Dict[str, Any] = self._state.get("overrides", {})
-        hooks: List[Dict[str, Any]] = []
-        for base in BUILTIN_HOOKS:
-            ov = overrides.get(base["id"], {})
-            hook = dict(base)
-            hook["source"] = "builtin"
-            hook["enabled"] = bool(ov.get("enabled", True))
-            if "order" in ov:
-                hook["order"] = ov["order"]
-            hook["removable"] = False
-            hooks.append(hook)
-        for custom in self._state.get("custom", []):
-            hook = dict(custom)
-            hook["source"] = "user"
-            hook.setdefault("managed", "user")
-            hook.setdefault("binding", "advisory")
-            hook["enabled"] = bool(custom.get("enabled", True))
-            hook["removable"] = True
-            hooks.append(hook)
-        # Honest execution flag: a hook actually runs only if a runner is bound
-        # (built-ins) or it carries a command (user hooks); otherwise it is
-        # advisory (listed + ordered, but a no-op when fired).
-        for hook in hooks:
-            hook["executable"] = self.has_runner(hook["id"]) or bool(str(hook.get("command") or "").strip())
-            hook["advisory"] = not hook["executable"]
-        hooks.sort(key=lambda h: (HOOK_KINDS.index(h["kind"]) if h["kind"] in HOOK_KINDS else 99, h.get("order", 100), h["id"]))
-        return hooks
-
-    def list(self, kind: Optional[str] = None) -> Dict[str, Any]:
-        hooks = self._materialize()
-        if kind:
-            hooks = [h for h in hooks if h["kind"] == kind]
-        counts: Dict[str, Dict[str, int]] = {}
-        for h in self._materialize():
-            bucket = counts.setdefault(h["kind"], {"total": 0, "enabled": 0})
-            bucket["total"] += 1
-            if h["enabled"]:
-                bucket["enabled"] += 1
-        return {
-            "hooks": hooks,
-            "kinds": list(HOOK_KINDS),
-            "counts": counts,
-            "total": len(hooks),
-            "enabled": sum(1 for h in hooks if h["enabled"]),
-            "generated_at": _now(),
-        }
-
-    def get(self, hook_id: str) -> Optional[Dict[str, Any]]:
-        return next((h for h in self._materialize() if h["id"] == hook_id), None)
-
-    def inspect(self, hook_id: str) -> Dict[str, Any]:
-        hook = self.get(hook_id)
-        if hook is None:
-            raise KeyError(hook_id)
-        detail = dict(hook)
-        detail["advisory"] = hook.get("managed") != "platform"
-        detail["note"] = (
-            "Enforced by its owning subsystem; the registry controls visibility and ordering."
-            if hook.get("managed") == "platform"
-            else "User-registered hook: listed, ordered and inspectable; runs advisory in this build."
-        )
-        return detail
-
-    # ── mutations ─────────────────────────────────────────────────────────
-    def set_enabled(self, hook_id: str, enabled: bool) -> Dict[str, Any]:
-        if self.get(hook_id) is None:
-            raise KeyError(hook_id)
-        if hook_id.startswith("builtin:"):
-            self._state.setdefault("overrides", {}).setdefault(hook_id, {})["enabled"] = bool(enabled)
-        else:
-            for custom in self._state.get("custom", []):
-                if custom["id"] == hook_id:
-                    custom["enabled"] = bool(enabled)
-        self._save()
-        return self.get(hook_id)  # type: ignore[return-value]
-
-    def set_order(self, hook_id: str, order: int) -> Dict[str, Any]:
-        if self.get(hook_id) is None:
-            raise KeyError(hook_id)
-        order = int(order)
-        if hook_id.startswith("builtin:"):
-            self._state.setdefault("overrides", {}).setdefault(hook_id, {})["order"] = order
-        else:
-            for custom in self._state.get("custom", []):
-                if custom["id"] == hook_id:
-                    custom["order"] = order
-        self._save()
-        return self.get(hook_id)  # type: ignore[return-value]
-
-    def reorder(self, kind: str, ordered_ids: List[str]) -> Dict[str, Any]:
-        for idx, hook_id in enumerate(ordered_ids):
-            try:
-                self.set_order(hook_id, (idx + 1) * 10)
-            except KeyError:
-                continue
-        return self.list(kind=kind)
-
-    def register(
-        self,
-        *,
-        name: str,
-        kind: str,
-        description: str = "",
-        command: str = "",
-        order: Optional[int] = None,
-        enabled: bool = True,
-    ) -> Dict[str, Any]:
-        if not str(name).strip():
-            raise ValueError("name is required")
-        kind = LEGACY_KIND_ALIASES.get(kind, kind)
-        if kind not in HOOK_KINDS:
-            raise ValueError(f"kind must be one of {', '.join(HOOK_KINDS)}")
-        slug = str(name).strip().lower().replace(" ", "-")
-        hook_id = f"user:{slug}"
-        existing = {c["id"] for c in self._state.get("custom", [])}
-        if hook_id in existing:
-            hook_id = f"user:{slug}-{len(existing) + 1}"
-        entry = {
-            "id": hook_id,
-            "name": str(name).strip(),
-            "kind": kind,
-            "description": str(description or "").strip(),
-            "command": str(command or "").strip(),
-            "order": int(order) if order is not None else 100,
-            "enabled": bool(enabled),
-            "managed": "user",
-            "binding": "advisory",
-            "created_at": _now(),
-        }
-        self._state.setdefault("custom", []).append(entry)
-        self._save()
-        return entry
-
-    def remove(self, hook_id: str) -> Dict[str, Any]:
-        if hook_id.startswith("builtin:"):
-            raise ValueError("Built-in hooks cannot be removed; disable them instead.")
-        before = len(self._state.get("custom", []))
-        self._state["custom"] = [c for c in self._state.get("custom", []) if c["id"] != hook_id]
-        if len(self._state["custom"]) == before:
-            raise KeyError(hook_id)
-        self._save()
-        return {"removed": hook_id}
-
-    # ── execution engine ──────────────────────────────────────────────────
-    # The registry above owns *what* runs and in *what order*. The methods below
-    # own *running* it: a hook executes either via an in-process runner bound by
-    # its owning subsystem (built-ins) or, for user hooks, by running their
-    # ``command`` as a subprocess. ``pre_*`` hooks can block the pending action.
-
-    def register_hook(self, hook_id: str, runner: Callable[[HookContext], Any]) -> "HooksRegistry":
-        """Bind a callable that *executes* when ``hook_id`` fires.
-
-        Built-in hooks bind their owning subsystem's real behaviour here at app
-        startup so dispatch performs actual work rather than a placeholder.
-        Returns ``self`` so registrations can be chained.
-        """
-        if not callable(runner):
-            raise TypeError("runner must be callable")
-        self._runtime_runners[hook_id] = runner
-        return self
-
-    # Alias — descriptive name used by the wiring layer.
-    register_runtime_hook = register_hook
-
-    def unregister_hook(self, hook_id: str) -> None:
-        self._runtime_runners.pop(hook_id, None)
-
-    def has_runner(self, hook_id: str) -> bool:
-        return hook_id in self._runtime_runners
-
-    def run_hooks(
-        self,
-        kind: str,
-        context: Optional[HookContext] = None,
-        *,
-        event: Optional[str] = None,
-        payload: Optional[Dict[str, Any]] = None,
-        user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Run every enabled hook of ``kind``, in order, against one context.
-
-        Returns the dispatch record: which hooks ran, whether the pending action
-        was blocked, and a per-hook result list. A ``pre_*`` hook that blocks
-        short-circuits the remaining hooks (fail-closed gate semantics).
-        """
-        kind = LEGACY_KIND_ALIASES.get(kind, kind)
-        if kind not in HOOK_KINDS:
-            raise ValueError(f"kind must be one of {', '.join(HOOK_KINDS)}")
-        if context is None:
-            context = HookContext(
-                kind, event=event or kind, payload=payload,
-                user_email=user_email, workspace_id=workspace_id, metadata=metadata,
-            )
-        hooks = [h for h in self._materialize() if h["kind"] == kind and h.get("enabled")]
-        results: List[HookResult] = []
-        for hook in hooks:
-            res = self._run_one(hook, context)
-            results.append(res)
-            self._record_run(res, context)
-            if res.blocked:
-                context.block(res.detail or f"{hook['id']} blocked {context.event}")
-                break
-        return {
-            "kind": kind,
-            "event": context.event,
-            "ran": len(results),
-            "blocked": context.blocked,
-            "block_reason": context.block_reason,
-            "results": [r.as_dict() for r in results],
-            "generated_at": _now(),
-        }
-
-    def run_hook(
-        self,
-        hook_id: str,
-        context: Optional[HookContext] = None,
-        *,
-        event: Optional[str] = None,
-        payload: Optional[Dict[str, Any]] = None,
-        user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Run a single hook by id (regardless of kind ordering)."""
-        hook = self.get(hook_id)
-        if hook is None:
-            raise KeyError(hook_id)
-        if context is None:
-            context = HookContext(
-                hook["kind"], event=event or hook_id, payload=payload,
-                user_email=user_email, workspace_id=workspace_id, metadata=metadata,
-            )
-        if not hook.get("enabled"):
-            res = HookResult(
-                hook_id=hook_id, name=hook.get("name", hook_id), kind=hook["kind"],
-                status="skipped", detail="hook disabled",
-                source=hook.get("source", ""), binding=hook.get("binding", ""),
-            )
-        else:
-            res = self._run_one(hook, context)
-        self._record_run(res, context)
-        return res.as_dict()
-
-    def fire_hook(
-        self,
-        kind: str,
-        event: str = "",
-        *,
-        payload: Optional[Dict[str, Any]] = None,
-        user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        context: Optional[HookContext] = None,
-    ) -> Dict[str, Any]:
-        """Fire-and-forget convenience over :meth:`run_hooks`.
-
-        Never raises — a dispatch failure is captured in the returned record so
-        a hook misconfiguration can never crash the lifecycle point that fired
-        it. Callers that need to *gate* on a block should read ``["blocked"]``.
-        """
-        try:
-            return self.run_hooks(
-                kind, context, event=event or kind, payload=payload,
-                user_email=user_email, workspace_id=workspace_id, metadata=metadata,
-            )
-        except Exception as exc:  # pragma: no cover - defensive
-            return {"kind": kind, "event": event or kind, "ran": 0, "blocked": False,
-                    "block_reason": "", "error": str(exc), "results": [], "generated_at": _now()}
-
-    # ── single-hook execution ─────────────────────────────────────────────
-    def _run_one(self, hook: Dict[str, Any], context: HookContext) -> HookResult:
-        hook_id = hook["id"]
-        start = time.perf_counter()
-        runner = self._runtime_runners.get(hook_id)
-        try:
-            if runner is not None:
-                out = runner(context)
-                status, detail, output, blocked = self._interpret_runner_output(out, context)
-            elif str(hook.get("command") or "").strip():
-                status, detail, output, blocked = self._run_command(hook, context)
-            else:
-                # No bound runner and no command → advisory (listed + ordered only).
-                status, detail, output, blocked = "advisory", "", "", False
-        except Exception as exc:  # a misbehaving hook never breaks the dispatch
-            status, detail, output, blocked = "error", str(exc)[:500], "", False
-        duration_ms = int((time.perf_counter() - start) * 1000)
-        return HookResult(
-            hook_id=hook_id,
-            name=hook.get("name", hook_id),
-            kind=hook["kind"],
-            status=status,
-            detail=detail,
-            output=output,
-            duration_ms=duration_ms,
-            blocked=blocked,
-            source=hook.get("source", ""),
-            binding=hook.get("binding", ""),
-        )
-
-    @staticmethod
-    def _interpret_runner_output(out: Any, context: HookContext):
-        """Normalize a runner's return value into (status, detail, output, blocked).
-
-        A runner may return ``None`` (ok), a ``str`` (ok + output text), or a
-        dict ``{status?, detail?, output?, block?}``. Calling ``context.block()``
-        also blocks, regardless of the return value.
-        """
-        blocked = bool(getattr(context, "blocked", False))
-        if isinstance(out, dict):
-            status = str(out.get("status") or ("blocked" if (out.get("block") or blocked) else "ok"))
-            block = bool(out.get("block")) or blocked or status == "blocked"
-            detail = str(out.get("detail") or context.block_reason or "")[:500]
-            return status, detail, str(out.get("output") or "")[:4000], block
-        if isinstance(out, str):
-            return ("blocked" if blocked else "ok", context.block_reason if blocked else "", out[:4000], blocked)
-        # None or anything else → ok (or blocked if the runner called context.block()).
-        return ("blocked" if blocked else "ok", context.block_reason if blocked else "", "", blocked)
-
-    def _run_command(self, hook: Dict[str, Any], context: HookContext):
-        """Run a user hook's ``command`` as a subprocess with the context on stdin.
-
-        The full context is provided both as the ``LATTICE_HOOK_CONTEXT`` env var
-        and on stdin (JSON). Exit code 0 = ok. A non-zero exit from a ``pre_*``
-        hook gates (blocks) the pending action; from any other kind it is
-        recorded as an error without blocking. A timeout fails closed for gates.
-        """
-        cmd = str(hook.get("command") or "").strip()
-        try:
-            argv = shlex.split(cmd)
-        except ValueError as exc:
-            return "error", f"invalid command: {exc}", "", False
-        if not argv:
-            return "skipped", "empty command", "", False
-        ctx_json = json.dumps(context.as_dict(), ensure_ascii=False)
-        env = dict(os.environ)
-        env.update({
-            "LATTICE_HOOK_KIND": context.kind,
-            "LATTICE_HOOK_EVENT": context.event,
-            "LATTICE_HOOK_ID": str(hook.get("id", "")),
-            "LATTICE_HOOK_CONTEXT": ctx_json,
-        })
-        is_gate = context.kind.startswith("pre_")
-        try:
-            proc = subprocess.run(
-                argv, input=ctx_json, capture_output=True, text=True,
-                timeout=self._command_timeout, env=env,
-            )
-        except subprocess.TimeoutExpired:
-            return ("blocked" if is_gate else "error",
-                    f"timed out after {self._command_timeout:.0f}s", "", is_gate)
-        except Exception as exc:
-            return "error", str(exc)[:500], "", False
-        output = (proc.stdout or "")[:4000]
-        if proc.returncode == 0:
-            return "ok", "", output, False
-        detail = (proc.stderr or proc.stdout or f"exit code {proc.returncode}").strip()[:500]
-        return ("blocked" if is_gate else "error", detail, output, is_gate)
-
-    # ── run log ────────────────────────────────────────────────────────────
-    def _load_runs(self) -> List[Dict[str, Any]]:
-        try:
-            if self._runs_path.exists():
-                with open(self._runs_path, "r", encoding="utf-8") as fh:
-                    data = json.load(fh)
-                if isinstance(data, list):
-                    return data
-        except Exception:
-            pass
-        return []
-
-    def _save_runs(self) -> None:
-        try:
-            self._runs_path.parent.mkdir(parents=True, exist_ok=True)
-            fd, tmp = tempfile.mkstemp(dir=str(self._runs_path.parent), suffix=".tmp")
-            with os.fdopen(fd, "w", encoding="utf-8") as fh:
-                json.dump(list(self._runs), fh, ensure_ascii=False, indent=2)
-            os.replace(tmp, self._runs_path)
-        except Exception:  # pragma: no cover - the run log is best-effort
-            pass
+import sys
 
-    def _record_run(self, result: HookResult, context: HookContext) -> None:
-        entry = result.as_dict()
-        entry["target_event"] = context.event
-        entry["target_kind"] = context.kind
-        with self._run_lock:
-            self._runs.appendleft(entry)
-            self._save_runs()
+import lattice_brain.runtime.hooks as _impl
 
-    def recent_runs(self, limit: int = 50, kind: Optional[str] = None) -> Dict[str, Any]:
-        with self._run_lock:
-            runs = list(self._runs)
-        if kind:
-            runs = [r for r in runs if r.get("target_kind") == kind or r.get("kind") == kind]
-        return {
-            "runs": runs[: max(0, int(limit))],
-            "total": len(runs),
-            "generated_at": _now(),
-        }
+sys.modules[__name__] = _impl