Module tool 

RustTool trait for self-describing, sandboxed tool plugins.

A RustTool is a unit of functionality that:

• Declares its identity (name, description, parameter schema)
• Declares its permission requirement (capability, read-only flag)
• Executes sandboxed logic given validated arguments

Dispatch Flow

orcs.dispatch("read", {path: "src/main.rs"})
  → IntentRegistry lookup → RustTool found
  → capability check (READ) ✓
  → approval check (read_only=true → exempt) ✓
  → tool.execute(args, &ctx)
  → Result<Value, ToolError>

Adding a New Tool

use orcs_component::{RustTool, ToolContext, ToolError, Capability};
use serde_json::{json, Value};

struct CountLinesTool;

impl RustTool for CountLinesTool {
    fn name(&self) -> &str { "count_lines" }

    fn description(&self) -> &str {
        "Count the number of lines in a file"
    }

    fn parameters_schema(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "path": { "type": "string", "description": "File path" }
            },
            "required": ["path"]
        })
    }

    fn required_capability(&self) -> Capability { Capability::READ }
    fn is_read_only(&self) -> bool { true }

    fn execute(&self, args: Value, ctx: &ToolContext<'_>) -> Result<Value, ToolError> {
        let path = args["path"].as_str()
            .ok_or_else(|| ToolError::new("missing 'path' argument"))?;
        let canonical = ctx.sandbox()
            .validate_read(path)
            .map_err(|e| ToolError::new(e.to_string()))?;
        let content = std::fs::read_to_string(&canonical)
            .map_err(|e| ToolError::new(e.to_string()))?;
        Ok(json!({ "lines": content.lines().count() }))
    }
}

Structs

ToolContext

Execution context provided to RustTool::execute.

ToolError

Error from tool execution.

Traits

RustTool

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