Thinker Decision (tool_use)
     │
     ▼
Harness loop (harness::agent::loop_graph / harness::agent::think)
     │
     ▼
ToolService (scoped tool stack: src/tools/scoped/builder.rs)
     │   Adapter: src/tools/adapters/registry_adapter
     │   Exposes Arc<dyn ToolService> as a LoopTool
     │
     ▼
Executor
     │
     ├─ BuiltinToolRegistry  (src/executor/builtin_registry/)
     │     Surfaces Arc<ToolRegistry> to the tool stack
     │
     └─ ToolRegistry trait   (src/executor/tool_registry.rs)
           Resolves a name to a UnifiedTool, executes the call

pub trait ToolRegistry: Send + Sync {
    fn get_tool(&self, name: &str) -> Option<&UnifiedTool>;

    fn execute_tool(
        &self,
        tool_name: &str,
        arguments: Value,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<Value>> + Send + '_>>;

    // Optional per-run shared handles (default None):

    /// Shared workspace handle: written by the execution engine after workspace
    /// resolution, read by tools like `memory_search`.
    fn workspace_handle(&self) -> Option<Arc<tokio::sync::RwLock<String>>> { None }

    /// Shared per-agent SmartRecallConfig map: Two-Phase Smart Recall for `memory_search`.
    fn smart_recall_config_handle(
        &self,
    ) -> Option<Arc<tokio::sync::RwLock<HashMap<String, SmartRecallConfig>>>> { None }

    /// Shared SessionContext: agent management tools bind agent switches to
    /// the correct conversation.
    fn session_context_handle(
        &self,
    ) -> Option<Arc<tokio::sync::RwLock<SessionContext>>> { None }

    /// Shared ToolContextHandle: workspace-scoped output paths.
    fn tool_context_handle(&self) -> Option<crate::tools::ToolContextHandle> { None }

    /// Shared session-key handle: `memory_search` `scope=current_session` filter.
    fn session_key_handle(&self) -> Option<Arc<tokio::sync::RwLock<String>>> { None }
}

impl ToolRegistry for BuiltinToolRegistry {
    fn get_tool(&self, name: &str) -> Option<&UnifiedTool> { /* … */ }
    fn execute_tool(&self, name: &str, args: Value) -> BoxFuture<'_, Result<Value>> { /* … */ }
    // workspace_handle / tool_context_handle / session_key_handle return real Arcs
}

pub struct BuiltinToolConfig {
    pub gateway_context: Option<Arc<GatewayContext>>,
    pub tool_catalog: Option<Arc<ToolCatalog>>,
    /* other dependencies */
}

impl BuiltinToolRegistry {
    pub async fn new() -> Result<Arc<Self>>;
    pub async fn with_config(config: BuiltinToolConfig) -> Result<Arc<Self>>;
}

pub struct UnifiedTool {
    pub id: String,                          // "builtin:search" | "mcp:fs:read_file" | "plugin:diagnostics:ping" | …
    pub name: String,                        // command name (no namespace prefix)
    pub source: ToolSource,                  // Builtin | Native | Mcp { server } | Skill { id } | Plugin { .. } | Custom { .. }
    pub routing_regex: Option<String>,       // reverses into a RoutingRuleConfig
    pub routing_strip_prefix: bool,          // strip prefix after slash-command match
    pub routing_system_prompt: Option<String>,
    pub routing_capabilities: Vec<String>,   // skill allowed-tools whitelist
    pub routing_intent_type: Option<String>,
    pub routing_context_format: Option<String>,
    pub aliases: Vec<String>,                // fuzzy matching + slash-command parsing
    pub visible_channels: Vec<ChannelType>,
    pub sort_order: u32,
    pub is_active: bool,
    pub is_builtin: bool,
    /* … */
}

pub struct ExecutionResult { content, tool_calls, task_results, execution_time_ms, success, error }
pub struct ToolCallRecord { tool_name, parameters, result, success, execution_time_ms }
pub struct TaskExecutionResult { task_id, description, success, output, error, execution_time_ms }
pub struct ExecutionContext { app_context, window_title, session_id, stream }
pub enum ExecutorError { ExecutionFailed, ToolError, TaskFailed { task_id, error }, Timeout, Cancelled }

ExecAuditLayer → PermissionLayer → ContextRuleLayer → TimeoutLayer → CoreDispatch