<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8.1-tool-system-overview -->

# Tool System Overview

- src/cli/common.rs
- src/lib.rs
- src/tools/binary_plugin.rs
- src/tools/custom.rs
- src/tools/delegate.rs
- src/tools/find.rs
- src/tools/grep.rs
- src/tools/mcp/wrapper.rs
- src/tools/mod.rs
- src/tools/output.rs
- src/tools/plugin.rs
- src/tools/registry.rs
- src/tools/types.rs
- tests/conformance/fixtures/.gitkeep
- tests/conformance/fixtures/edit_tool.json
- tests/conformance/fixtures/find_tool.json

The ZeptoClaw tool system enables LLMs to perform actions beyond text generation by executing structured function calls. This system is built around the `Tool` trait, managed by a `ToolRegistry`, and executed through a pipeline that integrates security scanning, hooks, and multi-runtime isolation.

## Core Abstractions

### Tool Trait

The `Tool` trait is the fundamental interface for all executable actions in ZeptoClaw. It is defined as `Send + Sync` to support concurrent execution within the Agent Loop.

**Tool Trait Interface**

```

```

**Sources:** [src/tools/types.rs197-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L197-L210) [src/tools/types.rs18-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L18-L39)

The trait requires several key methods:

- name() : Unique identifier (e.g., "shell" , "read_file" ) src/tools/types.rs 202
- category() : Returns a ToolCategory used for security policies src/tools/types.rs 218
- parameters() : Returns a JSON Schema defining the expected input src/tools/types.rs 222
- execute() : The async core logic returning a ToolOutput src/tools/types.rs 224

### ToolOutput

ZeptoClaw uses a "dual-audience" result pattern to separate what the AI sees from what the user sees.

- for_llm : The raw data or confirmation for the model src/tools/types.rs 81
- for_user : An optional friendly summary or status for the human user src/tools/types.rs 83
- pause_for_input : If true, the loop breaks to wait for user response src/tools/types.rs 91

**Sources:** [src/tools/types.rs79-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L79-L92)

### ToolContext

`ToolContext` provides environmental metadata to tools during execution.

- Workspace : The root directory for file operations src/tools/types.rs 242
- Channel/Chat ID : Routing info for tools that send messages src/tools/types.rs 244-246
- Is Batch : Flag for non-interactive execution src/tools/types.rs 248

**Sources:** [src/tools/types.rs240-250](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L240-L250)

## Tool Registry and Management

The `ToolRegistry` acts as the central management point for an agent's capabilities. It stores tools in a `HashMap<String, Box<dyn Tool>>` [src/tools/registry.rs49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L49-L49)

**Tool Management Logic**

```

```

**Sources:** [src/tools/registry.rs48-235](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L235)

### Tool Execution Flow

When `execute_with_context` is called, the registry performs a lookup. If the tool is not found, it provides an `opt_in_tool_hint` for common coding tools like `grep` or `find` [src/tools/registry.rs18-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L18-L25) Successful execution logs the duration and result [src/tools/registry.rs183-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L183-L203)

## Execution Pipeline and Security

When an agent calls a tool, it flows through a structured pipeline that ensures safety, specifically through taint tracking and shell validation.

**Data Flow and Security Checks**

```

```

**Sources:** [src/safety/taint.rs154-176](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/taint.rs#L154-L176) [src/tools/custom.rs201-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L201-L206)

### Output Truncation

To prevent context window exhaustion, tools that produce large volumes of data (like `grep` or `shell`) use `truncate_tool_output` [src/tools/output.rs42-95](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/output.rs#L42-L95)

- Limits : Defaults to 2,000 lines or 50,000 bytes src/tools/output.rs 8-11
- Behavior : Appends a trailer indicating how many lines/bytes were omitted src/tools/output.rs 56-59

**Sources:** [src/tools/output.rs1-95](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/output.rs#L1-L95) [src/tools/grep.rs161-165](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/grep.rs#L161-L165)

## Extension Mechanisms

ZeptoClaw supports several methods for extending tool capabilities:

### 1. Custom Shell Tools

Defined in `config.json`, these wrap shell commands with parameter interpolation using `{{key}}` syntax [src/tools/custom.rs87-107](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L87-L107) They use `sanitize_raw_string` for `raw_string` parameters to prevent injection while allowing word-splitting [src/tools/custom.rs40-77](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L40-L77)

### 2. Binary Plugins

`BinaryPluginTool` executes standalone binaries using JSON-RPC 2.0 over stdin/stdout [src/tools/binary_plugin.rs3-6](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L3-L6) It spawns the binary on-demand, writes the request, and reads the response [src/tools/binary_plugin.rs61-68](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L61-L68)

### 3. MCP (Model Context Protocol)

`McpToolWrapper` adapts tools from local or remote MCP servers [src/tools/mcp/wrapper.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/wrapper.rs#L1-L10) Tool names are automatically prefixed with the server name (e.g., `server_toolname`) to avoid collisions [src/tools/mcp/wrapper.rs26-35](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/wrapper.rs#L26-L35)

### 4. Delegation and Swarms

`DelegateTool` allows an agent to spawn a specialist sub-agent [src/tools/delegate.rs32-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L32-L44)

- Recursion Guard : Sub-agents are prevented from delegating further src/tools/delegate.rs 108-109
- Scratchpad : Uses a SwarmScratchpad to pass context between agents in a session src/tools/delegate.rs 51-52

**Sources:** [src/tools/custom.rs110-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L128) [src/tools/binary_plugin.rs68-73](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L68-L73) [src/tools/mcp/wrapper.rs10-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mcp/wrapper.rs#L10-L21) [src/tools/delegate.rs1-152](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L1-L152)

## Built-in Tool Reference

The system includes 32+ core tools, including:

- Grep : High-performance regex search using system grep -rn src/tools/grep.rs 14-16
- Filesystem : Tools for reading, writing, listing, and editing files src/tools/mod.rs 18-21
- Memory : Search and retrieval from workspace and long-term memory src/tools/mod.rs 28-29

**Sources:** [src/tools/grep.rs1-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/grep.rs#L1-L166) [src/tools/mod.rs1-143](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L143)
