refactor: establish tool and event ABI contracts

docs/plans/core-decomposition-completed.md

@@ -18,9 +18,9 @@
 - `services-core` 已承接 session layout、metadata store CRUD / index rebuild、metadata pagination、metadata construction / mutation、lineage / branch shaping、JSON file store、filesystem primitives、managed runtime command resolution / PATH merge、LSP plugin registry / extension matching / command-target mapping、diagnostic redaction、session usage/token usage 基础服务。
 - `services-core` 已承接 workspace-runtime legacy session-store merge、metadata 冲突选择、index rebuild 和 legacy path copy/move fallback；core workspace-runtime 只保留路径计算、runtime layout ensure 和错误兼容映射。
 - `runtime-services` 已承接 typed runtime service assembly、capability availability、provider registry、capability validation、无副作用 capability marker ports 和 backend event delivery；core backend event system 只保留兼容 re-export。
-- `bitfun-events` 已承接 backend event DTO、agentic event DTO、framework-neutral Agentic frontend event projection 和 platform-neutral `EventEmitter` trait；Tauri/WebSocket transport 只负责 delivery。
+- `bitfun-events` 已承接 backend event DTO、agentic event DTO、framework-neutral Agentic frontend event projection、AgenticEvent projection manifest、event version / aggregate / replay / retention facts、legacy WebSocket event allowlist 和 platform-neutral `EventEmitter` trait；Tauri/WebSocket transport 只负责 delivery。
 - `services-integrations` 已承接 remote-connect primitives、wire command routing / response assembly、LAN IP/URL 探测、ngrok 进程/tunnel lifecycle、mobile-web relay upload manifest / incremental upload / fallback upload、IM bot provider-neutral config / persistence / file auto-push / locale / menu / state / command parsing、Weixin provider client、workspace search concrete owner、remote SSH/SFTP/PTY owner、Remote SSH disabled runtime surface、Remote SSH workspace/session identity helper、remote workspace-search disabled surface、DeepResearch report IO / display-map sidecar、MiniApp host dispatch / storage / worker / import IO、announcement remote fetch/cache、browser CDP endpoint HTTP probing / page creation、WebFetch / WebSearch concrete HTTP provider、debug-log HTTP ingest posting、review-platform HTTP transport，以及 MCP server registry、connection pool、catalog cache、reconnect retry state、runtime-only config overlay、local command resolution helper 和 lifecycle status policy。
-- `tool-contracts` 已承接 provider-neutral tool DTO、manifest/catalog/admission/result presentation、Computer Use DTO/input parser/screenshot payload、confirmation facts、truncation recovery presentation、runtime restriction policy 和 provider-entry materialization；core 只保留 Computer Use 旧 public path re-export / compatibility shim 与产品执行入口。
+- `tool-contracts` 已承接 provider-neutral tool DTO、manifest/catalog/admission/result presentation、Computer Use DTO/input parser/screenshot payload、confirmation facts、truncation recovery presentation、runtime restriction policy、provider-entry materialization、materialized tool snapshot、provider identity、permission/effect filter、cancellation contract 和 stale-call guard；core 只保留 Computer Use 旧 public path re-export / compatibility shim、产品 Tool trait 适配与产品执行入口。
 - `tool-execution` 已承接 local / remote IO helper、Bash shell helper、batching plan、retry policy、state counting、tool state event payload shaping / result redaction、cancellation-state/token-store policy、background exec output capture、ExecCommand provider-neutral 呈现 / 输入默认值 / 结果 shape / shell metadata / shell argv / remote shell probe / remote env snapshot 解析、cache 与 capture policy / lifecycle facts / control facts / completion shape、prompt-safe tool context facts / custom-data materialization、Computer Use loop detection / screenshot hash / verification / retry policy，以及 File tool 的 provider-neutral 结果展示、写入 mode/status/line-count 规则、Edit guardrail 分类和 Delete success 文本；core 只保留 ToolResult 包装、权限、checkpoint、runtime handles、host adapter 调用、read-state adapter、remote FS 调用和旧工具入口。
 - `runtime-ports` / `terminal-core` / `services-integrations` 已承接 ExecCommand 会话执行端口和 concrete provider：`TerminalPort` 暴露本地命令执行、stdin 写入、会话控制和生命周期事件边界，`RemoteExecPort` 暴露远端 SSH 命令执行、bounded one-shot command、stdin、会话控制和生命周期事件边界；`TerminalRuntimePort` 复用原本地 `ExecProcessManager` 行为，`RemoteExecRuntimePort` 复用原 remote exec manager 与旧 SSH one-shot 行为，当前 desktop / CLI 产品入口和保留 server bootstrap 初始化路径通过 `CoreRuntimeServicesProvider` 构造 provider 并显式注入 `ConversationCoordinator` / 执行上下文 / `ToolRuntimeHandles`；core `ExecCommand` / `WriteStdin` / `ExecControl` 只消费端口，不再直接调用全局本地或远端进程 manager。
 - `agent-runtime` 已承接 scheduler/background delivery 纯决策、dialog lifecycle port contracts、runtime event queue/router、session management/cancellation port contracts、session/config/summary facts、persisted session state sidecar / processing-state sanitization、session state facts / event-label projection、session state manager / event emission owner、dialog-turn id / stats facts、side-question runtime-only tracking、thread-goal facts、context profile / model capability policy、prompt markup / prompt / prompt-cache facts 与持久化写入决策、remote file delivery prompt facts、turn skill/agent snapshot DTO/diff/render/store、file-read session state / prior-read guardrail / freshness 决策、session evidence ledger 与 compression-contract projection、dialog-turn cancellation token store、tool confirmation gate / wait channel state、user-question wait channel state、custom agent / mode / subagent schema、默认值、discovery/loading、markdown IO、validation、review 工具过滤、skill catalog/root specs、mode policy、selection/shadow/mode-info 规则、assistant payload rendering、post-call hook routing、DeepReview provider-neutral policy/queue/retry/diagnostics shaping 与 queue event payload shaping、DeepResearch citation renumber 与 report post-process gate，并建立不暴露 `bitfun-core` / `product-full` / concrete manager 的内部 SDK facade。SDK facade 已支持注入 fake runtime services、tool registry、harness registry、hook registry 和 agent registry。
@@ -41,6 +41,7 @@
 - focused tests 覆盖当前 delivery profile 能力裁剪、ProductAssembler 缺失 service 报告、无直接 core 入口的空 capability plan、SDK fake provider / services / tool / harness / hook / workspace-scoped agent registry 闭环，以及 runtime hook 顺序、timeout、错误策略和重复 id 拦截。
 - focused baseline 覆盖 tool manifest、GetToolSpec、execution admission、workspace search、remote workspace fallback、MCP config/catalog、prompt cache、custom agent / mode / subagent、thread-goal tools、AskUserQuestion、DeepReview policy、tool confirmation、session restore、MiniApp storage/builtin/import、function-agent Git、scheduled-job state 等路径。
 - H4 已完成 Agent Runtime SDK 发布准备的 workspace 内收口：`sdk` facade 暴露 v1 preview 兼容元数据、空默认 feature、稳定注入 registry/service 类型、最小外部 embedder 示例，以及 boundary required rules / self-test 保护。
+- Public API / Tool ABI / Event Manifest 基础闭环已建立：Agent Runtime SDK 继续只暴露 preview facade；`bitfun-agent-tools` 暴露 materialized snapshot / default effect facts / stale-call guard；`bitfun-events` 暴露 AgenticEvent projection manifest；core compatibility path 和 WebSocket adapter 不再拥有对应 contract 清单。
 
 ## 4. Adapter 边界与后续专项
 

docs/plans/core-decomposition-plan.md

@@ -22,16 +22,15 @@
 - workspace 已按六层物理目录展开：`interfaces -> assembly -> adapters -> services -> execution -> contracts`。
 - Runtime Services、Agent Runtime、Tool Contracts、Tool Execution、Harness、Product Domains、Services Core、Services Integrations 等 owner crate 已建立。
 - `bitfun-core --no-default-features` 已裁掉多批 concrete provider 和 direct provider 依赖；Desktop、CLI、ACP 仍通过 `bitfun-core/product-full` 获取完整产品能力。
-- Agentic frontend event projection 已进入 `bitfun-events`；Tauri/WebSocket transport 不再内联事件字段映射。
+- Agentic frontend event projection 和 AgenticEvent projection manifest 已进入 `bitfun-events`；Tauri/WebSocket transport 不再内联事件字段映射或 legacy event allowlist。
+- Tool ABI 基础合同已进入 `tool-contracts`：materialized snapshot、provider identity、default permission/effect filter、cancellation contract 和 stale-call guard 由 owner crate 提供，core 只投射现有产品 Tool 元数据。
 - Terminal / ExecCommand、remote SSH concrete execution、workspace search、debug ingest、AI provider adapter runtime、browser CDP、WebFetch/WebSearch、review platform transport 等多批 owner 已迁出或收口到 port/provider。
 - Boundary scripts 已覆盖核心 owner 防回流、six-layer path 解析、facade-only 文件、custom agent owner / custom subagent wrapper 保护和重点 feature gate。
 
 ## 3. 目标差距
 
 | 差距 | 影响 | 收敛要求 |
 |---|---|---|
-| Public API 面仍有 preview、compatibility 和内部导出混用 | SDK、插件和产品入口可能误依赖旧路径 | 标记 stable/workspace-internal/compatibility，删除或封闭旧 core public path |
-| Tool ABI、Event Manifest、Permission/Effect 仍未完全成为插件可消费合同 | built-in、MCP、ACP、plugin tool 语义可能分裂 | 建立 materialized snapshot、provider identity、stale guard、public event manifest |
 | Plugin Runtime Host 仍是设计合同，未形成主进程窄接口和 disabled/projection stub | 主体进程可能继续感知具体 adapter 或运行单元 | 落地 `PluginRuntimeClient`、binding、capability matrix 和 Host facade 白名单 |
 | UI Extension Contract 与产品形态矩阵仍需实现 | Desktop/Web/CLI/SDK/ACP 的插件 UI 行为可能不一致 | 建立 descriptor round-trip、fallback、unsupported/unavailable 和只读 state view |
 | OpenCode compatibility adapter 仍缺少真实消费路径 | OpenCode 插件能力无法受控进入 BitFun | 先支持 discovery/read-only，再逐步开放 tool provider 和 UI contribution |
@@ -40,39 +39,6 @@
 
 ## 4. 后续大型阶段
 
-### Stage A：Public API Closure 与 Core Facade 缩面
-
-目标：冻结可对外承诺的 API 面，阻止新功能继续绑定旧 core 路径。
-
-范围：
-
-- 梳理 `bitfun-core`、`bitfun-agent-runtime`、`bitfun-runtime-ports`、`bitfun-agent-tools`、`bitfun-runtime-services` 的 public surface。
-- 将导出标为 stable external、workspace-internal、compatibility 三类。
-- 收敛 `bitfun-core::agentic::*`、`bitfun-core::service::*` 等新调用方路径。
-- 将 Agent Runtime SDK-facing facade 与内部模块导出分开。
-- 对仍需保留的 compatibility re-export 增加 owner 注释和 boundary guard。
-
-准出：
-
-- 至少删除、迁移或显著简化一组旧 core public path。
-- `cargo check -p bitfun-core --no-default-features`、`cargo test -p bitfun-agent-runtime`、boundary self-test 和 `git diff --check` 通过。
-
-### Stage B：Tool ABI、Event Manifest 与 Security Control Plane
-
-目标：让 built-in tool、MCP tool、ACP external tool、plugin tool 和 hook 使用同一能力/效果语义。
-
-范围：
-
-- 建立 materialized tool snapshot、provider identity、permission/effect filter、stale call guard 和 cancellation contract。
-- 建立 public event manifest、event version、aggregate identity、replay/retention 和 UI projection contract。
-- 将 collapsed tool、MiniApp headless restriction、delegation restriction 等产品策略改为 decorator / policy provider。
-- 收敛 core 中的 tool manifest、tool result presentation 和部分产品文案旧路径。
-
-准出：
-
-- prompt-visible manifest、`GetToolSpec`、expanded/collapsed exposure、MCP/ACP catalog、remote/local path containment 和 public event projection 行为等价。
-- tool、MCP/ACP、event manifest、product-full 和 boundary focused checks 通过。
-
 ### Stage C：Plugin Runtime Host Foundation
 
 目标：建立主体进程的插件运行时窄接口，并将 OpenCode 等生态适配器限制在 Host 内部。

scripts/core-boundaries/rules/source/forbidden-rules.mjs

@@ -19,6 +19,11 @@ export const forbiddenContentRules = [
         message:
           'WebSocket transport adapter must not match agentic event variants directly; use bitfun-events frontend projection',
       },
+      {
+        regex: /\bfn\s+is_legacy_websocket_agentic_event_type\b/,
+        message:
+          'WebSocket transport adapter must not own the agentic event allowlist; use bitfun-events event manifest',
+      },
     ],
   },
   {

scripts/core-boundaries/rules/source/required-rules.mjs

@@ -32,6 +32,29 @@ export const requiredContentRules = [
       },
     ],
   },
+  {
+    path: 'src/crates/contracts/events/src/agentic_projection_manifest.rs',
+    reason:
+      'events contract must own the public AgenticEvent projection manifest, event versions, aggregate classification, and legacy transport allowlist',
+    patterns: [
+      {
+        regex: /\bpub const AGENTIC_EVENT_PROJECTION_MANIFEST\b/,
+        message: 'missing public AgenticEvent projection manifest',
+      },
+      {
+        regex: /\bpub fn public_agentic_event_projection_manifest\b/,
+        message: 'missing public AgenticEvent projection manifest accessor',
+      },
+      {
+        regex: /\bpub fn is_legacy_websocket_agentic_event_type\b/,
+        message: 'missing manifest-owned legacy WebSocket event allowlist helper',
+      },
+      {
+        regex: /\bpublic_event_projection_manifest_describes_projected_events_and_websocket_allowlist\b/,
+        message: 'missing public projection manifest regression test',
+      },
+    ],
+  },
   {
     path: 'src/crates/adapters/transport/src/adapters/tauri.rs',
     reason:
@@ -6706,6 +6729,10 @@ export const requiredContentRules = [
         regex: /\bpub struct ToolRuntimeAssembly\b/,
         message: 'missing generic runtime assembly contract',
       },
+      {
+        regex: /\bpub async fn materialized_tool_snapshot\b/,
+        message: 'missing registry materialized snapshot accessor',
+      },
       {
         regex: /\bpub type ToolDecoratorRef\b/,
         message: 'missing generic decorator ref contract',
@@ -6768,6 +6795,45 @@ export const requiredContentRules = [
       },
     ],
   },
+  {
+    path: 'src/crates/execution/tool-contracts/src/tool_snapshot.rs',
+    reason:
+      'agent-tools must own materialized tool snapshots, provider identity, effect facts, cancellation facts, and stale-call guards',
+    patterns: [
+      {
+        regex: /\bpub struct MaterializedToolSnapshot\b/,
+        message: 'missing materialized tool snapshot contract',
+      },
+      {
+        regex: /\bpub struct ToolProviderIdentity\b/,
+        message: 'missing provider-neutral tool identity contract',
+      },
+      {
+        regex: /\bpub struct ToolEffectFacts\b/,
+        message: 'missing provider-neutral tool effect facts contract',
+      },
+      {
+        regex: /\bpub enum ToolEffectFactsSource\b/,
+        message: 'missing tool effect facts source contract',
+      },
+      {
+        regex: /\bpub struct ToolEffectFilter\b/,
+        message: 'missing provider-neutral tool effect filter contract',
+      },
+      {
+        regex: /\bpub struct ToolCallSnapshotGuard\b/,
+        message: 'missing stale-call snapshot guard contract',
+      },
+      {
+        regex: /\bpub enum ToolSnapshotCallError\b/,
+        message: 'missing stale-call snapshot error contract',
+      },
+      {
+        regex: /\bpub async fn materialize_tool_snapshot\b/,
+        message: 'missing materialized tool snapshot builder',
+      },
+    ],
+  },
   {
     path: 'src/crates/execution/tool-provider-groups/src/lib.rs',
     reason:

scripts/core-boundaries/self-test.mjs

@@ -1220,6 +1220,15 @@ export function runManifestParserSelfTest({
         'legacy_flat_dialog_turn_started_preserves_existing_shape',
       ],
     },
+    {
+      path: 'src/crates/contracts/events/src/agentic_projection_manifest.rs',
+      contracts: [
+        'AGENTIC_EVENT_PROJECTION_MANIFEST',
+        'public_agentic_event_projection_manifest',
+        'is_legacy_websocket_agentic_event_type',
+        'public_event_projection_manifest_describes_projected_events_and_websocket_allowlist',
+      ],
+    },
     {
       path: 'src/crates/adapters/transport/src/adapters/tauri.rs',
       contracts: ['project_agentic_frontend_event', 'projected.event_name.as_str()'],
@@ -2630,6 +2639,7 @@ export function runManifestParserSelfTest({
         'StaticToolMaterializationError',
         'materialize_static_tool_provider_groups',
         'ToolRuntimeAssembly',
+        'materialized_tool_snapshot',
         'create_registry_from_static_provider_plans',
         'create_registry_from_static_provider_entries',
         'ToolCatalogRuntime',
@@ -2650,6 +2660,19 @@ export function runManifestParserSelfTest({
         'call_results',
       ],
     },
+    {
+      path: 'src/crates/execution/tool-contracts/src/tool_snapshot.rs',
+      contracts: [
+        'MaterializedToolSnapshot',
+        'ToolProviderIdentity',
+        'ToolEffectFacts',
+        'ToolEffectFactsSource',
+        'ToolEffectFilter',
+        'ToolCallSnapshotGuard',
+        'ToolSnapshotCallError',
+        'materialize_tool_snapshot',
+      ],
+    },
     {
       path: 'src/crates/execution/tool-contracts/src/mcp_tool_bridge.rs',
       contracts: [

src/crates/adapters/transport/src/adapters/websocket.rs

@@ -5,7 +5,9 @@
 /// event set to text messages.
 use crate::traits::{TextChunk, ToolEventPayload, TransportAdapter};
 use async_trait::async_trait;
-use bitfun_events::{project_agentic_frontend_event, AgenticEvent};
+use bitfun_events::{
+    is_legacy_websocket_agentic_event_type, project_agentic_frontend_event, AgenticEvent,
+};
 use serde_json::json;
 use std::fmt;
 use tokio::sync::mpsc;
@@ -44,24 +46,6 @@ impl fmt::Debug for WebSocketTransportAdapter {
     }
 }
 
-fn is_legacy_websocket_agentic_event_type(event_type: &str) -> bool {
-    matches!(
-        event_type,
-        "image-analysis-started"
-            | "image-analysis-completed"
-            | "dialog-turn-started"
-            | "subagent-session-linked"
-            | "model-round-started"
-            | "text-chunk"
-            | "tool-event"
-            | "token-usage-updated"
-            | "model-round-completed"
-            | "dialog-turn-completed"
-            | "deep-review-queue-state-changed"
-            | "thread-goal-updated"
-    )
-}
-
 #[async_trait]
 impl TransportAdapter for WebSocketTransportAdapter {
     async fn emit_event(&self, _session_id: &str, event: AgenticEvent) -> anyhow::Result<()> {

src/crates/assembly/core/src/agentic/tools/tool_adapter.rs

@@ -37,6 +37,18 @@ impl ToolRegistryItem for dyn Tool {
         Tool::is_readonly(self)
     }
 
+    fn is_concurrency_safe(&self, input: Option<&Value>) -> bool {
+        Tool::is_concurrency_safe(self, input)
+    }
+
+    fn needs_permissions(&self, input: Option<&Value>) -> bool {
+        Tool::needs_permissions(self, input)
+    }
+
+    fn manages_own_execution_timeout(&self) -> bool {
+        Tool::manages_own_execution_timeout(self)
+    }
+
     async fn is_enabled(&self) -> bool {
         Tool::is_enabled(self).await
     }