refactor(core): centralize tool context runtime bindings

docs/architecture/core-decomposition.md

@@ -301,6 +301,14 @@ owner 边界，否则不要把一个 feature group 继续拆成更小的 crate
   manifest / GetToolSpec facade 与 snapshot wrapper 注入。该收口不改变工具执行路径，
   也不声明 `ToolUseContext`、collapsed unlock state、`GetToolSpecTool` Tool impl、
   snapshot runtime 或 concrete tools 已迁出 core。
+- HR1 后续收口进一步把 `ToolUseContext` 的 workspace service accessor、runtime artifact
+  lookup、path policy enforcement、tool pipeline/description/preflight context
+  materialization、tool-call cancellation/post-call hook wrapper 和 Deep Review light checkpoint 绑定集中到
+  core-owned `tools/tool_context_runtime.rs`；`framework.rs` 只保留 context shape、
+  portable facts projection 与 `Tool` trait。该调整仍不迁移 `ToolUseContext`
+  本体、runtime service handles 或 concrete tool behavior，并通过 remote workspace
+  containment、runtime URI scope、path policy、task/description/preflight context materialization
+  与 cancellation hook 回归测试保护现有工具语义。
 - 已完成的 MCP runtime/dynamic tools、remote-connect tracker/wire/pure policy、
   semantic baseline、product-domain port/facade 与 tool contract/helper 外移不得重复规划；
   如果后续发现这些已完成项存在实现错误，应在对应 H 阶段记录问题、风险和修复方案，

docs/plans/core-decomposition-plan.md

@@ -2142,7 +2142,7 @@ git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts
 29. 已完成：H1 tool catalog runtime facade slice。`bitfun-agent-tools::ToolCatalogRuntime` 接管 provider-backed visible-tools、prompt-visible manifest 与 readonly enabled catalog 查询入口；core 继续持有 product registry snapshot、agent policy、`dyn Tool` / `ToolUseContext` adapter 和 product facade，不迁移 `ToolUseContext`、`GetToolSpecTool` Tool impl、collapsed unlock state、snapshot wrapper implementation 或 concrete tools。
 30. 已完成：H1 GetToolSpec Tool adapter facade slice。`bitfun-agent-tools::GetToolSpecRuntime::call_results` 接管单次执行结果到 `Vec<ToolResult>` 的通用适配形状，core `product_runtime.rs` 暴露 product `resolve_product_get_tool_spec_results`，`GetToolSpecTool::call_impl` 只保留 product facade 委托和 `BitFunError` 映射；不迁移 `ToolUseContext`、runtime manifest assembly、unlock state owner、assistant rendering 语义或 concrete tools。
 31. 已完成：H1 product provider plan closure。`bitfun-tool-packs::product_tool_provider_group_plan` 接管 product provider group id / feature group / tool-name order 计划，core `product_runtime.rs` 只按该计划物化 concrete tools 并继续注入 snapshot wrapper；不迁移 concrete tool implementation、`ToolUseContext`、runtime service handles 或 tool behavior。
-32. HR1 当前闭环状态：工具 runtime 的 provider-neutral contract、host path normalization / runtime artifact URI / remote POSIX path pure contract、allowed-list / collapsed-tool execution gate policy、manifest/catalog runtime facade、GetToolSpec facade、static-provider assembly、readonly filtering、provider plan 与 core product adapter 已收敛；core 内部 product runtime adapter 已统一到 `product_runtime.rs`。`ToolUseContext` 本体和 concrete tools 仍显式 core-owned；继续外移会触碰 workspace services、cancellation、Deep Review hooks 或具体工具 IO，必须作为后续高风险 owner 迁移单独确认。
+32. HR1 当前闭环状态：工具 runtime 的 provider-neutral contract、host path normalization / runtime artifact URI / remote POSIX path pure contract、allowed-list / collapsed-tool execution gate policy、manifest/catalog runtime facade、GetToolSpec facade、static-provider assembly、readonly filtering、provider plan 与 core product adapter 已收敛；core 内部 product runtime adapter 已统一到 `product_runtime.rs`。本轮进一步把 `ToolUseContext` 上的 workspace service accessor、runtime artifact lookup、path policy enforcement、tool pipeline/description/preflight context materialization、tool-call cancellation/post-call hook wrapper 和 Deep Review light checkpoint 绑定集中到 `tool_context_runtime.rs`，作为 core-owned runtime binding owner，并补齐 remote workspace containment、runtime URI scope、path policy、task/description/preflight context materialization 与 cancellation hook 回归测试；`framework.rs` 只保留 context shape、portable facts projection 和 `Tool` trait。`ToolUseContext` 本体和 concrete tools 仍显式 core-owned；继续外移会触碰 workspace services、cancellation、Deep Review hooks 或具体工具 IO，必须作为后续高风险 owner 迁移单独确认。
 33. H4 已完成：facade / boundary finalization。`scripts/check-core-boundaries.mjs` 的 regular check 和 self-test 已覆盖 remote-connect file/image/dialog owner anchor、core adapter/deferred owner anchor 与既有 duplicate-path required rule；root / core / services-integrations 文档与当前 H1-H3 代码状态一致，不声明 remote-SSH runtime、agent registry/scheduler、default feature 或构建收益已完成。
 34. H5 已启动并完成当前闭环：第一步建立 `bitfun-core --no-default-features` 编译闭环，
     证明 `ssh-remote` 关闭时不再编译 russh-backed runtime，并通过 disabled surface

scripts/check-core-boundaries.mjs

@@ -494,6 +494,36 @@ const forbiddenContentRules = [
         regex: /\bpub enum ToolWorkspaceKind\b/,
         message: 'core tool framework must not redefine ToolWorkspaceKind; use bitfun-agent-tools',
       },
+      {
+        regex: /\bget_global_coordinator\b/,
+        message:
+          'core tool framework must not own runtime checkpoint coordination; keep it in tool_context_runtime',
+      },
+      {
+        regex: /\bGitService\b/,
+        message:
+          'core tool framework must not own git-backed checkpoint runtime; keep it in tool_context_runtime',
+      },
+      {
+        regex: /\bget_workspace_runtime_service_arc\b/,
+        message:
+          'core tool framework must not own workspace runtime lookup; keep it in tool_context_runtime',
+      },
+      {
+        regex: /\bremote_workspace_runtime_root\b/,
+        message:
+          'core tool framework must not own remote runtime-root lookup; keep it in tool_context_runtime',
+      },
+      {
+        regex: /\bget_path_manager_arc\b/,
+        message:
+          'core tool framework must not own host runtime-root lookup; keep it in tool_context_runtime',
+      },
+      {
+        regex: /\bpost_call_hooks::record_successful_tool_call\b/,
+        message:
+          'core tool framework must not own post-call runtime hooks; keep them in tool_context_runtime',
+      },
     ],
   },
   {
@@ -2567,6 +2597,77 @@ const requiredContentRules = [
       },
     ],
   },
+  {
+    path: 'src/crates/core/src/agentic/tools/tool_context_runtime.rs',
+    reason:
+      'core must keep ToolUseContext runtime/service bindings centralized while ToolUseContext and concrete tools remain core-owned',
+    patterns: [
+      {
+        regex: /\bimpl ToolUseContext\b/,
+        message: 'missing ToolUseContext runtime binding owner impl',
+      },
+      {
+        regex: /\brecord_light_checkpoint\b/,
+        message: 'missing Deep Review checkpoint binding',
+      },
+      {
+        regex: /\bcall_with_tool_runtime_hooks\b/,
+        message: 'missing tool-call cancellation/post-call hook binding',
+      },
+      {
+        regex: /\bbuild_tool_use_context_for_task\b/,
+        message: 'missing tool pipeline context materialization binding',
+      },
+      {
+        regex: /\bbuild_tool_description_context\b/,
+        message: 'missing tool manifest description context materialization binding',
+      },
+      {
+        regex: /\bbuild_write_preflight_context\b/,
+        message: 'missing write preflight context materialization binding',
+      },
+      {
+        regex: /\bensure_current_workspace_runtime\b/,
+        message: 'missing workspace runtime ensure binding',
+      },
+      {
+        regex: /\bresolve_tool_path\b/,
+        message: 'missing tool path resolution binding',
+      },
+      {
+        regex: /\benforce_path_operation\b/,
+        message: 'missing runtime path policy binding',
+      },
+      {
+        regex: /\bworkspace_path_resolution_rejects_absolute_paths_outside_remote_workspace\b/,
+        message: 'missing remote workspace containment regression',
+      },
+      {
+        regex: /\bruntime_uri_resolution_rejects_different_workspace_scope\b/,
+        message: 'missing runtime artifact scope regression',
+      },
+      {
+        regex: /\bpath_policy_allows_only_configured_local_roots\b/,
+        message: 'missing path policy enforcement regression',
+      },
+      {
+        regex: /\btool_call_runtime_hook_returns_cancelled_before_impl_completes\b/,
+        message: 'missing tool-call cancellation regression',
+      },
+      {
+        regex: /\btool_task_context_materialization_preserves_runtime_fields\b/,
+        message: 'missing tool task context materialization regression',
+      },
+      {
+        regex: /\btool_description_context_preserves_manifest_custom_data_shape\b/,
+        message: 'missing tool description context regression',
+      },
+      {
+        regex: /\bwrite_preflight_context_preserves_minimal_runtime_fields\b/,
+        message: 'missing write preflight context regression',
+      },
+    ],
+  },
   {
     path: 'src/crates/core/src/agentic/tools/pipeline/tool_pipeline.rs',
     reason:
@@ -4392,6 +4493,12 @@ function runManifestParserSelfTest() {
     'ToolRenderOptions',
     'ToolPathBackend',
     'ToolPathResolution',
+    'get_global_coordinator',
+    'GitService',
+    'get_workspace_runtime_service_arc',
+    'remote_workspace_runtime_root',
+    'get_path_manager_arc',
+    'post_call_hooks::record_successful_tool_call',
   ];
   const coreToolFrameworkRuleText = coreToolFrameworkRule.patterns
     .map((pattern) => pattern.regex.source)
@@ -4843,6 +4950,27 @@ function runManifestParserSelfTest() {
         'unlocked_collapsed_tools',
       ],
     },
+    {
+      path: 'src/crates/core/src/agentic/tools/tool_context_runtime.rs',
+      contracts: [
+        'impl ToolUseContext',
+        'record_light_checkpoint',
+        'call_with_tool_runtime_hooks',
+        'build_tool_use_context_for_task',
+        'build_tool_description_context',
+        'build_write_preflight_context',
+        'ensure_current_workspace_runtime',
+        'resolve_tool_path',
+        'enforce_path_operation',
+        'workspace_path_resolution_rejects_absolute_paths_outside_remote_workspace',
+        'runtime_uri_resolution_rejects_different_workspace_scope',
+        'path_policy_allows_only_configured_local_roots',
+        'tool_call_runtime_hook_returns_cancelled_before_impl_completes',
+        'tool_task_context_materialization_preserves_runtime_fields',
+        'tool_description_context_preserves_manifest_custom_data_shape',
+        'write_preflight_context_preserves_minimal_runtime_fields',
+      ],
+    },
     {
       path: 'src/crates/core/src/agentic/tools/pipeline/tool_pipeline.rs',
       contracts: ['validate_collapsed_tool_usage', 'unlocked_collapsed_tools', 'GetToolSpec'],

src/crates/core/AGENTS.md

@@ -51,6 +51,12 @@ SessionManager → Session → DialogTurn → ModelRound
   reviewed port/provider plan and equivalence tests exist. `ToolContextFacts`
   / `PortableToolContextProvider` are only portable projections; they must not
   carry runtime handles, workspace services, or cancellation tokens.
+- Keep `ToolUseContext` runtime/service bindings centralized in
+  `src/agentic/tools/tool_context_runtime.rs`. `framework.rs` should define the
+  context shape, portable facts projection, and tool trait, not own workspace
+  runtime lookup, path enforcement, pipeline/description/preflight context
+  materialization, cancellation wrapping, post-call hooks, or checkpoint
+  collection.
 - Host path normalization, runtime artifact URI parsing/building, and remote
   POSIX path containment are portable `bitfun-agent-tools` contracts. Core
   keeps compatibility wrappers for `BitFunError`, workspace runtime-root

src/crates/core/src/agentic/execution/execution_engine.rs

@@ -5,23 +5,23 @@
 use super::round_executor::RoundExecutor;
 use super::types::{ExecutionContext, ExecutionResult, RoundContext, RoundResult};
 use crate::agentic::agents::{
-    get_agent_registry, PromptBuilder, PromptBuilderContext, RemoteExecutionHints,
+    PromptBuilder, PromptBuilderContext, RemoteExecutionHints, get_agent_registry,
 };
 use crate::agentic::context_profile::{ContextProfilePolicy, ModelCapabilityProfile};
 use crate::agentic::core::{
-    render_system_reminder, Message, MessageContent, MessageHelper, MessageRole,
-    MessageSemanticKind, RequestReasoningTokenPolicy, Session,
+    Message, MessageContent, MessageHelper, MessageRole, MessageSemanticKind,
+    RequestReasoningTokenPolicy, Session, render_system_reminder,
 };
 use crate::agentic::events::{AgenticEvent, EventPriority, EventQueue};
 use crate::agentic::execution::types::FinishReason;
 use crate::agentic::image_analysis::{
-    build_multimodal_message_with_images, process_image_contexts_for_provider, ImageContextData,
-    ImageLimits,
+    ImageContextData, ImageLimits, build_multimodal_message_with_images,
+    process_image_contexts_for_provider,
 };
 use crate::agentic::round_preempt::RoundInjectionKind;
 use crate::agentic::session::{CompressionTailPolicy, ContextCompressor, SessionManager};
 use crate::agentic::tools::{
-    resolve_tool_manifest, ResolvedToolManifest, SubagentParentInfo, ToolRuntimeRestrictions,
+    ResolvedToolManifest, SubagentParentInfo, resolve_tool_manifest, tool_context_runtime,
 };
 use crate::agentic::util::build_remote_workspace_layout_preview;
 use crate::agentic::{WorkspaceBackend, WorkspaceBinding};
@@ -34,7 +34,7 @@ use crate::util::token_counter::TokenCounter;
 use crate::util::types::Message as AIMessage;
 use crate::util::types::ToolDefinition;
 use crate::util::{elapsed_ms_u64, truncate_at_char_boundary};
-use bitfun_agent_tools::{collect_loaded_collapsed_tool_names, GetToolSpecLoadObservation};
+use bitfun_agent_tools::{GetToolSpecLoadObservation, collect_loaded_collapsed_tool_names};
 use log::{debug, error, info, trace, warn};
 use sha2::{Digest, Sha256};
 use std::collections::{HashMap, HashSet};
@@ -2510,27 +2510,13 @@ impl ExecutionEngine {
         primary_supports_image_understanding: bool,
         context_vars: &HashMap<String, String>,
     ) -> ResolvedToolManifest {
-        let mut tool_opts_custom = HashMap::new();
-        tool_opts_custom.insert(
-            "primary_model_supports_image_understanding".to_string(),
-            serde_json::Value::Bool(primary_supports_image_understanding),
+        let description_context = tool_context_runtime::build_tool_description_context(
+            agent_type,
+            workspace,
+            workspace_services,
+            primary_supports_image_understanding,
+            context_vars,
         );
-        for (key, value) in context_vars {
-            tool_opts_custom.insert(key.clone(), serde_json::Value::String(value.clone()));
-        }
-        let description_context = crate::agentic::tools::framework::ToolUseContext {
-            tool_call_id: None,
-            agent_type: Some(agent_type.to_string()),
-            session_id: None,
-            dialog_turn_id: None,
-            workspace: workspace.cloned(),
-            unlocked_collapsed_tools: Vec::new(),
-            custom_data: tool_opts_custom,
-            computer_use_host: None,
-            cancellation_token: None,
-            runtime_tool_restrictions: ToolRuntimeRestrictions::default(),
-            workspace_services: workspace_services.cloned(),
-        };
         resolve_tool_manifest(allowed_tools, exposure_overrides, &description_context).await
     }