Struct ShellExecutor 

pub struct ShellExecutor { /* private fields */ }

Bash block extraction and execution via tokio::process::Command.

Parses ```bash fenced blocks from LLM responses (legacy path) and handles structured bash tool calls (modern path). Use ShellExecutor::new with a ShellConfig and chain optional builder methods to attach audit logging, event streaming, permission policies, and cancellation.

Example

use zeph_tools::{ShellExecutor, ToolExecutor, ShellConfig};

let executor = ShellExecutor::new(&ShellConfig::default());

// Execute a fenced bash block.
let response = "```bash\npwd\n```";
if let Ok(Some(output)) = executor.execute(response).await {
    println!("{}", output.summary);
}

Implementations

impl ShellExecutor

pub fn new(config: &ShellConfig) -> Self

Create a new ShellExecutor from configuration.

Merges the built-in DEFAULT_BLOCKED_COMMANDS with any additional blocked commands from config, then subtracts any explicitly allowed commands. No subprocess is spawned at construction time.

pub fn with_sandbox( self, sandbox: Arc<dyn Sandbox>, policy: SandboxPolicy, ) -> Self

Attach an OS-level sandbox backend and a pre-snapshotted policy.

The policy is snapshotted at construction and never re-resolved per call (no TOCTOU). If a different policy is needed, create a new ShellExecutor via the builder chain.

pub fn with_risk_chain(self, accumulator: Arc<RiskChainAccumulator>) -> Self

Attach a per-turn risk chain accumulator for multi-step attack detection.

When set, each command is recorded into the accumulator. If the cumulative risk score exceeds threshold, the command is blocked before execution.

pub fn with_execution_config( self, config: &ExecutionConfig, ) -> Result<Self, String>

Build the environment registry from [execution] config and wire it in one step.

Convenience wrapper for agent startup. Converts zeph_config::ExecutionConfig entries into trusted ExecutionContext instances and passes them to Self::with_environments.

Errors

Returns an error string when any registry entry’s cwd cannot be canonicalized or escapes allowed_paths.

pub fn with_environments( self, environments: HashMap<String, ExecutionContext>, default_env: Option<String>, ) -> Result<Self, String>

Wire the named execution environment registry from [execution] config.

Builds trusted ExecutionContext instances from the operator-authored TOML entries and canonicalizes their cwd paths at construction time.

Errors

Returns an error string (surfaced at agent startup) when a registry entry’s cwd path does not exist, cannot be canonicalized, or escapes allowed_paths.

pub fn set_skill_env(&self, env: Option<HashMap<String, String>>)

Set environment variables to inject when executing the active skill’s bash blocks.

pub fn with_audit(self, logger: Arc<AuditLogger>) -> Self

Attach an audit logger. Each shell invocation will emit an AuditEntry.

pub fn with_tool_event_tx(self, tx: ToolEventTx) -> Self

Attach a tool-event sender for streaming output to the TUI or channel adapter.

When set, ToolEvent::Started, ToolEvent::OutputChunk, and ToolEvent::Completed events are sent on tx during execution.

pub fn with_background_completion_tx( self, tx: Sender<BackgroundCompletion>, ) -> Self

Attach a dedicated sender for routing BackgroundCompletion payloads to the agent.

This channel is separate from ToolEventTx (which goes to the TUI). The agent holds the receiver end and drains it at the start of each turn to inject deferred completions into the message history as a single merged user-role block.

pub fn with_task_supervisor(self, supervisor: TaskSupervisor) -> Self

Attach a TaskSupervisor so background shell run tasks are registered and observable.

When set, each spawn_background_with_context call registers the run task under its RunId in the supervisor, making it visible to TUI status panels and gracefully aborted on supervisor shutdown.

pub fn with_permissions(self, policy: PermissionPolicy) -> Self

Attach a permission policy for confirmation-gate enforcement.

Commands matching the policy’s rules may require user approval before execution proceeds.

pub fn with_cancel_token(self, token: CancellationToken) -> Self

Attach a cancellation token. When the token is cancelled, the running subprocess is killed and the executor returns ToolError::Cancelled.

pub fn with_output_filters(self, registry: OutputFilterRegistry) -> Self

Attach an output filter registry. Filters are applied to stdout+stderr before the summary is stored in ToolOutput and sent to the LLM.

pub fn background_runs_snapshot(&self) -> Vec<BackgroundRunSnapshot>

Snapshot all in-flight background runs.

Acquires the lock once, maps each BackgroundHandle to a BackgroundRunSnapshot, then drops the guard before returning. Safe to call from any thread.

pub fn policy_handle(&self) -> ShellPolicyHandle

Return a clonable handle for live policy rebuilds on hot-reload.

Clone the handle out at construction time and store it on the agent. Calling ShellPolicyHandle::rebuild atomically swaps the effective blocked_commands without recreating the executor.

pub async fn execute_confirmed( &self, response: &str, ) -> Result<Option<ToolOutput>, ToolError>

Execute a bash block bypassing the confirmation check (called after user confirms).

Errors

Returns ToolError on blocked commands, sandbox violations, or execution failures.

impl ShellExecutor

pub async fn shutdown(&self)

Cancel all in-flight background runs.

Called during agent shutdown. On Unix, issues SIGTERM/SIGKILL escalation against each captured process ID before cancelling the token. Each cancelled run emits a ToolEvent::Completed { success: false } event.

Trait Implementations

impl Debug for ShellExecutor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ToolExecutor for ShellExecutor

async fn execute(&self, response: &str) -> Result<Option<ToolOutput>, ToolError>

Parse response for fenced tool blocks and execute them.

async fn execute_confirmed( &self, response: &str, ) -> Result<Option<ToolOutput>, ToolError>

Execute bypassing confirmation checks (called after user approves).

fn tool_definitions(&self) -> Vec<ToolDef>

Return the tool definitions this executor can handle.

async fn execute_tool_call( &self, call: &ToolCall, ) -> Result<Option<ToolOutput>, ToolError>

Execute a structured tool call. Returns Ok(None) if call.tool_id is not handled.

fn set_skill_env(&self, env: Option<HashMap<String, String>>)

Inject environment variables for the currently active skill. No-op by default.

fn checkpoint_undo(&self, n: usize) -> CheckpointActionResult

Undo the last n checkpointed write commands.

fn checkpoint_redo(&self) -> CheckpointActionResult

Redo the last undone checkpoint.

fn checkpoint_list(&self) -> CheckpointListResult

List the current undo stack entries and redo depth.

fn requires_confirmation(&self, _call: &ToolCall) -> bool

Return true when call would require user confirmation before execution.

async fn execute_tool_call_confirmed( &self, call: &ToolCall, ) -> Result<Option<ToolOutput>, ToolError>

Execute a structured tool call bypassing confirmation checks.

fn is_tool_speculatable(&self, _tool_id: &str) -> bool

Whether a tool call can be safely dispatched speculatively (before the LLM finishes).

fn set_effective_trust(&self, _level: SkillTrustLevel)

Set the effective trust level for the currently active skill. No-op by default.

fn is_tool_retryable(&self, _tool_id: &str) -> bool

Whether the executor can safely retry this tool call on a transient error.