Trait RustTool 

pub trait RustTool: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> Value;
    fn required_capability(&self) -> Capability;
    fn is_read_only(&self) -> bool;
    fn execute(
        &self,
        args: Value,
        ctx: &ToolContext<'_>,
    ) -> Result<Value, ToolError>;

    // Provided method
    fn intent_def(&self) -> IntentDef { ... }
}

A self-describing, sandboxed tool that integrates with IntentRegistry.

Each implementor defines:

• Identity: name + description + parameter schema (for LLM tools array)
• Permission: required capability + read-only flag (for dispatcher)
• Logic: execute function (sandboxed, capability pre-checked)

Pre-conditions for execute()

The dispatcher guarantees these before calling execute():

1. required_capability() is granted to the caller
2. Mutation approval obtained (for non-is_read_only() tools)

Tools should NOT re-check capabilities. They may use ctx.sandbox() for path validation and ctx.child_ctx() for command-level permission checks (e.g., exec).

Required Methods

fn name(&self) -> &str

Unique tool name (e.g., “read”, “write”, “grep”).

Must be unique within the IntentRegistry.

fn description(&self) -> &str

Human-readable description (sent to LLM as tool description).

fn parameters_schema(&self) -> Value

JSON Schema for parameters (sent to LLM as tool parameters).

Must be a valid JSON Schema object with "type": "object".

fn required_capability(&self) -> Capability

Required capability for execution.

The dispatcher checks this BEFORE calling execute().

fn is_read_only(&self) -> bool

Whether this tool is read-only.

Read-only tools are exempt from mutation approval (HIL gate). Examples: read, grep, glob.

fn execute( &self, args: Value, ctx: &ToolContext<'_>, ) -> Result<Value, ToolError>

Execute the tool with the given arguments.

Arguments

• args — JSON object matching parameters_schema()
• ctx — Execution context with sandbox and optional child context

Returns

JSON value representing the tool output (structure is tool-specific).

Provided Methods

fn intent_def(&self) -> IntentDef

Generate an IntentDef for this tool.

Used by IntentRegistry to register the tool and expose it to LLM tool_calls.

Default implementation uses name(), description(), and parameters_schema() with IntentResolver::Internal.

Implementors