ltcai 8.1.0 → 8.3.0

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -0,0 +1,43 @@
+# Community And Plugins
+
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
+
+LatticeAI 8.3.0 defines the path from a strong local-first framework to a
+product ecosystem. The immediate goal is small and practical: make it clear how
+contributors can extend the Brain without weakening local-first trust,
+workspace scoping, or release quality.
+
+## Community Entry Points
+
+- Start with the product docs: `README.md`, `docs/WHY_LATTICE.md`, and
+  `docs/ONBOARDING.md`.
+- Use `docs/DEVELOPMENT.md` for local setup, validation, and release gates.
+- Use `docs/PLUGIN_SDK.md` for plugin manifests, compatibility, permissions,
+  lifecycle state, catalog endpoints, and install flows.
+- Use `plugins/hello-world/plugin.json` as the minimum working plugin shape.
+
+## Plugin Direction
+
+Plugins should add one bounded capability at a time:
+
+- new ingestion sources that still route through `IngestionPipeline`;
+- graph-aware tools that preserve workspace scoping;
+- workflow templates that declare permissions explicitly;
+- editor or automation helpers that keep secrets out of logs and audit payloads;
+- local-first integrations that require explicit opt-in before network access.
+
+## Guardrails
+
+- No plugin should bypass the ToolRegistry, permission model, or audit hooks.
+- No plugin should write graph data without provenance.
+- No plugin should assume a cloud model, remote registry, or network connection.
+- Compatibility requirements belong in `lattice_version`, and examples should
+  use current host-compatible values.
+
+## 8.3.0 Ecosystem Tasks
+
+- Keep the hello-world plugin valid and boring.
+- Expand examples only when they exercise real extension seams.
+- Add tests before treating a plugin API as stable.
+- Prefer documentation that helps a first contributor build one useful plugin
+  over broad ecosystem promises.

package/docs/DEVELOPMENT.md

@@ -1,8 +1,11 @@
 # Lattice AI Development
 
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
+
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release
-history stays in `docs/CHANGELOG.md` and `RELEASE.md`.
+history is intentionally limited to 7.0.0-8.3.0 in `docs/CHANGELOG.md` and
+`RELEASE.md`.
 
 ## Product Contract
 
@@ -77,9 +80,21 @@ Runtime assembly seams live under `latticeai.runtime`:
 - `config_runtime.py` derives app config values from `Config`;
 - `security_runtime.py` applies trusted proxy/security-derived settings;
 - `brain_runtime.py` constructs Brain Core and conversation primitives.
+- model/runtime, ToolRegistry/MCP, router, static asset, and lifespan seams
+  should continue moving out of monolithic app-factory helpers.
+
+Future extraction should continue with AgentRuntime, ToolRegistry, config,
+server decomposition, and Knowledge Graph stabilization in that order when
+architectural debt is present.
+
+## Runtime Hook Coverage
 
-Future extraction should continue with router assembly, model runtime assembly,
-platform/hooks assembly, static asset serving, and lifespan/startup/shutdown.
+Knowledge Graph ingestion paths must continue to pass through the shared
+pre-tool/post-tool lifecycle:
+
+- browser `read-url` ingestion dispatches `tool.kg_ingest.*` events;
+- browser `ingest-current-tab` ingestion dispatches the same lifecycle;
+- `IngestionPipeline` remains the common ingestion boundary behind those routes.
 
 ## Documentation Sync
 
@@ -96,3 +111,11 @@ For user-facing, API, runtime, release, or packaging changes, check:
 
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
+
+For 8.3.0 release work, exact artifacts are:
+
+- `dist/ltcai-8.3.0-py3-none-any.whl`
+- `dist/ltcai-8.3.0.tar.gz`
+- `ltcai-8.3.0.tgz`
+- `dist/ltcai-8.3.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_8.3.0_aarch64.dmg`

package/docs/LEGACY_COMPATIBILITY.md

@@ -1,10 +1,21 @@
 # Legacy Compatibility Map
 
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
+
 Lattice AI is moving toward a smaller, modular architecture centered on
 `lattice_brain`, `latticeai.services`, `latticeai.api`, and `latticeai.runtime`.
 Some root-level modules remain packaged for compatibility with older imports,
 CLI entrypoints, or extension workflows. Their presence does not define the
-current architecture.
+current 8.3.0 architecture.
+
+8.3.0 also tracks the inner compatibility layers that sit below the root
+modules. The managed inventory lives in `latticeai.core.legacy_compatibility`
+and groups shims by layer:
+
+- `root`: historical repo-root imports such as `knowledge_graph.py`.
+- `brain-flat`: pre-graph-package imports such as `lattice_brain.store`.
+- `deprecated-namespace`: older `latticeai.brain.*` package imports.
+- `service-alias`: service paths that now alias Brain runtime modules.
 
 ## Current Policy
 
@@ -15,6 +26,9 @@ current architecture.
 - Add deprecation notes before removal.
 - Avoid breaking package users during a minor release.
 - Do not silently remove rollback, backup, restore, or migration paths.
+- Track every remaining shim through `latticeai.core.legacy_compatibility` so
+  release readiness can report owner, replacement, reason, removal phase, and
+  missing files.
 
 ## Root Module Map
 
@@ -33,6 +47,14 @@ current architecture.
 | `setup_wizard.py` | setup and model recommendation services | Compatibility for first-run recommendation calls |
 | `server.py` | lazy proxy to `latticeai.server_app` / `latticeai.app_factory` | Preserves historical `server.app` imports without import-time construction |
 
+## Inner Shim Layers
+
+| Legacy layer | Example module | Current home / direction | Why it remains |
+| --- | --- | --- | --- |
+| `brain-flat` | `lattice_brain.store`, `lattice_brain.ingest`, `lattice_brain.retrieval` | `lattice_brain.graph.*` | Preserves imports from before graph modules were split into a package |
+| `deprecated-namespace` | `latticeai.brain.store`, `latticeai.brain.ingest` | `lattice_brain.graph.*` | Preserves the old application-package Brain namespace |
+| `service-alias` | `latticeai.services.agent_runtime` | `lattice_brain.runtime.agent_runtime` | Preserves service-layer imports while runtime ownership sits in Brain Core |
+
 ## Packaging Notes
 
 `pyproject.toml` and `package.json` still include several root modules because

package/docs/ONBOARDING.md

@@ -0,0 +1,38 @@
+# Lattice AI Onboarding
+
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
+
+The first-run goal is a five-minute path from "I opened the app" to "my Brain
+has a source, a question, and proof." This page is the product contract behind
+that flow; the UI should make these steps obvious without asking a new user to
+read the docs first.
+
+## Five-Minute Flow
+
+1. Wake the Brain and confirm the local owner profile.
+2. Let Lattice inspect local model/runtime readiness.
+3. Pick the recommended Brain voice or skip model loading.
+4. Add one source: upload a file, connect a folder, save a note, or capture a
+   browser/source event.
+5. Ask one grounded question and inspect the answer proof.
+6. Open the Knowledge Graph only when the user wants source-level evidence.
+7. Back up the Brain once useful memory exists.
+
+## Product Promises
+
+- The user starts in the Brain, not in an admin dashboard.
+- Empty states suggest one concrete next action without claiming proof that does
+  not exist yet.
+- Upload, note, browser, and message ingestion all converge through the unified
+  ingestion pipeline when it is available.
+- Workspace-scoped content must not leak or overwrite another workspace's graph
+  metadata.
+- Advanced runtime, workflow, plugin, and admin surfaces are available, but they
+  do not block the first conversation.
+
+## Release Gate
+
+8.3.0 treats onboarding as a release gate, not marketing copy. The current
+machine-checkable product readiness report requires this five-minute contract,
+the Brain Home surface, setup helpers, graph ingestion tests, and exact release
+artifact documentation before the release can be called complete.

package/docs/TRUST_MODEL.md

@@ -1,7 +1,9 @@
 # Lattice AI Trust Model
 
-Lattice AI's trust model is local-first, opt-in for external communication, and
-honest when something is unavailable.
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
+
+Lattice AI is local-first, explicit about external communication, and honest
+when a capability is unavailable.
 
 ## Local By Default
 
@@ -9,58 +11,56 @@ By default, Lattice AI binds the API to `127.0.0.1`, stores Brain data under the
 local data directory, and does not send prompts, documents, graph content, or
 archives to Lattice-owned servers.
 
-Local data includes:
+Local data can include:
 
-- local profile and sessions;
-- conversations and memory records;
-- Knowledge Graph nodes, edges, provenance, and search indexes;
-- uploaded document blobs;
+- profile and session metadata;
+- conversations, memories, decisions, and workflow history;
+- Knowledge Graph nodes, edges, provenance, and indexes;
+- uploaded document blobs and extracted text;
 - audit and admin operation logs;
 - backups and encrypted `.latticebrain` archives.
 
 ## Explicit External Paths
 
-Some features can contact third parties, but they require explicit user/admin
-action or configuration:
+External communication requires configuration plus a user/admin action:
 
-- model downloads from model registries;
-- cloud model API calls after keys are configured and a cloud model is chosen;
+- cloud model calls after keys are configured and a cloud model is selected;
+- model downloads from registries after install consent;
 - Telegram bridge after the integration is enabled;
-- Brain Network peer actions after pairing/initiating network flows;
+- Brain Network peer actions after pairing;
 - Docker/Postgres setup after opt-in scale configuration;
-- update checks only when update checking is enabled;
-- remote marketplace/registry refreshes only through explicit user actions.
+- update checks only when enabled;
+- marketplace or remote registry refreshes only when invoked.
 
 Token presence alone must not start external communication.
 
 ## Consent And Honesty Gates
 
-Lattice AI should fail closed or report unavailable state for:
+Lattice AI should fail closed or show an unavailable state for:
 
 - no model loaded;
-- local model not installed;
-- installed model not loaded;
+- local model not installed or not loaded;
 - missing cloud key;
 - deterministic/model-free preview;
 - dry-run versus real execution;
 - no graph/context evidence available;
 - unavailable external integration;
 - wrong archive passphrase;
-- archive path traversal or tampering.
+- archive tampering, unsupported archive versions, or path traversal.
 
-## Admin Boundary
+## Product Boundary
 
-The normal user product is Brain Chat, memory, topics, relationships, graph
-exploration, model state, and Brain ownership. Admin Console is for users,
+Normal Brain use is conversation, memory, topics, relationships, model state,
+source capture, and Knowledge Graph exploration. Admin Console is for users,
 roles, audit logs, security events, retention, and operations. Admin visibility
 does not mean secrets should appear in clear text.
 
-## Known Limitations
+## Known Limits
 
-- Local files are only as protected as the user's machine, account, backups, and
-  disk encryption.
-- Cloud model prompts follow the selected provider's policy.
+- Local files are only as protected as the user's machine, OS account, backups,
+  and disk encryption.
+- Cloud model prompts follow the selected provider's policy once the user
+  explicitly chooses that provider.
 - A local admin can inspect local files and process memory outside Lattice AI.
 - Marketplace and model registries are third-party services when explicitly
   contacted.
-

package/docs/WHY_LATTICE.md

@@ -1,51 +1,55 @@
 # Why Lattice AI Exists
 
-**Lattice AI is a local-first Digital Brain that keeps your knowledge durable across any AI model.**
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
+
+**Lattice AI is a local-first Digital Brain that keeps your knowledge durable
+across any AI model.**
 
 **모델은 바꿔도, 내 지식은 남는 로컬 AI 브레인.**
 
-AI models change quickly. A model you use today may be replaced next month, and
-the conversation history, project context, decisions, and sources you built
-around it can become scattered across tools. Lattice AI exists so the durable
-asset is not the model. The durable asset is your Brain.
+AI models change quickly. A model you use today may be replaced tomorrow, and a
+cloud chat history can become scattered across tools. Lattice AI exists so the
+durable asset is not the model. The durable asset is your Brain.
 
 ## The Problem
 
-Most AI products begin with a model and treat your context as temporary prompt
-material. That works for short questions, but it fails for long-running work:
+Most AI products start with a model and treat your context as temporary prompt
+material. That breaks down for real work:
 
 - project decisions disappear into old chats;
-- documents and notes are disconnected from conversations;
+- documents and notes stay disconnected from conversations;
 - switching models often means losing useful context;
-- graph or database tools expose implementation details before user value;
-- cloud-only products make it hard to inspect, back up, or move your knowledge.
+- graph tools expose implementation detail before user value;
+- cloud-only products make your knowledge hard to inspect, back up, or move.
 
 ## The Lattice Answer
 
-Lattice AI is a local-first private AI memory layer. It keeps conversations,
-documents, decisions, relationships, and project history in a Brain that belongs
-to the user. Models can be local, cloud, current, or future. The Brain remains.
+Lattice AI keeps conversations, documents, memories, decisions, relationships,
+and source provenance in a private local Brain. Models can be local, cloud,
+current, or future. The Brain remains.
+
+The graph matters, but it is not the product identity. The product identity is a
+local-first Digital Brain: a place where the user can talk, add sources, watch
+memory grow, and inspect the Knowledge Graph when they need proof.
 
-The graph is real, but it is not the product identity. Product category is
-local-first Digital Brain; core capability is a private AI memory layer; UX
-metaphor is the Living Brain. Users start with Brain
-Chat, memory, topics, relationships, ownership, backup, and graph exploration.
-Advanced admin logs, roles, hooks, workflows, Telegram, Brain Network, Docker,
-Postgres, and plugin details stay outside the normal user flow.
+In 8.3.0 the first screen is intentionally not a dashboard. The living Brain,
+conversation composer, evidence-backed Brain Brief, and five-minute onboarding
+path appear together so the user immediately knows what matters, what to add,
+and why the answer is grounded in local memory.
 
 ## Practical Reasons To Use It
 
-- Ask what the team decided last week and see the source.
-- Drop in documents and build a searchable personal memory.
-- Prepare for a meeting from past notes, project decisions, and files.
-- Preserve context when moving from one model to another.
-- Export or back up the Brain as an encrypted `.latticebrain` archive.
+- Ask what the team decided and see the source.
+- Add documents and build a searchable private memory.
+- Prepare from old notes, project decisions, and files.
+- Preserve context when moving between models.
+- Export or restore the Brain as an encrypted `.latticebrain` archive.
 - Use Korean or English without changing the underlying Brain.
 - Avoid fake answers when no model or evidence is available.
 
 ## What Lattice AI Is Not
 
-- Not a hosted SaaS by default.
+- Not hosted SaaS by default.
 - Not just a model launcher.
 - Not just a graph viewer.
 - Not a generic dashboard.

package/docs/kg-schema.md

@@ -1,4 +1,6 @@
-# Knowledge Graph — v2 스키마
+# Knowledge Graph Schema
+
+Current release: **8.3.0 - Orchestrated Brain Readiness**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `kg_schema.py`
@@ -80,15 +82,15 @@ Edge {
 
 **엔드포인트 룰은 권고 사항이다 (스키마 문서 기준).** 코드에는 엔드포인트 페어
 검증기가 존재하지 않는다 — `validate_endpoints` 는 구현된 적이 없으며, 쓰기
-경로는 타입 페어를 거부하지 않는다. v4 의 쓰기 정규화는 *타입 어휘* 를
+경로는 타입 페어를 거부하지 않는다. 현재 쓰기 정규화는 *타입 어휘* 를
 강제한다: `_upsert_edge` 가 모든 엣지 타입을 canonical `EdgeType` 값으로
 정규화하므로 자유 문자열 타입은 더 이상 생성되지 않는다.
 
 ---
 
-## v3.6.0 — Knowledge Graph First 엔티티/관계
+## Current Knowledge Graph First 엔티티/관계
 
-v3.6.0 은 "모든 데이터 소스가 Knowledge Graph 로 수렴한다"는 원칙을 1급 스키마로
+8.3.0 은 "모든 데이터 소스가 Knowledge Graph 로 수렴한다"는 원칙을 1급 스키마로
 승격한다. 아래 타입은 **추가형(additive)**이다 — 기존 enum/legacy 매핑을 깨지 않고
 `from_legacy` 가 무손실로 정규화하며, 알 수 없는 타입은 여전히 `CONCEPT`/`MENTIONS` 로
 폴백한다. 스키마는 **확장 가능**하게 유지한다: 새 도메인 엔티티는 enum 멤버 1개 +
@@ -136,7 +138,7 @@ provenance(source_type, source_uri, content_hash, captured_at, modified_at,
 - provenance 는 노드 `metadata.provenance` 에 임베드되며, 동시에 감사 가능한
   `ingestion_provenance` 테이블에 기록된다 (`KnowledgeGraphStore.get_provenance(node_id)`).
 
-구현: `latticeai/services/ingestion.py` (`IngestionPipeline`) 가 단일 진입점이며,
+구현: `lattice_brain/ingestion.py` (`IngestionPipeline`) 가 단일 진입점이며,
 파일/로컬폴더/URL/브라우저 탭/텍스트를 모두 이 형태로 정규화한다.
 
 ---

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "8.1.0"
+__version__ = "8.3.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/graph/ingest.py

@@ -490,8 +490,6 @@ class KnowledgeGraphIngestMixin:
         is derived from (source_type, source_uri | content_hash) so re-ingesting
         the same origin reuses the same SOURCE node (idempotent).
         """
-        key = source_uri or content_hash or content_node_id
-        source_id = f"source:{_sha256_text(f'{source_type}|{key}')[:24]}"
         meta = {
             "source_type": source_type,
             "source_uri": source_uri,
@@ -499,6 +497,9 @@ class KnowledgeGraphIngestMixin:
             "captured_at": captured_at or _now(),
             **(extra or {}),
         }
+        key = source_uri or content_hash or content_node_id
+        source_scope = meta.get("workspace_id") or "legacy-global"
+        source_id = f"source:{_sha256_text(f'{source_scope}|{source_type}|{key}')[:24]}"
         label = title or source_uri or source_type
         self._upsert_node(
             conn,
@@ -551,7 +552,8 @@ class KnowledgeGraphIngestMixin:
         )
         captured_at = captured_at or _now()
         content_hash = _sha256_text(f"{source_type}|{source_uri or ''}|{text}")
-        content_id = f"webdoc:{content_hash[:24]}"
+        identity_hash = _sha256_text(f"{workspace_id or 'legacy-global'}|{content_hash}")
+        content_id = f"webdoc:{identity_hash[:24]}"
         full_text = f"{title}\n{text}"
         node_meta = {
             "source_type": source_type,
@@ -581,6 +583,8 @@ class KnowledgeGraphIngestMixin:
                 summary=(text or title)[:500],
                 metadata=node_meta,
                 raw=node_meta,
+                owner=owner,
+                workspace_id=workspace_id,
             )
             # ── SOURCE 노드 + indexed_from 엣지 (출처 추적) ──────────────────
             source_node_id = self._attach_source_node(
@@ -597,13 +601,27 @@ class KnowledgeGraphIngestMixin:
             if owner:
                 person_id = f"person:{_slug(owner)}"
                 self._upsert_node(
-                    conn, person_id, "Person", owner, metadata={"email": owner}
+                    conn,
+                    person_id,
+                    "Person",
+                    owner,
+                    metadata={"email": owner, "workspace_id": workspace_id},
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_edge(conn, person_id, content_id, "업로드함", weight=1.0)
             # ── 대화 연결 ───────────────────────────────────────────────────
             if conversation_id:
                 conv_id = f"conversation:{_slug(conversation_id)}"
-                self._upsert_node(conn, conv_id, "Chat", conversation_id)
+                self._upsert_node(
+                    conn,
+                    conv_id,
+                    "Chat",
+                    conversation_id,
+                    metadata={"conversation_id": conversation_id, "workspace_id": workspace_id},
+                    owner=owner,
+                    workspace_id=workspace_id,
+                )
                 self._upsert_edge(conn, conv_id, content_id, "언급함", weight=0.8)
             # ── RAG 청크 ────────────────────────────────────────────────────
             for index, chunk in enumerate(_chunks(text)):
@@ -615,7 +633,9 @@ class KnowledgeGraphIngestMixin:
                     "Chunk",
                     f"{title} chunk {index + 1}",
                     summary=chunk[:500],
-                    metadata={"index": index, "source_node": content_id},
+                    metadata={"index": index, "source_node": content_id, "workspace_id": workspace_id},
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_chunk(
                     conn,
@@ -636,7 +656,13 @@ class KnowledgeGraphIngestMixin:
                     cid,
                     node_t,
                     concept,
-                    metadata={"auto_extracted": True, "source_type": source_type},
+                    metadata={
+                        "auto_extracted": True,
+                        "source_type": source_type,
+                        "workspace_id": workspace_id,
+                    },
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_edge(conn, content_id, cid, "포함함", weight=0.8)
             for triple in triples:
@@ -662,8 +688,14 @@ class KnowledgeGraphIngestMixin:
                     sem_type,
                     sem_title,
                     summary=item["summary"],
-                    metadata={"auto_extracted": True, "source_node": content_id},
+                    metadata={
+                        "auto_extracted": True,
+                        "source_node": content_id,
+                        "workspace_id": workspace_id,
+                    },
                     raw=item,
+                    owner=owner,
+                    workspace_id=workspace_id,
                 )
                 self._upsert_edge(conn, content_id, sem_id, "포함함", weight=0.9)
 

package/lattice_brain/graph/schema.py

@@ -56,6 +56,12 @@ KG_SCHEMA_V2_VERSION = 2
 EMBED_DIM = int(os.getenv("LATTICEAI_EMBED_DIM", "1024"))
 
 
+def set_embed_dim(dim: int) -> None:
+    """Optional way for upper layers to override without direct module import at top level in lattice_brain."""
+    global EMBED_DIM
+    EMBED_DIM = int(dim)  # lattice_brain isolation: no direct latticeai import; callers can pre-set env if using central Config
+
+
 # ── Node / Edge taxonomy (PPT 슬라이드 20·21) ──────────────────────────────
 class NodeType(str, Enum):
     """워크스페이스의 모든 ‘명사’.

package/lattice_brain/runtime/agent_runtime.py

@@ -266,7 +266,7 @@ class AgentRuntime:
         unknown_roles = [role for role in requested_roles if role not in AGENT_ROLES]
         health = self.health()
         goal_ready = bool(str(goal or "").strip())
-        retry_budget = max(0, min(int(max_retries or 0), self._max_retries_cap))
+        retry_budget = self._clamp_retries(max_retries)
         blocking_reasons: List[str] = []
         if not goal_ready:
             blocking_reasons.append("goal is required")
@@ -324,6 +324,7 @@ class AgentRuntime:
     def events(self, run_id: str, *, scope: Optional[str] = None) -> Dict[str, Any]:
         run = self._store.get_agent_run(run_id, workspace_id=scope)
         status = str(run.get("status") or "")
+        contract = extract_contract(run)
         return {
             "run_id": run_id,
             "status": status,
@@ -331,7 +332,7 @@ class AgentRuntime:
             "current_role": run.get("current_role"),
             "timeline": run.get("timeline") or [],
             "handoffs": run.get("handoffs") or [],
-            "contract": contract_view(run),
+            "contract": contract_view(contract) if contract is not None else None,
         }
 
     # ── execution ─────────────────────────────────────────────────────────
@@ -360,6 +361,9 @@ class AgentRuntime:
                 raise PermissionError(pre_dispatch.get("block_reason") or "Agent run blocked by a pre_run hook.")
         return pre_dispatch
 
+    def _clamp_retries(self, max_retries: int) -> int:
+        return max(0, min(int(max_retries or 0), self._max_retries_cap))
+
     @staticmethod
     def _result_patch(result: Any, goal: str) -> Dict[str, Any]:
         return {
@@ -488,7 +492,7 @@ class AgentRuntime:
                 workspace_id=scope,
                 inputs=inputs or {},
                 roles=roles or None,
-                max_retries=max(0, min(int(max_retries or 0), self._max_retries_cap)),
+                max_retries=self._clamp_retries(max_retries),
             )
         except Exception as exc:
             failed = self._store.update_agent_run(
@@ -571,25 +575,13 @@ class AgentRuntime:
         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.")
-
+        pre_dispatch = self._fire_pre_run(
+            goal=goal,
+            roles=roles,
+            max_retries=max_retries,
+            user_email=user_email,
+            scope=scope,
+        )
         orchestrator = self._live_orchestrator(user_email, scope)
         result = orchestrator.run(
             goal,
@@ -597,7 +589,7 @@ class AgentRuntime:
             workspace_id=scope,
             inputs=inputs or {},
             roles=roles or None,
-            max_retries=max(0, min(int(max_retries or 0), self._max_retries_cap)),
+            max_retries=self._clamp_retries(max_retries),
         )
         run = self._store.record_agent_run(
             agent_id=result.agent_id,
@@ -626,20 +618,13 @@ class AgentRuntime:
             retries=result.retries,
         )
 
-        # ── 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,
-            )
+        run_id = run.get("id") or run.get("run_id") if isinstance(run, dict) else None
+        post_dispatch = self._post_run_hooks(
+            run_id=run_id,
+            result=result,
+            user_email=user_email,
+            scope=scope,
+        )
 
         result_payload = result.as_dict()
         result_payload["contract"] = multi_agent_contract(result=result, goal=goal, run_id=run.get("id") if isinstance(run, dict) else None)

package/lattice_brain/runtime/multi_agent.py

@@ -21,7 +21,7 @@ from typing import Any, Callable, Dict, List, Optional
 from .contracts import multi_agent_contract
 
 
-MULTI_AGENT_VERSION = "8.1.0"
+MULTI_AGENT_VERSION = "8.3.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")