<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8.8-tool-composition -->

# Tool Composition

- src/tools/binary_plugin.rs
- src/tools/cron.rs
- src/tools/custom.rs
- src/tools/delegate.rs
- src/tools/gsheets.rs
- src/tools/mcp/wrapper.rs
- src/tools/memory.rs
- src/tools/plugin.rs
- src/tools/registry.rs
- src/tools/spawn.rs
- src/tools/types.rs
- src/tools/whatsapp.rs

## Purpose and Scope

This page documents the **Tool Composition** system, which enables LLMs to create new tools at runtime using natural language descriptions and shell command templates. The system provides a meta-programming capability where the agent can define, store, and execute custom tools without manual code deployment. It specifically covers the `CreateToolTool` for dynamic generation and the `CustomTool` adapter for shell-based composition.

For information about built-in tools, see [8.2. Built-in Tools Reference](https://github.com/qhkm/zeptoclaw/blob/2c743d31/8.2. Built-in Tools Reference) For binary plugins and MCP tools, see [8.6. Binary Plugin System](https://github.com/qhkm/zeptoclaw/blob/2c743d31/8.6. Binary Plugin System) and [8.7. MCP Integration](https://github.com/qhkm/zeptoclaw/blob/2c743d31/8.7. MCP Integration)

## Overview

Tool Composition allows the LLM to create tools dynamically during a conversation. The system converts these descriptions into executable shell commands or instruction sets that are persisted to disk and automatically loaded in future agent sessions.

**Key Components:**

Sources: [src/tools/custom.rs110-113](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L113) [src/tools/registry.rs48-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L50)

## Tool Composition Architecture

The system bridges **Natural Language Space** (LLM requests) to **Code Entity Space** (Shell execution and Tool traits).

### System Mapping

```

```

Sources: [src/tools/custom.rs110-113](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L113) [src/tools/registry.rs172-181](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L172-L181)

## CreateToolTool: The Meta-Tool

`CreateToolTool` is a specialized tool that allows the agent to modify its own capabilities. It manages the lifecycle of composed tools through primary actions.

### Actions and Parameters

The tool uses a standard JSON schema to define its interface to the LLM.

### Validation and Security

When `create` is called, the system validates the tool definition. The resulting command template is subjected to `ShellSecurityConfig` checks during execution to prevent unauthorized binary usage or dangerous shell metacharacters [src/tools/custom.rs201-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L201-L206)

Sources: [src/tools/custom.rs201-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L201-L206)

## Template Interpolation

The `CustomTool` implementation uses a double-mustache `{{key}}` syntax for parameter interpolation. This allows LLMs to define generic commands that accept specific runtime arguments.

### Interpolation Logic

The `interpolate` function in `src/tools/custom.rs` performs the following:

1. Iterates through the provided HashMap<String, String> of arguments src/tools/custom.rs 93-94
2. Identifies if a parameter is marked as raw_string in the CustomToolDef src/tools/custom.rs 95-98
3. Raw Strings : Uses sanitize_raw_string to strip dangerous metacharacters while allowing word-splitting for CLI flags src/tools/custom.rs 99-100 src/tools/custom.rs 40-77
4. Standard Strings : Wraps values in single quotes using shell_escape to prevent command injection src/tools/custom.rs 101-102 src/tools/custom.rs 26-28
5. Replaces {{key}} with the processed value src/tools/custom.rs 104

### Example Execution Flow

```

```

Sources: [src/tools/custom.rs18-28](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L18-L28) [src/tools/custom.rs87-107](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L87-L107) [src/tools/custom.rs201-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L201-L206)

## Persistence and Storage

Composed tools are managed by the `ComposedToolStore`. This component ensures that tools created during a session are available after a restart.

### Data Flow

1. Creation : CreateToolTool receives a definition, creates a CustomToolDef , and passes it to the store.
2. Persistence : The store serializes the definition to ~/.zeptoclaw/composed_tools.json .
3. Registration : At startup, the ToolRegistry is populated with these tools. The Tool trait's parameters() method automatically converts the CustomToolDef parameter map into a JSON Schema for the LLM src/tools/custom.rs 148-175

Sources: [src/tools/custom.rs148-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L148-L175)

## Implementation Details

### CustomTool Execution

The `CustomTool::execute` function handles the low-level process spawning:

- Output Limit : Output is capped at MAX_OUTPUT_BYTES (50,000 bytes) to prevent LLM context overflow src/tools/custom.rs 19
- Timeout : Defaults to 30 seconds, clamped to a minimum of 1 second ( MIN_TIMEOUT_SECS ) src/tools/custom.rs 22 src/tools/custom.rs 211-212
- Working Directory : If the tool context provides a workspace, the command is executed within that directory src/tools/custom.rs 159-162 src/tools/custom.rs 222-224
- Shell Execution : Commands are executed via sh -c src/tools/custom.rs 4

### Tool Category

All composed tools created via `CreateToolTool` are assigned the `ToolCategory::Shell` category [src/tools/custom.rs144-146](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L144-L146) This ensures they are governed by the same security policies and agent mode permissions as the standard `shell` tool.

### Specialized Composition Adapters

While `CustomTool` is the primary target for LLM-generated tools, other adapters exist for structured composition:

- BinaryPluginTool : Adapts external binaries using JSON-RPC 2.0 src/tools/binary_plugin.rs 68-73
- McpToolWrapper : Adapts Model Context Protocol tools to the internal Tool trait src/tools/mcp/wrapper.rs 10-21
- PluginTool : Wraps plugin manifest definitions for shell execution src/tools/plugin.rs 68-75

Sources: [src/tools/custom.rs4](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L4-L4) [src/tools/custom.rs19-22](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L19-L22) [src/tools/custom.rs144-146](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L144-L146) [src/tools/custom.rs159-162](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L159-L162) [src/tools/custom.rs211-212](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L211-L212) [src/tools/custom.rs222-224](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L222-L224) [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/plugin.rs68-75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/plugin.rs#L68-L75)
