Struct BuiltinToolExecutor 

pub struct BuiltinToolExecutor { /* private fields */ }

Built-in tool executor that uses ToolRegistry for dynamic dispatch

Implementations

impl BuiltinToolExecutor

pub fn new() -> Self

Creates a new executor with all built-in tools registered

pub fn new_with_permissions( permission_checker: Arc<dyn PermissionChecker>, ) -> Self

Creates a new executor with a permission checker

pub fn new_with_config(_config: Arc<RwLock<Config>>) -> Self

Compatibility constructor for callers that already hold shared config. Current built-ins have no executor-time configuration dependency.

pub fn new_with_config_and_permissions( _config: Arc<RwLock<Config>>, permission_checker: Arc<dyn PermissionChecker>, ) -> Self

Creates a new executor with both shared config and a permission checker.

pub fn with_registry(registry: ToolRegistry) -> Self

Creates a new executor from an existing registry

pub fn with_registry_and_permissions( registry: ToolRegistry, permission_checker: Arc<dyn PermissionChecker>, ) -> Self

Creates a new executor from an existing registry and permission checker.

This is the dependency-injection counterpart to new_with_permissions: callers that intentionally expose a selected/custom registry can keep the canonical permission gate instead of silently dropping it.

pub fn with_tool_event_publisher( self, publisher: Arc<dyn ToolEventPublisher>, ) -> Self

Inject an instance-local, non-blocking tool-event publisher.

pub fn registry(&self) -> &ToolRegistry

Returns a reference to the internal registry

pub fn eligible_native_tool(&self, name: &str) -> bool

Observe the registered Arc, not a same-name custom replacement.

pub fn with_native_tool_ceiling( self, names: Vec<String>, ) -> Result<Self, ToolError>

Install an immutable positive ceiling. Reinstallation can only narrow it.

pub fn tool_schemas() -> Vec<ToolSchema>

Returns all built-in tool schemas

pub fn register_tool<T: Tool + 'static>(&self, tool: T) -> Result<(), ToolError>

Registers a custom tool to this executor

pub fn register_tool_with_guide<T, G>( &self, tool: T, guide: G, ) -> Result<(), ToolError>

where T: Tool + 'static, G: ToolGuide + 'static,

Register a tool with its guide

pub fn get_guide(&self, tool_name: &str) -> Option<Arc<dyn ToolGuide>>

Get guide for a tool

pub async fn check_framework_root_spawn_permissions( &self, call: &ToolCall, args: &Value, ctx: &ToolExecutionContext<'_>, ) -> Result<Option<ToolOutcome>, ToolError>

Host-side permission entry used only by the installed v2 Root owner. Classification is explicit while the typed request retains the actual spawn_session identity, original argument bytes and existing once gates.

pub fn build_enhanced_prompt(&self, context: GuideBuildContext) -> String

Build enhanced prompt for all registered tools

Trait Implementations

impl Default for BuiltinToolExecutor

fn default() -> Self

Returns the “default value” for a type.

impl ToolExecutor for BuiltinToolExecutor

fn check_permissions_for<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, call: &'life1 ToolCall, ctx: &'life2 ToolExecutionContext<'life3>, ) -> Pin<Box<dyn Future<Output = Result<Option<ToolOutcome>, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

The real permission gate for built-in tools, extracted from the execute path so it is reusable by wrapping executors (issue #341). The behavior is byte-for-byte the same block that used to run inline in execute_with_context_outcome:

• resolves the SAME tool_name + args the execute path runs with (so the check sees exactly what the tool will run with);
• “always ask” rules (requires_forced_confirmation) force a confirmation even under bypass; everything else is skipped when the session is in bypass-permissions mode;
• forced confirmations route through check_or_request_forced so the active mode/bypass can’t suppress the prompt;
• a ConfirmationRequired first tries the cross-process ApprovalProxy (a subagent worker forwarding to its host), then the interactive human sink (returning the synthesized approval pause as Ok(Some(..))), then fails closed;
• deny fails closed.

The only mechanical difference from the old inline block: the interactive pause is returned as Ok(Some(outcome)) and a clean pass returns Ok(None), so the caller decides whether to run the tool. The fallback arg-parse warning is intentionally NOT re-logged here — the execute path already logs it once for this call.

fn execute<'life0, 'life1, 'async_trait>( &'life0 self, call: &'life1 ToolCall, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Executes a tool call

fn execute_with_context<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, call: &'life1 ToolCall, ctx: ToolExecutionContext<'life2>, ) -> Pin<Box<dyn Future<Output = Result<ToolResult, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Executes a tool call with streaming-capable context.

fn execute_with_context_outcome<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, call: &'life1 ToolCall, ctx: ToolExecutionContext<'life2>, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Outcome-aware dispatch: returns the tool’s ToolOutcome rather than the collapsed ToolResult, so the agent loop can branch on Completed/Running/NeedsHuman directly instead of sniffing markers on a result. The default collapses via the execute_with_context path (always Completed), so executors that never surface Running/NeedsHuman (composition, MCP, tests) need no override; the built-in + overlay executors override this to return the real outcome.

fn execute_exact_with_context_outcome<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, call: &'life1 ToolCall, execution_name: &'life2 str, ctx: ToolExecutionContext<'life3>, ) -> Pin<Box<dyn Future<Output = Result<ToolOutcome, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Execute a call through an already-selected exact owner.

fn check_permissions_for_exact<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, call: &'life1 ToolCall, execution_name: &'life2 str, ctx: &'life3 ToolExecutionContext<'life4>, ) -> Pin<Box<dyn Future<Output = Result<Option<ToolOutcome>, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

Permission gate for an already-selected exact owner identity.

fn check_permissions_for_resolved<'life0, 'life1, 'life2, 'life3, 'life4, 'life5, 'async_trait>( &'life0 self, call: &'life1 ToolCall, execution_name: &'life2 str, resolved_args: &'life3 Value, ctx: &'life4 ToolExecutionContext<'life5>, ) -> Pin<Box<dyn Future<Output = Result<Option<ToolOutcome>, ToolError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait, 'life5: 'async_trait,

Permission gate for a call whose exact execution identity and effective arguments have already been resolved by a wrapping executor.

fn list_tools(&self) -> Vec<ToolSchema>

Lists all available tools and their schemas

fn owns_exact_tool(&self, tool_name: &str) -> bool

Returns whether this executor owns tool_name as a complete, exact, case-sensitive execution identity.

fn exact_tool_owner(&self, name: &str) -> Option<&dyn ToolExecutor>

Read-only observation of the concrete exact owner in a known routing chain. Unknown wrappers return None; existence/name is not provenance.

fn local_execution_contract(&self, name: &str) -> Option<&'static str>

Only concrete owners override this hook. Transparent wrappers retain their existing exact-owner forwarding instead of guessing provenance.

fn local_tool_instance(&self, name: &str) -> Option<Arc<dyn Tool>>

fn tool_mutability(&self, tool_name: &str) -> ToolMutability

Returns mutability metadata for a tool name when available. Executors that can inspect concrete tools should override this.

fn call_mutability(&self, call: &ToolCall) -> ToolMutability

Returns mutability metadata for a specific tool call when available. Defaults to name-based classification.

fn tool_concurrency_safe(&self, tool_name: &str) -> bool

Returns whether a tool can safely execute in parallel with other read-only tools. Executors that can inspect concrete tools should override this. Fallback keeps current behavior for known read-only tools.

fn call_concurrency_safe(&self, call: &ToolCall) -> bool

Returns whether a specific tool call can safely run in parallel. Defaults to the tool-name level classification.

fn call_parallel_classification( &self, call: &ToolCall, ) -> (ToolMutability, bool)

Classify a tool call’s mutability AND concurrency-safety together, returning (mutability, concurrency_safe).

fn for_session(&self, _session: &Session) -> Option<Arc<dyn ToolExecutor>>

Optionally bind an already installed Host tool surface to a canonical Session contract. This selects registrations, never adds a grant. Unknown wrappers retain the existing behavior with None.

fn resolve_reference_for_session( &self, session: &Session, reference: &str, ) -> Option<String>

Use the same versioned exact owner for live dispatch and typed replay.

fn execution_contract_for_exact(&self, name: &str) -> Option<&'static str>

Observe semantics through the existing exact-owner chain. Calling only the owner’s local hook avoids recursion when an owner returns self. Opaque wrappers supply no provenance, even when their catalog has a name.

fn tool_instance_for_exact(&self, name: &str) -> Option<Arc<dyn Tool>>

Registry replacement is observable even if name and contract agree.

fn framework_session_tool_for_exact( &self, name: &str, ) -> Option<HostFrameworkSessionTool>

Only an explicit Host factory supplies this opaque in-process proof. Unknown wrappers and names/contract strings alone supply no provenance.

fn local_framework_session_tool( &self, _name: &str, ) -> Option<HostFrameworkSessionTool>

fn tool_guidance(&self) -> Option<String>

Server-level usage guidance to surface in the system prompt for whatever this executor currently exposes — e.g. the instructions an MCP server returns from initialize. Because it is derived from the live executor, the text is naturally scoped to what is actually connected/loaded for the run (a disconnected server contributes nothing).