ltcai 3.4.0 → 3.5.0

package/latticeai/api/auth.py

@@ -1,17 +1,21 @@
 """Authentication API router: register, login, logout, SSO, profile."""
 
-import base64
-import json
 import logging
 import secrets
 import time
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple
 from urllib.parse import urlencode
 
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import JSONResponse, RedirectResponse
 from pydantic import BaseModel
 
+from latticeai.core.oidc import (
+    OIDCValidationError,
+    fetch_jwks as _default_fetch_jwks,
+    verify_id_token as _default_verify_id_token,
+)
+
 
 class UserRegister(BaseModel):
     email: str
@@ -35,7 +39,9 @@ class UpdateProfileRequest(BaseModel):
     nickname: Optional[str] = None
 
 
-_sso_states: Dict[str, float] = {}
+# state → (issued_at, nonce). The nonce binds the eventual ID token to *this*
+# login attempt (replay / token-injection defence); the timestamp expires it.
+_sso_states: Dict[str, Tuple[float, str]] = {}
 
 
 def create_auth_router(
@@ -58,6 +64,8 @@ def create_auth_router(
     open_registration: bool,
     session_ttl: int,
     require_auth: bool = True,
+    verify_id_token: Callable[..., Dict] = _default_verify_id_token,
+    fetch_jwks: Callable[[str], Awaitable[Dict]] = _default_fetch_jwks,
 ) -> APIRouter:
     router = APIRouter()
 
@@ -114,13 +122,15 @@ def create_auth_router(
         if not settings.get("enabled") or not discovery:
             raise HTTPException(status_code=503, detail="SSO가 설정되지 않았습니다.")
         state = secrets.token_urlsafe(16)
-        _sso_states[state] = time.time()
+        nonce = secrets.token_urlsafe(16)
+        _sso_states[state] = (time.time(), nonce)
         params = urlencode({
             "client_id": settings["client_id"],
             "response_type": "code",
             "redirect_uri": settings["redirect_uri"],
             "scope": settings.get("scopes") or "openid email profile",
             "state": state,
+            "nonce": nonce,
         })
         return RedirectResponse(f"{discovery['authorization_endpoint']}?{params}")
 
@@ -128,9 +138,10 @@ def create_auth_router(
     async def sso_callback(code: str = "", state: str = "", error: str = ""):
         if error:
             return RedirectResponse(f"/?sso_error={error}")
-        ts = _sso_states.pop(state, None)
-        if ts is None or time.time() - ts > 300:
+        entry = _sso_states.pop(state, None)
+        if entry is None or time.time() - entry[0] > 300:
             raise HTTPException(status_code=400, detail="유효하지 않은 SSO 상태입니다.")
+        _, nonce = entry
         settings = get_sso_settings()
         discovery = await get_sso_discovery()
         if not settings.get("enabled") or not discovery:
@@ -148,8 +159,25 @@ def create_auth_router(
         id_token = tokens.get("id_token")
         if not id_token:
             raise HTTPException(status_code=400, detail="ID 토큰을 받지 못했습니다.")
-        padded = id_token.split(".")[1] + "=="
-        payload = json.loads(base64.urlsafe_b64decode(padded))
+        # Never trust a decoded JWT payload: verify signature (against the
+        # provider JWKS), issuer, audience, expiry and the login nonce before
+        # using any claim. Any failure is fail-closed (401).
+        issuer = discovery.get("issuer") or ""
+        try:
+            jwks = await fetch_jwks(discovery.get("jwks_uri", ""))
+            payload = verify_id_token(
+                id_token,
+                jwks=jwks,
+                issuer=issuer,
+                audience=settings["client_id"],
+                nonce=nonce,
+            )
+        except OIDCValidationError as exc:
+            logging.warning("SSO ID token rejected: %s", exc)
+            raise HTTPException(status_code=401, detail="SSO 토큰 검증에 실패했습니다.")
+        except Exception as exc:  # discovery/JWKS fetch failure → fail closed
+            logging.warning("SSO token validation error: %s", exc)
+            raise HTTPException(status_code=502, detail="SSO 공급자 검증에 실패했습니다.")
         email = payload.get("email") or payload.get("preferred_username") or payload.get("upn") or ""
         if not email:
             raise HTTPException(status_code=400, detail="이메일을 확인할 수 없습니다.")

package/latticeai/api/chat.py

@@ -24,6 +24,7 @@ from PIL import Image
 from latticeai.core.agent import AgentRunContext, AgentState
 from latticeai.core.context_builder import format_sources_footnote, retrieve_context_for_generation
 from latticeai.core.document_generator import DocumentGenerationSession, detect_document_intent
+from latticeai.core.hooks import dispatch_tool
 from latticeai.services.chat_service import ChatService
 from latticeai.services.tool_dispatch import build_agent_runtime, collect_created_files
 from telegram_bot import broadcast_web_chat
@@ -144,6 +145,7 @@ def create_chat_router(
     knowledge_graph,
     public_model: str,
     base_dir: Path,
+    hooks=None,
 ) -> APIRouter:
     api_router = APIRouter()
     router = model_router
@@ -247,6 +249,7 @@ def create_chat_router(
         clear_history=clear_history,
         knowledge_save=knowledge_save,
         audit=append_audit_event,
+        hooks=hooks,
     )
 
     @api_router.post("/chat")
@@ -651,7 +654,9 @@ def create_chat_router(
         for case in eval_cases:
             case_id = case.get("id", "?")
             try:
-                result   = execute_tool(action_name, case.get("input", {}))
+                case_input = case.get("input", {})
+                result   = dispatch_tool(hooks, action_name, case_input,
+                                         lambda: execute_tool(action_name, case_input), source="eval")
                 criteria = case.get("pass_criteria", "")
                 if "success == true" in criteria:
                     passed = result.get("success") is True

package/latticeai/api/computer_use.py

@@ -11,6 +11,7 @@ from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 
 from latticeai.core.agent import extract_action as _extract_agent_action
+from latticeai.core.hooks import dispatch_tool
 from tools import (
     ToolError,
     computer_click,
@@ -105,9 +106,15 @@ class CuDragRequest(BaseModel):
     y2: int
 
 
-def create_computer_use_router(*, model_router, require_user, tool_response, save_to_history) -> APIRouter:
+def create_computer_use_router(*, model_router, require_user, tool_response, save_to_history, hooks=None) -> APIRouter:
     router = APIRouter()
 
+    def _dispatch(name, args, fn):
+        # Run a computer-use action through the unified pre_tool/post_tool
+        # lifecycle. With hooks=None this is a transparent pass-through, so the
+        # behaviour is unchanged when hooks are absent.
+        return dispatch_tool(hooks, name, dict(args or {}), fn, source="computer_use")
+
     @router.get("/tools/chrome_status")
     async def tools_chrome_status(request: Request):
         require_user(request)
@@ -122,7 +129,9 @@ def create_computer_use_router(*, model_router, require_user, tool_response, sav
     async def cu_status(request: Request):
         require_user(request)
         try:
-            return computer_status()
+            return _dispatch("computer_status", {}, computer_status)
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc))
         except ToolError as exc:
             raise HTTPException(status_code=400, detail=str(exc))
 
@@ -130,7 +139,9 @@ def create_computer_use_router(*, model_router, require_user, tool_response, sav
     async def cu_screenshot(request: Request):
         require_user(request)
         try:
-            return computer_screenshot()
+            return _dispatch("computer_screenshot", {}, computer_screenshot)
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc))
         except ToolError as exc:
             raise HTTPException(status_code=400, detail=str(exc))
 
@@ -196,7 +207,8 @@ def create_computer_use_router(*, model_router, require_user, tool_response, sav
                             "action",
                             {"step": 1, "action": "computer_open_url", "args": {"url": url, "app": "Google Chrome"}},
                         )
-                        result = computer_open_url(url, "Google Chrome")
+                        result = _dispatch("computer_open_url", {"url": url, "app": "Google Chrome"},
+                                           lambda: computer_open_url(url, "Google Chrome"))
                         yield _send("result", {"step": 1, "action": "computer_open_url", "result": result})
                         message = f"Google Chrome에서 {url}을 열었습니다."
                         action_name = "computer_open_url"
@@ -205,14 +217,15 @@ def create_computer_use_router(*, model_router, require_user, tool_response, sav
                             "action",
                             {"step": 1, "action": "computer_open_app", "args": {"app": "Google Chrome"}},
                         )
-                        result = computer_open_app("Google Chrome")
+                        result = _dispatch("computer_open_app", {"app": "Google Chrome"},
+                                           lambda: computer_open_app("Google Chrome"))
                         yield _send("result", {"step": 1, "action": "computer_open_app", "result": result})
                         message = "Google Chrome을 열었습니다."
                         action_name = "computer_open_app"
                     save_to_history("user", req.task, source="web", conversation_id=req.conversation_id)
                     save_to_history("assistant", message, source="web", conversation_id=req.conversation_id)
                     yield _send("final", {"message": message, "steps": [{"step": 1, "action": action_name, "result": result}]})
-                except ToolError as exc:
+                except (ToolError, PermissionError) as exc:
                     yield _send("tool_error", {"step": 1, "action": "computer_open_app", "error": str(exc)})
                 return
 
@@ -256,7 +269,7 @@ def create_computer_use_router(*, model_router, require_user, tool_response, sav
 
                 yield _send("action", {"step": step + 1, "action": name, "args": args})
                 try:
-                    result = execute_tool(name, args)
+                    result = _dispatch(name, args, lambda: execute_tool(name, args))
                     if name == "computer_screenshot" and "screenshot_b64" in result:
                         last_screenshot_b64 = result["screenshot_b64"]
                         result_summary = {k: v for k, v in result.items() if k != "screenshot_b64"}
@@ -275,7 +288,7 @@ def create_computer_use_router(*, model_router, require_user, tool_response, sav
                         last_screenshot_b64 = None
                         transcript.append({"step": step + 1, "action": name, "args": args, "result": result})
                         yield _send("result", {"step": step + 1, "action": name, "result": result})
-                except (ToolError, KeyError, TypeError) as exc:
+                except (ToolError, PermissionError, KeyError, TypeError) as exc:
                     error_str = str(exc)
                     transcript.append({"step": step + 1, "action": name, "args": args, "error": error_str})
                     yield _send("tool_error", {"step": step + 1, "action": name, "error": error_str})

package/latticeai/api/local_files.py

@@ -2,7 +2,11 @@
 
 from __future__ import annotations
 
+import os
 import platform
+import time
+import uuid
+from datetime import datetime
 from pathlib import Path
 from typing import Optional
 
@@ -14,6 +18,11 @@ from knowledge_graph_api import create_knowledge_graph_router
 from local_knowledge_api import create_local_knowledge_router
 from tools import local_list, local_read, local_write
 
+try:
+    from latticeai import __version__ as _LATTICE_VERSION
+except Exception:  # pragma: no cover - defensive
+    _LATTICE_VERSION = "unknown"
+
 
 class LocalAccessRequest(BaseModel):
     path: str
@@ -37,47 +46,103 @@ def create_local_files_router(
     require_graph,
     static_dir: Path,
     local_kg_watcher,
+    hooks=None,
+    data_dir: Optional[Path] = None,
 ) -> APIRouter:
     router = APIRouter()
 
     @router.get("/api/local-agent/status")
     async def local_agent_status(request: Request):
         """Real on-device runtime status — the 'Local Agent' is the Lattice
-        server running on this machine (filesystem access + folder watching +
-        local inference), not a separate desktop process. Everything reported
-        here is observed, never faked."""
+        server running on this machine. Every field below is *probed*, not
+        hardcoded: filesystem access is a real write/read/delete; the graph and
+        watcher are reached live; the mode/handshake are derived from those
+        probes. A failing subsystem yields ``degraded``/``error`` honestly.
+
+        Allowed modes: offline · starting · online · degraded · error.
+        """
         require_user(request)
+        started = time.perf_counter()
+        errors = []
+
+        # ── filesystem capability: a real write → read → delete probe ─────────
+        fs_ok = False
+        probe_dir = Path(data_dir) if data_dir else Path(static_dir).parent
+        try:
+            probe_dir.mkdir(parents=True, exist_ok=True)
+            probe = probe_dir / f".local_agent_probe_{uuid.uuid4().hex}"
+            token = uuid.uuid4().hex
+            probe.write_text(token, encoding="utf-8")
+            fs_ok = probe.read_text(encoding="utf-8") == token
+            probe.unlink()
+        except Exception as exc:
+            errors.append(f"filesystem: {exc}")
+
+        # ── graph subsystem reachability (real call) ──────────────────────────
+        graph_reachable = None
+        if knowledge_graph is not None:
+            try:
+                knowledge_graph.stats()
+                graph_reachable = True
+            except Exception as exc:
+                graph_reachable = False
+                errors.append(f"graph: {exc}")
+
+        # ── watcher + connected sources (real) ────────────────────────────────
         watch = local_kg_watcher.status() if local_kg_watcher else {"available": False, "active": {}}
         sources = []
         try:
             if knowledge_graph is not None:
                 sources = (knowledge_graph.local_sources() or {}).get("sources", [])
-        except Exception:
-            sources = []
+        except Exception as exc:
+            errors.append(f"sources: {exc}")
         watched = len(watch.get("active", {}) or {})
+
+        # ── derive mode + handshake from the probes (no constants) ────────────
+        if not fs_ok:
+            mode = "error"
+        elif graph_reachable is False:
+            mode = "degraded"
+        else:
+            mode = "online"
+        handshake_ok = fs_ok and graph_reachable is not False
+        latency_ms = round((time.perf_counter() - started) * 1000, 2)
+
         return {
             "agent": {
                 "id": "lattice-local-runtime",
                 "name": "Lattice Local Agent",
                 "kind": "on-device-runtime",
-                "online": True,
+                "online": mode == "online",
                 "platform": platform.platform(),
                 "machine": platform.machine(),
                 "python": platform.python_version(),
             },
+            "online": mode == "online",
+            "mode": mode,
+            "version": _LATTICE_VERSION,
+            "pid": os.getpid(),
             "handshake": {
-                "ok": True,
+                "ok": handshake_ok,
                 "transport": "in-process",
-                "detail": "The local Lattice runtime serves this workspace on-device; no external agent is required.",
+                "latency_ms": latency_ms,
+                "detail": "Probed the in-process runtime (filesystem + graph); the local Lattice server is the on-device agent — no separate desktop process.",
             },
             "health": {
-                "status": "ok",
-                "filesystem_access": True,
+                "status": mode,
+                "filesystem_access": fs_ok,
+                "graph_reachable": graph_reachable,
                 "watcher_available": bool(watch.get("available")),
             },
+            "filesystem_access": fs_ok,
+            "watcher_available": bool(watch.get("available")),
+            "connected_folders": len(sources),
+            "watched_folders": watched,
             "folders": {"connected": len(sources), "watching": watched},
             "watch": watch,
             "sources": sources,
+            "last_seen": datetime.now().isoformat(timespec="seconds"),
+            "error": "; ".join(errors) if errors else None,
         }
 
     @router.post("/local/list")
@@ -157,6 +222,7 @@ def create_local_files_router(
             local_permission_response=permission_gateway.local_permission_response,
             require_local_approval=permission_gateway.require_local_approval,
             watcher=local_kg_watcher,
+            hooks=hooks,
         )
     )
 

package/latticeai/api/tools.py

@@ -15,6 +15,7 @@ from pydantic import BaseModel
 
 from latticeai.api.computer_use import create_computer_use_router
 from latticeai.api.local_files import create_local_files_router
+from latticeai.core.hooks import dispatch_tool
 from latticeai.api.mcp import create_mcp_router
 from latticeai.api.permissions import create_permissions_router
 from latticeai.services.upload_service import process_uploaded_document
@@ -220,23 +221,30 @@ def create_tools_router(
 
     # ── Direct Tool API ───────────────────────────────────────────────────────────
     
-    def _tool_response(fn, *args):
+    def _tool_response(fn, *args, **kwargs):
+        # Shared tool lifecycle (same path as the agent + workflow tool calls):
+        # pre_tool (may block) → execute → post_tool. Keyword args are forwarded
+        # to the tool and surfaced in the hook payload so read_file / edit_file /
+        # grep (which need kwargs) run through the SAME lifecycle as every other
+        # tool instead of bypassing it.
         tool_name = getattr(fn, "__name__", "tool")
-        # ── pre_tool hooks ── a blocking pre_tool hook (e.g. a permission gate)
-        # stops the tool call before it runs.
-        if HOOKS is not None:
-            pre = HOOKS.fire_hook("pre_tool", f"tool.{tool_name}", payload={"tool": tool_name, "argc": len(args)})
-            if pre.get("blocked"):
-                raise HTTPException(status_code=403, detail=pre.get("block_reason") or f"Tool '{tool_name}' blocked by a pre_tool hook.")
         try:
-            result = fn(*args)
+            result = dispatch_tool(HOOKS, tool_name, dict(kwargs), lambda: fn(*args, **kwargs), source="http")
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc))
         except ToolError as exc:
-            if HOOKS is not None:
-                HOOKS.fire_hook("post_tool", f"tool.{tool_name}", payload={"tool": tool_name, "status": "error", "detail": str(exc)})
             raise HTTPException(status_code=400, detail=str(exc))
-        if HOOKS is not None:
-            HOOKS.fire_hook("post_tool", f"tool.{tool_name}", payload={"tool": tool_name, "status": "ok"})
         return {"status": "ok", "workspace": str(AGENT_ROOT), "result": result}
+
+    def _dispatch(tool_name, args, fn):
+        # Lifecycle wrapper for callables that aren't a plain tools.* function
+        # (e.g. the server's clear_history). Same pre_tool/post_tool path.
+        try:
+            return dispatch_tool(HOOKS, tool_name, dict(args or {}), fn, source="http")
+        except PermissionError as exc:
+            raise HTTPException(status_code=403, detail=str(exc))
+        except ToolError as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
     
     
     @api_router.post("/tools/list_dir")
@@ -254,11 +262,7 @@ def create_tools_router(
     @api_router.post("/tools/read_file")
     async def tools_read_file(req: ToolReadFileRequest, request: Request):
         require_user(request)
-        try:
-            return {"status": "ok", "workspace": str(AGENT_ROOT),
-                    "result": read_file(req.path, offset=req.offset, limit=req.limit, line_numbers=req.line_numbers)}
-        except ToolError as exc:
-            raise HTTPException(status_code=400, detail=str(exc))
+        return _tool_response(read_file, req.path, offset=req.offset, limit=req.limit, line_numbers=req.line_numbers)
     
     
     @api_router.post("/tools/write_file")
@@ -270,11 +274,7 @@ def create_tools_router(
     @api_router.post("/tools/edit_file")
     async def tools_edit_file(req: ToolEditFileRequest, request: Request):
         require_user(request)
-        try:
-            return {"status": "ok", "workspace": str(AGENT_ROOT),
-                    "result": edit_file(req.path, req.old_string, req.new_string, replace_all=req.replace_all)}
-        except ToolError as exc:
-            raise HTTPException(status_code=400, detail=str(exc))
+        return _tool_response(edit_file, req.path, req.old_string, req.new_string, replace_all=req.replace_all)
     
     
     @api_router.post("/tools/search_files")
@@ -286,18 +286,15 @@ def create_tools_router(
     @api_router.post("/tools/grep")
     async def tools_grep(req: ToolGrepRequest, request: Request):
         require_user(request)
-        try:
-            return {"status": "ok", "workspace": str(AGENT_ROOT),
-                    "result": grep(
-                        req.pattern,
-                        path=req.path,
-                        glob=req.glob,
-                        max_results=req.max_results,
-                        case_insensitive=req.case_insensitive,
-                        context_lines=req.context_lines,
-                    )}
-        except ToolError as exc:
-            raise HTTPException(status_code=400, detail=str(exc))
+        return _tool_response(
+            grep,
+            req.pattern,
+            path=req.path,
+            glob=req.glob,
+            max_results=req.max_results,
+            case_insensitive=req.case_insensitive,
+            context_lines=req.context_lines,
+        )
     
     
     @api_router.post("/tools/todo_read")
@@ -315,7 +312,7 @@ def create_tools_router(
     @api_router.post("/tools/clear_history")
     async def tools_clear_history(req: ToolClearHistoryRequest, request: Request):
         current_user = require_user(request)
-        result = clear_history(req.keep_last)
+        result = _dispatch("clear_history", {"keep_last": req.keep_last}, lambda: clear_history(req.keep_last))
         append_audit_event(
             "history_delete",
             user_email=current_user,
@@ -458,12 +455,15 @@ def create_tools_router(
         require_graph=_require_graph,
         static_dir=STATIC_DIR,
         local_kg_watcher=LOCAL_KG_WATCHER,
+        hooks=HOOKS,
+        data_dir=DATA_DIR,
     ))
     api_router.include_router(create_computer_use_router(
         model_router=router,
         require_user=require_user,
         tool_response=_tool_response,
         save_to_history=save_to_history,
+        hooks=HOOKS,
     ))
 
     @api_router.post("/tools/knowledge_save")

package/latticeai/core/agent.py

@@ -28,6 +28,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Awaitable, Callable, Dict, FrozenSet, List, Optional
 
+from latticeai.core.hooks import dispatch_tool
 from tools import ToolError
 
 
@@ -122,6 +123,11 @@ class AgentDeps:
     memory_updater_prompt: str
     agent_root: Path
 
+    # ── lifecycle hooks port (optional) ──────────────────────────────
+    # When present, every tool execution fires the shared pre_tool/post_tool
+    # lifecycle, so the agent tool path no longer bypasses hooks.
+    hooks: Any = None
+
 
 class AgentRuntime:
     """Drives the agent state machine over injected :class:`AgentDeps`."""
@@ -289,13 +295,18 @@ class AgentRuntime:
 
             try:
                 d.check_role(name, current_user)
-                result = d.execute_tool(name, args)
+                # Shared tool lifecycle: pre_tool (may block) → execute → post_tool.
+                result = dispatch_tool(
+                    d.hooks, name, args,
+                    lambda: d.execute_tool(name, args),
+                    user_email=current_user, source="agent",
+                )
                 ctx.transcript.append({
                     "state": AgentState.EXECUTING.value, "action": name,
                     "thoughts": thoughts, "args": args,
                     "risk": risk, "governance": dict(policy), "result": result,
                 })
-            except (ToolError, KeyError, TypeError) as exc:
+            except (ToolError, KeyError, TypeError, PermissionError) as exc:
                 ctx.transcript.append({
                     "state": AgentState.EXECUTING.value, "action": name,
                     "thoughts": thoughts, "args": args,

package/latticeai/core/builtin_hooks.py

@@ -0,0 +1,106 @@
+"""Real runners for the built-in lifecycle hooks.
+
+Each built-in hook in :data:`latticeai.core.hooks.BUILTIN_HOOKS` is bound here to
+an actual callable so dispatch performs real platform work rather than a silent
+no-op. Kept out of ``server_app`` to keep the assembly file lean; ``server_app``
+calls :func:`register_builtin_hook_runners` once with the platform dependencies.
+
+A runner receives a :class:`~latticeai.core.hooks.HookContext` and returns a
+status dict (``{status, output, block?, detail?}``). It may mutate the context
+payload (e.g. redaction) or call ``context.block()`` to gate a ``pre_*`` action.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+_SECRET_KEY_HINTS = (
+    "token", "password", "passwd", "secret", "api_key", "apikey",
+    "authorization", "auth", "cookie", "session", "private_key",
+)
+
+
+def register_builtin_hook_runners(
+    registry: Any,
+    *,
+    append_audit_event: Callable[..., None],
+    get_tool_permission: Callable[..., dict],
+    classify_sensitive_message: Callable[..., dict],
+) -> None:
+    """Bind a real runner to every built-in hook on ``registry``."""
+
+    def redact_secrets(context):
+        """pre_run — strip secret-like keys from the agent context packet."""
+        payload = context.payload if isinstance(context.payload, dict) else {}
+        redacted = []
+        for key in list(payload.keys()):
+            if any(s in str(key).lower() for s in _SECRET_KEY_HINTS):
+                payload[key] = "***redacted***"
+                redacted.append(key)
+        return {"status": "ok", "output": f"redacted {len(redacted)} field(s)" if redacted else "no secrets present"}
+
+    def audit_agent_run(context):
+        """post_run — append the completed agent run to the workspace audit log."""
+        p = context.payload if isinstance(context.payload, dict) else {}
+        append_audit_event(
+            "hook_post_run", user_email=context.user_email,
+            run_id=p.get("run_id"), agent_id=p.get("agent_id"), status=p.get("status"),
+        )
+        return {"status": "ok", "output": f"audited run {p.get('run_id') or ''}".strip()}
+
+    def pipeline_index_status(context):
+        """post_index — record ingest/embed/graph-build pipeline state."""
+        p = context.payload if isinstance(context.payload, dict) else {}
+        return {"status": "ok", "output": f"pipeline {context.event}: indexed={p.get('indexed')}"}
+
+    def research_memory_snapshot(context):
+        """agent — record that a short-term memory snapshot was captured."""
+        p = context.payload if isinstance(context.payload, dict) else {}
+        n = p.get("context_items")
+        return {"status": "ok", "output": f"memory snapshot recorded ({n if n is not None else '0'} context items)"}
+
+    def tool_permission_gate(context):
+        """pre_tool — evaluate the real governance policy for the tool and record it.
+
+        Enforcement (admin-only gating, approval tokens) stays in the tool
+        dispatcher; this surfaces the policy into the run log and only blocks when
+        the governance policy itself marks the tool denied.
+        """
+        p = context.payload if isinstance(context.payload, dict) else {}
+        tool = p.get("tool") or ""
+        try:
+            perm = dict(get_tool_permission(tool))
+        except Exception as exc:  # pragma: no cover - defensive
+            return {"status": "ok", "output": f"policy unavailable for '{tool}': {exc}"}
+        if perm.get("policy") == "deny" or perm.get("risk") == "deny":
+            return {"status": "blocked", "block": True, "detail": f"governance policy denies '{tool}'"}
+        return {"status": "ok", "output": f"policy[{tool}]: risk={perm.get('risk')} approval={perm.get('requires_approval')}"}
+
+    def sensitive_data_guard(context):
+        """pre_tool — classify the outgoing tool payload for sensitive data."""
+        p = context.payload if isinstance(context.payload, dict) else {}
+        content = " ".join(str(v) for v in p.values() if isinstance(v, (str, int, float)))
+        try:
+            verdict = classify_sensitive_message(
+                {"role": "tool", "content": content, "user_email": context.user_email}, -1
+            )
+        except Exception as exc:  # pragma: no cover - defensive
+            return {"status": "ok", "output": f"classifier unavailable: {exc}"}
+        labels = verdict.get("labels") or []
+        return {"status": "ok", "output": f"sensitivity={verdict.get('sensitivity')} labels={','.join(labels) if labels else 'none'}"}
+
+    def workflow_replay_log(context):
+        """post_workflow — record the workflow run so it can be replayed."""
+        p = context.payload if isinstance(context.payload, dict) else {}
+        return {"status": "ok", "output": f"workflow {p.get('workflow_id') or '?'} -> {p.get('status') or 'recorded'} ({p.get('steps', '?')} steps)"}
+
+    registry.register_hook("builtin:redact-secrets", redact_secrets)
+    registry.register_hook("builtin:audit-agent-run", audit_agent_run)
+    registry.register_hook("builtin:pipeline-index-status", pipeline_index_status)
+    registry.register_hook("builtin:research-memory-snapshot", research_memory_snapshot)
+    registry.register_hook("builtin:tool-permission-gate", tool_permission_gate)
+    registry.register_hook("builtin:sensitive-data-guard", sensitive_data_guard)
+    registry.register_hook("builtin:workflow-replay-log", workflow_replay_log)
+
+
+__all__ = ["register_builtin_hook_runners"]