<!-- source: https://deepwiki.com/qhkm/zeptoclaw/3.4-tool-system-architecture -->

# Tool System Architecture

- src/cli/common.rs
- src/cli/tools.rs
- src/kernel/mod.rs
- src/kernel/registrar.rs
- src/lib.rs
- src/safety/taint.rs
- src/tools/binary_plugin.rs
- src/tools/browser.rs
- src/tools/custom.rs
- src/tools/delegate.rs
- src/tools/mcp/wrapper.rs
- src/tools/mod.rs
- src/tools/plugin.rs
- src/tools/registry.rs
- src/tools/types.rs

This page documents ZeptoClaw's tool system architecture, which enables LLM function calling through a unified `Tool` trait abstraction. The system manages tool discovery, registration, filtering, execution, and integration with the runtime isolation layer.

For information about runtime isolation (Native/Docker/Apple Container backends), see **3.6 Runtime Isolation**. For details on the agent processing loop that invokes tools, see **3.2 Agent Loop**.

## Overview

The tool system is centered around four core abstractions:

- Tool trait : Async interface that all tools must implement src/tools/types.rs 197-208
- ToolContext : Execution context containing channel, chat_id, workspace, and session metadata src/tools/types.rs 1-5
- ToolOutput : Dual-audience result structure with separate content for LLM and user src/tools/types.rs 79-92
- ToolRegistry : Central registry for tool management, definition generation, and execution dispatch src/tools/registry.rs 48-50

Tools come from five distinct sources: built-in tools (32+), custom tools defined in config, binary plugins, command-mode plugins, and MCP server integration. All tool execution converges through `kernel::gate::execute_tool()` for unified safety scanning, taint tracking, and metrics recording.

Sources: [src/tools/mod.rs1-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L1-L140) [src/lib.rs94-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L94-L100) [src/tools/registry.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L1-L5) [src/kernel/mod.rs10-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/mod.rs#L10-L12)

## Tool Trait

The `Tool` trait defines the interface that all tools must implement. It is an async trait with four required methods and a category classification:

```

```

**Tool Trait Methods**

### ToolCategory

The `ToolCategory` enum classifies tools for agent mode permission enforcement [src/tools/types.rs20-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L20-L39):

Sources: [src/tools/types.rs18-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L18-L39) [src/tools/mod.rs135](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L135-L135) [src/tools/mod.rs15-33](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L15-L33)

## ToolContext and ToolOutput

### ToolContext

The `ToolContext` struct provides execution context to tools, containing metadata about the current request:

```

```

Tools use this context to access workspace paths for filesystem operations [src/tools/binary_plugin.rs159-162](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L159-L162) and determine the originating channel for response routing in proactive messaging [src/tools/delegate.rs119-120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L119-L120)

### ToolOutput

The `ToolOutput` struct provides dual-audience results from tool execution [src/tools/types.rs79-92](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L79-L92):

```

```

Constructor methods include `llm_only(content)` [src/tools/types.rs96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L96-L96) `user_visible(content)` [src/tools/types.rs107](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L107-L107) and `split(for_llm, for_user)` [src/tools/types.rs145](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L145-L145) The `with_pause()` method is used by tools like `AskClarificationTool` to stop the agent loop [src/tools/types.rs159-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L159-L163)

Sources: [src/tools/types.rs74-163](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L74-L163) [src/tools/mod.rs109](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L109-L109)

## ToolRegistry

The `ToolRegistry` maintains all registered 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)

**ToolRegistry Architecture**

```

```

Sources: [src/tools/registry.rs48-230](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L230) [src/kernel/registrar.rs179-181](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/registrar.rs#L179-L181) [src/kernel/mod.rs10-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/mod.rs#L10-L12)

## Tool Discovery and Filtering

Tool registration passes through a multi-dimensional filter implemented in `ToolFilter` [src/kernel/registrar.rs54-64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/registrar.rs#L54-L64):

1. denied : Startup guard/degraded mode blocklist from config.tools.deny src/kernel/registrar.rs 122-127
2. profile : Tool sets from config.tool_profiles src/kernel/registrar.rs 112-120
3. allowed : Intersection of template allowed_tools and hand required_tools src/kernel/registrar.rs 79-100
4. blocked : Template blocked_tools explicit deny list src/kernel/registrar.rs 102-110

**Tool Filtering Pipeline**

```

```

Sources: [src/kernel/registrar.rs54-182](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/registrar.rs#L54-L182)

## Execution Pipeline and Taint Tracking

All tool executions route through the `kernel::gate` to ensure consistent application of safety policies and data-flow tracking.

- Taint Tracking : The TaintEngine labels outputs based on provenance (e.g., ExternalNetwork for web tools) and blocks tainted content from reaching sensitive sinks like shell_execute src/safety/taint.rs 1-15
- Sink Rules : Built-in rules block ExternalNetwork and Secret labels from flowing into shell_execute to prevent injection attacks like curl | sh src/safety/taint.rs 155-160

Sources: [src/kernel/mod.rs10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/mod.rs#L10-L10) [src/safety/taint.rs154-176](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/taint.rs#L154-L176)

## Extension Mechanisms

### Binary Plugins

The `BinaryPluginTool` executes standalone binaries via JSON-RPC 2.0 over stdin/stdout [src/tools/binary_plugin.rs1-6](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L1-L6) The binary is spawned on-demand for each call, receiving a request and returning a single response before exiting [src/tools/binary_plugin.rs63-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L63-L67)

### Custom Tools

`CustomTool` allows users to define shell-based tools in `config.json` [src/tools/custom.rs1-4](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L1-L4)

- Interpolation : Placeholders like {{key}} are replaced with shell-escaped values src/tools/custom.rs 87-107
- Security : Commands are validated against ShellSecurityConfig blocklists src/tools/custom.rs 201-206
- Raw Strings : Parameters typed as raw_string are sanitized but not escaped, allowing word-splitting for CLI flags src/tools/custom.rs 30-40

### Agent Delegation

The `DelegateTool` enables swarm architectures by spawning sub-agents [src/tools/delegate.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L1-L5) It creates a temporary `AgentLoop` with a role-specific system prompt and tool whitelist, preventing recursion by excluding `delegate` and `spawn` from sub-agents [src/tools/delegate.rs106-110](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L106-L110)

Sources: [src/tools/binary_plugin.rs68-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L68-L130) [src/tools/custom.rs41-198](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L41-L198) [src/tools/delegate.rs32-53](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L32-L53)

## Built-in Tools Reference

ZeptoClaw provides a comprehensive suite of built-in tools [src/tools/mod.rs15-33](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L15-L33):

- Filesystem : read_file , write_file , list_dir , edit_file , find , grep src/cli/tools.rs 26-52
- Shell/Git : shell , git src/cli/tools.rs 54-59
- Web : web_search , web_fetch , web_screenshot , browser src/cli/tools.rs 61-73 src/cli/tools.rs 159-165
- Memory : memory_search , memory_get , longterm_memory src/cli/tools.rs 75-94
- Multi-Agent : delegate , spawn src/cli/tools.rs 110-122
- Integrations : whatsapp_send , google_sheets , google (Gmail/Calendar), r8r src/cli/tools.rs 124-150

Sources: [src/cli/tools.rs17-180](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/tools.rs#L17-L180) [src/tools/mod.rs103-140](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/mod.rs#L103-L140) [src/lib.rs88-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/lib.rs#L88-L100)
