Struct ShellExecTool 

pub struct ShellExecTool { /* private fields */ }

A tool that executes shell commands as subprocesses.

ShellExecTool implements the Tool trait and is registered under the name shell.exec. When invoked it spawns the requested executable, waits for it to finish (respecting an optional timeout and turn cancellation), and returns a structured JSON object with stdout, stderr, success, and exit_code fields.

Before execution the tool emits a ShellPermissionRequest so that permission policies (e.g. CommandPolicy) can allow, deny, or require approval for the command.

Input schema

Field	Type	Required	Description
executable	string	yes	Program to run.
argv	[string]	no	Arguments passed to the executable.
cwd	string	no	Working directory for the subprocess.
env	{string:string}	no	Extra environment variables.
timeout_ms	integer	no	Maximum wall-clock time in milliseconds.

Example

use agentkit_tool_shell::ShellExecTool;
use agentkit_tools_core::ToolRegistry;

let mut reg = ToolRegistry::new();
reg.register(ShellExecTool::default());

let spec = &reg.specs()[0];
assert_eq!(spec.name.0, "shell.exec");
assert!(spec.annotations.destructive_hint);

Trait Implementations

impl Clone for ShellExecTool

fn clone(&self) -> ShellExecTool

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ShellExecTool

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

Formats the value using the given formatter.

impl Default for ShellExecTool

fn default() -> Self

Returns the “default value” for a type.

impl Tool for ShellExecTool

fn spec(&self) -> &ToolSpec

Returns the ToolSpec describing the shell.exec tool.

fn proposed_requests( &self, request: &ToolRequest, ) -> Result<Vec<Box<dyn PermissionRequest>>, ToolError>

Extracts a ShellPermissionRequest from the incoming ToolRequest.

The returned request is evaluated by the active PermissionChecker before invoke runs, giving policies such as CommandPolicy a chance to allow or deny the command.

Errors

Returns ToolError::InvalidInput if the request input cannot be deserialized into the expected schema.

fn invoke<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, request: ToolRequest, ctx: &'life1 mut ToolContext<'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,

Spawns the requested command and returns its output.

The subprocess is spawned with kill_on_drop(true) so it is cleaned up if the future is cancelled. When a timeout_ms is specified in the input the command is aborted after that duration. If a turn cancellation token is present in the ToolContext the command is also aborted when the turn is cancelled.

On success the returned ToolResult contains a JSON object:

{
  "stdout": "...",
  "stderr": "...",
  "success": true,
  "exit_code": 0
}

Errors

• ToolError::InvalidInput – the request input does not match the schema.
• ToolError::ExecutionFailed – the command could not be spawned or timed out.
• ToolError::Cancelled – the turn was cancelled while the command was running.

fn current_spec(&self) -> Option<ToolSpec>

Returns the current specification for this tool, if it should be advertised right now.