Tool System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                          IronClaw Tool System                                │
│                                                                              │
│   Built-in Tools ──────▶ Core functionality (HTTP, shell, files, memory)   │
│   (Rust native)                                                              │
│                                                                              │
│   WASM Tools ──────────▶ Sandboxed extensions with capability control       │
│   (Sandboxed)           • Fuel metering   • Memory limits                   │
│                         • Allowlists      • Credential injection             │
│                                                                              │
│   MCP Servers ─────────▶ External tool providers via JSON-RPC               │
│   (External process)    • Pre-built servers  • Any language                 │
└─────────────────────────────────────────────────────────────────────────────┘

#[async_trait]
pub trait Tool: Send + Sync {
    /// Get the tool name.
    fn name(&self) -> &str;

    /// Get a description of what the tool does.
    fn description(&self) -> &str;

    /// Get the JSON Schema for the tool's parameters.
    fn parameters_schema(&self) -> serde_json::Value;

    /// Execute the tool with the given parameters.
    async fn execute(
        &self,
        params: serde_json::Value,
        ctx: &JobContext,
    ) -> Result<ToolOutput, ToolError>;

    /// Whether this tool requires user approval.
    fn requires_approval(&self, _params: &serde_json::Value) -> ApprovalRequirement {
        ApprovalRequirement::Never
    }

    /// Where this tool should execute (Orchestrator or Container).
    fn domain(&self) -> ToolDomain {
        ToolDomain::Orchestrator
    }

    /// Per-invocation rate limit configuration.
    fn rate_limit_config(&self) -> Option<ToolRateLimitConfig> {
        None
    }
}

pub struct ToolRegistry {
    tools: RwLock<HashMap<String, Arc<dyn Tool>>>,
    builtin_names: RwLock<HashSet<String>>,
    credential_registry: Option<Arc<SharedCredentialRegistry>>,
    secrets_store: Option<Arc<dyn SecretsStore>>,
    rate_limiter: RateLimiter,
}

// Register built-in tools (echo, time, json, http, web_fetch)
registry.register_builtin_tools();

// Register container tools (shell, file operations)
registry.register_container_tools();

// Register memory tools (requires workspace)
registry.register_memory_tools(workspace);

// Register job management tools
registry.register_job_tools(context_manager, scheduler, ...);

// Register WASM tool from bytes
registry.register_wasm(WasmToolRegistration {
    name: "my_tool",
    wasm_bytes: &bytes,
    runtime: &runtime,
    capabilities: caps,
    ..Default::default()
}).await?;

const PROTECTED_TOOL_NAMES: &[&str] = &[
    "echo", "time", "json", "http", "shell",
    "read_file", "write_file", "list_dir", "apply_patch",
    "memory_search", "memory_write", "memory_read", "memory_tree",
    "create_job", "list_jobs", "job_status", "cancel_job",
    "build_software", "tool_search", "tool_install", "tool_auth",
    "web_fetch", "message", ...
];

pub enum ApprovalRequirement {
    Never,                    // No approval needed
    UnlessAutoApproved,       // Needs approval unless session auto-approve enabled
    Always,                   // Always requires explicit approval
}

fn requires_approval(&self, params: &serde_json::Value) -> ApprovalRequirement {
    let command = params.get("command")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    
    if is_destructive(command) {
        ApprovalRequirement::Always
    } else {
        ApprovalRequirement::UnlessAutoApproved
    }
}

pub struct ToolRateLimitConfig {
    pub requests_per_minute: u32,
    pub requests_per_hour: u32,
}

impl Default for ToolRateLimitConfig {
    fn default() -> Self {
        Self {
            requests_per_minute: 60,
            requests_per_hour: 1000,
        }
    }
}

pub struct ToolOutput {
    pub result: serde_json::Value,
    pub cost: Option<Decimal>,
    pub duration: Duration,
    pub raw: Option<String>,
}

impl ToolOutput {
    pub fn success(result: serde_json::Value, duration: Duration) -> Self;
    pub fn text(text: impl Into<String>, duration: Duration) -> Self;
    pub fn with_cost(mut self, cost: Decimal) -> Self;
    pub fn with_raw(mut self, raw: impl Into<String>) -> Self;
}

pub fn validate_tool_schema(schema: &serde_json::Value, path: &str) -> Vec<String>