Struct ShellTools 

pub struct ShellTools { /* private fields */ }

The built-in tool set: bash. Shared behind an Arc between the engine’s Agent and the driver.

Implementations

impl ShellTools

pub fn builtin_specs() -> Vec<ToolSpec>

The specs the built-in tool set advertises. Fixed at compile time and independent of the instance: the system-prompt renderer names the same tools the resolver offers, so the prompt and the API’s tools array cannot drift.

pub fn new(workspace: impl Into<PathBuf>) -> ShellTools

Tools rooted at workspace, commands running on this host; the path is canonicalized, falling back to the input if canonicalization fails (canonicalization requires every component to exist). A build without the local-shell feature installs the no-shell executor: every command fails in-band until a real one is installed.

pub fn with_env( workspace: impl Into<PathBuf>, env: &BTreeMap<String, String>, ) -> ShellTools

Tools rooted at workspace whose commands run with env layered over the inherited environment — how a frontend hands its agent’s tools a connection (a daemon URL, a scoped token, a PATH addition) without touching the process environment. A wired crate::vision macro rides the same map: its staging directory’s var lights the inbox up. A build without the local-shell feature installs the no-shell executor either way: the env has nothing to ride on.

pub fn with_executor( workspace: impl Into<PathBuf>, exec: Arc<dyn ShellExecutor>, ) -> ShellTools

Tools rooted at workspace whose commands run on exec — the seam a remote-shell frontend comes in through.

pub fn with_vision_inbox(self, inbox: Option<PathBuf>) -> ShellTools

Lights the vision inbox up explicitly — the seam a resolver that runs its own inner ShellTools (the subagents extension) uses to inherit its parent’s inbox, since it builds on Self::with_executor, which reads no env map.

pub fn vision_inbox(&self) -> Option<&Path>

The staging directory images attach from, when a frontend wired the crate::vision macro for this shell.

pub fn workspace(&self) -> &Path

The working directory every command starts in.

pub fn executor(&self) -> Arc<dyn ShellExecutor>

The executor commands run on. A resolver that runs its own inner ShellTools — the subagents extension — builds the inner one on the same executor, so subagents land where the turn’s commands land.

pub fn install_approval(&self, approval: Arc<dyn Approval>)

Installs the approval hook consulted by the tool. Call once per turn before stepping; tool resolution cannot overlap another turn’s hook, so the swap is safe.

pub fn current_approval(&self) -> Option<Arc<dyn Approval>>

The approval hook installed for the current turn, if any. A resolver that runs its own inner ShellTools — the subagents extension — reads this to inherit the turn’s policy rather than holding a hook of its own.

pub fn clear_approval(&self)

Removes the approval hook; calls reject until one is installed again.

Trait Implementations

impl ToolResolver for ShellTools

fn specs(&self) -> Vec<ToolSpec>

The tools offered to the model this step.

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

where 'life0: 'async_trait, 'life1: 'async_trait, ShellTools: 'async_trait,

Turn a model’s call into a result. Errors become in-band results: implementations must not panic and must not abort on unknown names or bad arguments — return ToolResult::failure instead.

fn resolve_streaming<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, call: ToolCall, ctx: &'life1 ToolContext, progress: &'life2 mut dyn ToolProgress, ) -> Pin<Box<dyn Future<Output = ToolResult> + Send + 'async_trait>>

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

Resolve with progress: an implementation running something long — a shell command — reports human-facing output chunks (complete lines) as they land, so a sink can render them live; the full text still arrives in the returned result. The default ignores progress and resolves as usual.

fn replay_safety(&self, _name: &str) -> ReplaySafety

The replay safety of one offered tool (see ReplaySafety), consulted when a crash left a committed call without its result. Defaults to ReplaySafety::Unsafe: a resolver that does not classify its tools is treated as entirely side-effecting.