<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8-tools-and-extensions -->

# Tools and Extensions

- src/tools/binary_plugin.rs
- src/tools/custom.rs
- src/tools/delegate.rs
- src/tools/mcp/wrapper.rs
- src/tools/plugin.rs
- src/tools/registry.rs
- src/tools/types.rs

This page provides an overview of ZeptoClaw's tool system architecture and its extensibility mechanisms: built-in tools, custom shell tools, binary plugins, and MCP (Model Context Protocol) integration. Tools enable LLM agents to interact with the filesystem, execute shell commands, call external APIs, and integrate with third-party services.

**Related Pages:**

- For detailed documentation of individual built-in tools, see Built-in Tools Reference
- For creating custom tools via JSON manifests, see Custom Tools
- For dynamic tool discovery via Model Context Protocol, see MCP Integration
- For tool execution within container isolation, see Runtime Isolation
- For hardware and Android automation tools, see Android and Hardware Tools

## Tool System Architecture

ZeptoClaw's tool system is built on three core abstractions: the `Tool` trait, `ToolRegistry`, and `ToolContext`.

### Core Abstractions

The `Tool` trait defines the contract for any executable capability:

```

```

**Tool Context Structure:**
The `ToolContext` carries execution metadata that tools use for context-aware behavior, such as `workspace` for filesystem operations and `is_batch` to handle non-interactive environments [src/tools/types.rs221-231](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L221-L231)

Sources: [src/tools/types.rs79-231](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L79-L231) [src/tools/registry.rs48-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L50)

## Tool System Components Diagram

This diagram maps the high-level tool system components to their corresponding implementation entities in the codebase.

```

```

Sources: [src/tools/registry.rs48-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L50) [src/tools/types.rs197-208](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L197-L208) [src/tools/binary_plugin.rs68-73](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L68-L73) [src/tools/delegate.rs45-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L45-L53)

## Tool Sources

ZeptoClaw supports several distinct tool sources, registered via the `ToolRegistry` [src/tools/registry.rs83-87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L83-L87)

### 1. Built-in Tools (32+)

Built-in tools are compiled directly into the binary. They are categorized to support security policies [src/tools/types.rs20-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L20-L39)

Sources: [src/tools/types.rs20-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L20-L39) [src/tools/delegate.rs110-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L110-L120)

### 2. Custom & Plugin Tools

- CustomTool: Defined in config.json , these wrap shell commands with {{parameter}} interpolation src/tools/custom.rs 109-113 It supports raw_string parameters for multi-arg CLI input src/tools/custom.rs 32-40
- BinaryPluginTool: Executes standalone plugin binaries via JSON-RPC 2.0 over stdin/stdout. The binary is spawned on-demand and expected to exit after one response src/tools/binary_plugin.rs 1-6 src/tools/binary_plugin.rs 61-68
- PluginTool: An adapter for manifest-defined tools that execute shell commands via sh -c src/tools/plugin.rs 68-75

### 3. MCP Integration

The `McpClient` connects to Model Context Protocol servers to dynamically discover tools. These are adapted via `McpToolWrapper` to implement the standard `Tool` trait [src/tools/mcp/wrapper.rs9-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/wrapper.rs#L9-L21)

### 4. Specialized Swarm and Hardware Tools

- DelegateTool: Enables multi-agent swarms by creating temporary AgentLoop instances for specialist sub-agents. It uses a Semaphore to bound concurrency src/tools/delegate.rs 32-45
- Android and Hardware: Integration with ADB for mobile automation and peripheral interfaces (I2C, Serial) for hardware interaction src/tools/android/mod.rs src/tools/hardware/mod.rs

## Tool Registration and Filtering

Tool availability is gated by a multi-dimensional filtering system. The `ToolRegistry` serves as the central storage for these enabled tools [src/tools/registry.rs48-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L50)

### Registration Flow Diagram

```

```

Sources: [src/tools/registry.rs83-87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L83-L87) [src/tools/registry.rs206-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L206-L210)

## Tool Execution Pipeline

When an LLM requests a tool call, the system processes it through the following stages:

1. Registry Lookup: The ToolRegistry retrieves the tool by name src/tools/registry.rs 172-181
2. Context Injection: A ToolContext is prepared with current workspace , channel , and chat_id src/tools/types.rs 221-231
3. Execution: The tool's execute method is called with JSON arguments src/tools/types.rs 197-208
4. Output Handling: ToolOutput separates content for the LLM ( for_llm ) from content for the user ( for_user ) src/tools/types.rs 79-83
5. Pausing: Tools can set pause_for_input: true to halt the agent loop until the user responds src/tools/types.rs 159-162

### Output Sanitization

To prevent context window bloat, tool outputs are often truncated. For example, `CustomTool` captures up to 50KB from stdout [src/tools/custom.rs18-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L18-L19)

Sources: [src/tools/registry.rs166-204](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L166-L204) [src/tools/types.rs94-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L94-L163) [src/tools/custom.rs177-213](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L177-L213)

## Security and Isolation

Tool execution is governed by several security layers:

- Agent Modes: Observer , Assistant , and Autonomous modes restrict which ToolCategory can be executed without approval src/tools/types.rs 13-39
- Shell Security: ShellSecurityConfig validates commands against blocklists or allowlists before execution src/tools/custom.rs 201-206 src/tools/plugin.rs 148-153
- Runtime Isolation: Tools requiring shell access use ContainerRuntime to isolate the process src/tools/custom.rs 220-225
- Parameter Sanitization: CustomTool provides sanitize_raw_string to strip shell metacharacters from multi-argument inputs while preserving flags src/tools/custom.rs 40-77

Sources: [src/tools/types.rs13-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L13-L39) [src/tools/custom.rs110-113](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L113) [src/tools/plugin.rs72-75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/plugin.rs#L72-L75) [src/tools/custom.rs40-77](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L40-L77)
