ltcai 3.2.0 → 3.4.0

package/latticeai/core/hooks.py

@@ -20,10 +20,15 @@ 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, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 
 HOOK_KINDS = (
@@ -36,11 +41,137 @@ HOOK_KINDS = (
     "workflow",
 )
 
+# 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)
+
+
 # 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
@@ -116,9 +247,17 @@ BUILTIN_HOOKS: List[Dict[str, Any]] = [
 class HooksRegistry:
     """Persisted registry of lifecycle hooks (built-in + user-registered)."""
 
-    def __init__(self, path: Path):
+    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]:
@@ -282,3 +421,260 @@ class HooksRegistry:
             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).
+        """
+        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
+
+    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()
+
+    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(),
+        }

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "3.2.0"
+MARKETPLACE_VERSION = "3.4.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/multi_agent.py

@@ -14,7 +14,7 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 
-MULTI_AGENT_VERSION = "3.2.0"
+MULTI_AGENT_VERSION = "3.4.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/core/workflow_engine.py

@@ -214,17 +214,31 @@ class WorkflowEngine:
     gracefully (and the gap is visible in the timeline).
     """
 
-    def __init__(self, runners: Optional[Dict[str, Callable[..., Any]]] = None):
+    def __init__(self, runners: Optional[Dict[str, Callable[..., Any]]] = None, *, hooks: Any = None):
         self.runners = runners or {}
+        # Optional lifecycle hooks registry. When present, ``run`` fires the
+        # ``workflow`` hooks at workflow start and end so automation registered
+        # against the workflow lifecycle actually executes.
+        self.hooks = hooks
 
     def run(self, workflow: Dict[str, Any], *, inputs: Optional[Dict[str, Any]] = None) -> WorkflowRun:
         definition = normalize_definition(workflow)
         errors = validate_definition(definition)
         run = WorkflowRun(workflow_id=definition.get("id"), name=definition.get("name") or "workflow")
+        if self.hooks is not None:
+            self.hooks.fire_hook(
+                "workflow", "workflow.start",
+                payload={"workflow_id": definition.get("id"), "name": definition.get("name"), "valid": not errors},
+            )
         if errors:
             run.status = "failed"
             run.timeline.append({"node": None, "type": "validation", "status": "failed", "errors": errors, "timestamp": _now()})
             run.finished_at = _now()
+            if self.hooks is not None:
+                self.hooks.fire_hook(
+                    "workflow", "workflow.end",
+                    payload={"workflow_id": definition.get("id"), "status": run.status},
+                )
             return run
 
         nodes = {node["id"]: node for node in definition["nodes"]}
@@ -300,6 +314,12 @@ class WorkflowEngine:
 
         run.status = "failed" if had_error else ("partial" if had_skip else "ok")
         run.finished_at = _now()
+        if self.hooks is not None:
+            self.hooks.fire_hook(
+                "workflow", "workflow.end",
+                payload={"workflow_id": definition.get("id"), "name": definition.get("name"),
+                         "status": run.status, "steps": steps},
+            )
         return run
 
 

package/latticeai/core/workspace_os.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "3.2.0"
+WORKSPACE_OS_VERSION = "3.4.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/server_app.py

@@ -1283,8 +1283,46 @@ AGENT_RUNTIME = AgentRuntime(
     orchestrator_factory=PLATFORM.build_orchestrator,
     workspace_graph=_workspace_graph,
     append_audit_event=append_audit_event,
+    hooks=HOOKS_REGISTRY,
 )
 
+# ── Hooks dispatch: bind real built-in runners ───────────────────────────────
+# The registry lists built-in hooks; binding a runner here makes them *execute*
+# real platform behaviour when fired (not a placeholder). Runners take a
+# HookContext and may mutate its payload, return a status dict, or block.
+def _hook_redact_secrets(context):
+    """pre_run — strip secret-like keys from the agent context packet."""
+    secret_re = ("token", "password", "passwd", "secret", "api_key", "apikey",
+                 "authorization", "auth", "cookie", "session", "private_key")
+    redacted = []
+    payload = context.payload if isinstance(context.payload, dict) else {}
+    for key in list(payload.keys()):
+        if any(s in str(key).lower() for s in secret_re):
+            payload[key] = "***redacted***"
+            redacted.append(key)
+    return {"status": "ok", "output": f"redacted {len(redacted)} field(s)" if redacted else "no secrets present"}
+
+def _hook_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 _hook_pipeline_index_status(context):
+    """pipeline — record ingest/embed/graph-build pipeline state for the index."""
+    p = context.payload if isinstance(context.payload, dict) else {}
+    return {"status": "ok", "output": f"pipeline {context.event}: indexed={p.get('indexed')}"}
+
+HOOKS_REGISTRY.register_hook("builtin:redact-secrets", _hook_redact_secrets)
+HOOKS_REGISTRY.register_hook("builtin:audit-agent-run", _hook_audit_agent_run)
+HOOKS_REGISTRY.register_hook("builtin:pipeline-index-status", _hook_pipeline_index_status)
+
 app.include_router(create_plugins_router(
     registry=PLUGIN_REGISTRY,
     require_user=require_user,
@@ -1307,6 +1345,7 @@ app.include_router(create_workflow_designer_router(
     append_audit_event=append_audit_event,
     ui_file_response=ui_file_response,
     static_dir=STATIC_DIR,
+    hooks=HOOKS_REGISTRY,
 ))
 
 app.include_router(create_agents_router(
@@ -1457,6 +1496,7 @@ app.include_router(create_tools_router(
     recommend_mcps=recommend_mcps,
     install_mcp=install_mcp,
     mcp_public_item=mcp_public_item,
+    hooks=HOOKS_REGISTRY,
 ))
 
 app.include_router(create_hooks_router(

package/latticeai/services/agent_runtime.py

@@ -54,12 +54,16 @@ class AgentRuntime:
         workspace_graph: Callable[[], Any],
         append_audit_event: Callable[..., None],
         max_retries_cap: int = 5,
+        hooks: Any = None,
     ):
         self._store = store
         self._orchestrator_factory = orchestrator_factory
         self._workspace_graph = workspace_graph
         self._append_audit_event = append_audit_event
         self._max_retries_cap = int(max_retries_cap)
+        # Lifecycle hooks registry (optional). When present, ``start`` fires the
+        # ``pre_run`` / ``post_run`` hooks; a blocking ``pre_run`` aborts the run.
+        self._hooks = hooks
 
     # ── configuration ─────────────────────────────────────────────────────
     def config(self) -> Dict[str, Any]:
@@ -192,6 +196,26 @@ class AgentRuntime:
     ) -> Dict[str, Any]:
         if not str(goal or "").strip():
             raise ValueError("goal is required")
+
+        # ── pre_run hooks ─────────────────────────────────────────────────
+        # A blocking pre_run hook (e.g. a policy gate) aborts the run before any
+        # orchestration happens. Hook failures never crash the run (fire_hook
+        # swallows them); only an explicit block stops it.
+        pre_dispatch: Optional[Dict[str, Any]] = None
+        if self._hooks is not None:
+            pre_dispatch = self._hooks.fire_hook(
+                "pre_run", "agent.run",
+                payload={"goal": goal, "roles": roles or None, "max_retries": max_retries},
+                user_email=user_email, workspace_id=scope,
+            )
+            if pre_dispatch.get("blocked"):
+                self._append_audit_event(
+                    "multi_agent_run_blocked",
+                    user_email=user_email,
+                    reason=pre_dispatch.get("block_reason"),
+                )
+                raise PermissionError(pre_dispatch.get("block_reason") or "Agent run blocked by a pre_run hook.")
+
         orchestrator = self._orchestrator_factory(user_email or None, scope)
         result = orchestrator.run(
             goal,
@@ -226,7 +250,28 @@ class AgentRuntime:
             status=result.status,
             retries=result.retries,
         )
-        return {"run": run, "result": result.as_dict()}
+
+        # ── post_run hooks ────────────────────────────────────────────────
+        post_dispatch: Optional[Dict[str, Any]] = None
+        if self._hooks is not None:
+            run_id = run.get("id") or run.get("run_id") if isinstance(run, dict) else None
+            post_dispatch = self._hooks.fire_hook(
+                "post_run", "agent.run",
+                payload={
+                    "run_id": run_id,
+                    "agent_id": result.agent_id,
+                    "status": result.status,
+                    "retries": result.retries,
+                },
+                user_email=user_email, workspace_id=scope,
+            )
+
+        payload = {"run": run, "result": result.as_dict()}
+        if pre_dispatch is not None:
+            payload["pre_run_hooks"] = pre_dispatch
+        if post_dispatch is not None:
+            payload["post_run_hooks"] = post_dispatch
+        return payload
 
     def stop(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
         """Best-effort stop.

package/latticeai/services/upload_service.py

@@ -23,6 +23,7 @@ async def process_uploaded_document(
     classify_sensitive_message,
     append_audit_event,
     enforce_rate_limit,
+    hooks=None,
 ) -> dict:
     enforce_rate_limit(current_user, "upload")
     suffix = Path(file.filename or "upload").suffix.lower()
@@ -92,6 +93,22 @@ async def process_uploaded_document(
         except OSError:
             pass
 
+    # ── pipeline hooks ── the ingest → embed → graph-build pipeline just ran for
+    # this document; fire the pipeline lifecycle hooks so downstream automation
+    # (index-status publishing, custom reindex triggers) executes.
+    if hooks is not None:
+        kg = result.get("knowledge_graph") or {}
+        hooks.fire_hook(
+            "pipeline", "document.ingested",
+            payload={
+                "filename": file.filename,
+                "chars": result.get("chars"),
+                "graph_node": kg.get("node_id"),
+                "indexed": bool(kg.get("node_id")),
+            },
+            user_email=current_user,
+        )
+
     result["original_filename"] = file.filename
     return result