Skip to content

08.1 Core Tools

Jump to bottom
Nikolay Vyahhi edited this page Feb 19, 2026 · 3 revisions

Core Tools

Relevant source files

The following files were used as context for generating this wiki page:

This page documents ZeroClaw's built-in core tools that provide fundamental agent capabilities. Core tools include shell execution, file operations, memory management, git operations, and cron scheduling. These tools form the foundation of the agent's ability to interact with the file system, execute commands, persist context, and schedule recurring tasks.

For browser automation and HTTP tools, see Browser and HTTP Tools. For third-party integrations and delegation, see Integration Tools. For hardware-specific tools, see Hardware Tools.

Tool Registration Architecture

ZeroClaw uses a trait-driven tool system where all tools implement the Tool trait defined in src/tools/traits.rs. Tools are registered in two tiers:

  1. Minimal tier (default_tools) - Shell, FileRead, FileWrite only
  2. Full tier (all_tools) - All core tools plus memory, git, cron, and optional integrations

The tool registry is constructed at agent initialization and passed to the agent's turn loop for execution.

Tool Registry Construction

graph TB
    subgraph "Tool Factory Functions"
        DefaultFn["default_tools()<br/>(minimal)"]
        AllFn["all_tools()<br/>(comprehensive)"]
    end
    
    subgraph "Minimal Tier (3 tools)"
        ShellTool["ShellTool"]
        FileReadTool["FileReadTool"]
        FileWriteTool["FileWriteTool"]
    end
    
    subgraph "Full Tier (17+ tools)"
        MemTools["MemoryStoreTool<br/>MemoryRecallTool<br/>MemoryForgetTool"]
        CronTools["CronAddTool<br/>CronListTool<br/>CronRemoveTool<br/>CronUpdateTool<br/>CronRunTool<br/>CronRunsTool"]
        GitTool["GitOperationsTool"]
        ConfigTools["ScheduleTool<br/>ProxyConfigTool<br/>PushoverTool"]
        VisionTools["ScreenshotTool<br/>ImageInfoTool"]
    end
    
    DefaultFn --> ShellTool
    DefaultFn --> FileReadTool
    DefaultFn --> FileWriteTool
    
    AllFn --> ShellTool
    AllFn --> FileReadTool
    AllFn --> FileWriteTool
    AllFn --> MemTools
    AllFn --> CronTools
    AllFn --> GitTool
    AllFn --> ConfigTools
    AllFn --> VisionTools
    
    ShellTool -.requires.-> RuntimeAdapter["RuntimeAdapter"]
    ShellTool -.requires.-> SecurityPolicy["SecurityPolicy"]
    FileReadTool -.requires.-> SecurityPolicy
    FileWriteTool -.requires.-> SecurityPolicy
    MemTools -.requires.-> Memory["Memory backend"]
    CronTools -.requires.-> Config["Config"]
Loading

Sources: src/tools/mod.rs:72-86, src/tools/mod.rs:89-238

Function Purpose Tool Count
default_tools() Minimal set for basic agent operation 3
all_tools() Full registry with memory, git, cron, and integrations 17+ (varies by config)

Tool Trait Interface:

All tools implement three required methods:

  • name() -> &str - Unique identifier for LLM tool calls
  • description() -> &str - Natural language description for LLM context
  • parameters_schema() -> serde_json::Value - JSON Schema for tool arguments
  • execute(args: serde_json::Value) -> anyhow::Result<ToolResult> - Async execution handler

Sources: src/tools/traits.rs

Shell Execution Tool

The ShellTool enables command execution via /bin/sh -lc with security policy enforcement. It supports both native subprocess execution and Docker sandbox isolation.

Shell Tool Architecture

graph TB
    LLM["LLM generates<br/>tool call"] --> ShellTool["ShellTool::execute()"]
    
    ShellTool --> SecurityCheck{"SecurityPolicy<br/>checks"}
    
    SecurityCheck -->|can_act?| ActionCheck["Verify autonomy level"]
    SecurityCheck -->|is_command_allowed?| CommandCheck["Check allowed_commands"]
    SecurityCheck -->|is_rate_limited?| RateCheck["Check action budget"]
    SecurityCheck -->|record_action?| RecordAction["Decrement budget"]
    
    ActionCheck -->|denied| ErrorResult["ToolResult{success: false}"]
    CommandCheck -->|denied| ErrorResult
    RateCheck -->|denied| ErrorResult
    RecordAction -->|denied| ErrorResult
    
    ActionCheck -->|approved| RuntimeSwitch{"RuntimeAdapter<br/>type"}
    CommandCheck -->|approved| RuntimeSwitch
    RateCheck -->|approved| RuntimeSwitch
    RecordAction -->|approved| RuntimeSwitch
    
    RuntimeSwitch -->|native| NativeExec["NativeRuntime<br/>tokio::process::Command"]
    RuntimeSwitch -->|docker| DockerExec["DockerRuntime<br/>docker run --rm"]
    
    NativeExec --> ShOutput["stdout/stderr<br/>+ exit code"]
    DockerExec --> ShOutput
    
    ShOutput --> SuccessResult["ToolResult{success: true/false}"]
Loading

Sources: src/tools/shell.rs, src/runtime/native.rs, src/runtime/docker.rs

Security Enforcement

The shell tool enforces four security layers before execution:

  1. Autonomy Level - ReadOnly mode blocks all shell commands
  2. Command Allowlist - allowed_commands config restricts executable binaries
  3. Rate Limiting - max_actions_per_hour prevents runaway execution
  4. Action Recording - Each execution decrements the action budget

Example SecurityPolicy Configuration:

Field Purpose Default
autonomy.level ReadOnly/Supervised/Full Supervised
autonomy.allowed_commands Binary allowlist (e.g., ["ls", "cat", "git"]) ["*"] (all allowed)
autonomy.max_actions_per_hour Rate limit per hour 100

Sources: src/tools/shell.rs, src/security/policy.rs

File Operations

File tools provide read/write access with path security enforcement. Both tools validate paths against:

  • workspace_only flag (restricts access to workspace directory)
  • Forbidden system directories (/etc, /sys, /proc, etc.)
  • Symlink escape detection

FileReadTool

Reads file content with encoding detection and binary data handling.

Parameters:

  • path (required) - File path to read

Security Checks:

  1. Path must be within workspace if workspace_only = true
  2. Path must not be in forbidden directories
  3. Symlink resolution must not escape workspace
  4. Autonomy level must allow read operations

Sources: src/tools/file_read.rs

FileWriteTool

Writes or appends content to files with automatic parent directory creation.

Parameters:

  • path (required) - File path to write
  • content (required) - Content to write
  • append (optional) - If true, append instead of overwrite

Security Checks:

  1. All FileReadTool checks
  2. Autonomy level must be Supervised or Full (blocks ReadOnly)
  3. Action budget check via record_action()

Sources: src/tools/file_write.rs

Forbidden Path Protection

Both file tools block access to 14 system directories hardcoded in SecurityPolicy:

/etc  /sys  /proc  /dev  /boot  /root  /usr/bin  /usr/sbin  
/bin  /sbin  /lib  /lib64  /var  /tmp

Sources: src/security/policy.rs

Memory Management Tools

Memory tools provide persistent context storage and retrieval through the Memory trait abstraction. The agent can store facts, recall relevant context, and forget outdated information.

Memory Tool Suite

graph LR
    subgraph "Memory Tools"
        MemoryStoreTool["MemoryStoreTool::execute()"]
        MemoryRecallTool["MemoryRecallTool::execute()"]
        MemoryForgetTool["MemoryForgetTool::execute()"]
    end
    
    subgraph "Memory Backend Interface"
        MemoryTrait["Memory trait"]
    end
    
    subgraph "Implementations"
        SQLiteMemory["SQLiteMemory<br/>(vector + FTS5)"]
        PostgresMemory["PostgresMemory"]
        MarkdownMemory["MarkdownMemory"]
        LucidMemory["LucidMemory<br/>(remote)"]
        NoneMemory["NoneMemory<br/>(no-op)"]
    end
    
    MemoryStoreTool --> MemoryTrait
    MemoryRecallTool --> MemoryTrait
    MemoryForgetTool --> MemoryTrait
    
    MemoryTrait --> SQLiteMemory
    MemoryTrait --> PostgresMemory
    MemoryTrait --> MarkdownMemory
    MemoryTrait --> LucidMemory
    MemoryTrait --> NoneMemory
Loading

Sources: src/tools/memory_store.rs, src/tools/memory_recall.rs, src/tools/memory_forget.rs, src/memory/mod.rs

MemoryStoreTool

Stores a fact or context snippet with automatic embedding generation.

Parameters:

  • content (required) - The fact to store
  • tags (optional) - Comma-separated tags for categorization

Behavior:

  • Generates embedding via provider (e.g., OpenAI text-embedding-3-small)
  • Stores content with timestamp, tags, and vector
  • Requires Supervised or Full autonomy (blocks ReadOnly)

Sources: src/tools/memory_store.rs

MemoryRecallTool

Retrieves relevant memories using hybrid vector + keyword search.

Parameters:

  • query (required) - Search query
  • limit (optional) - Max results (default: 5)

Behavior:

  • No security restrictions (read-only operation)
  • Returns timestamp, content, similarity score, and tags
  • Uses hybrid search (vector cosine + FTS5 keyword)

Sources: src/tools/memory_recall.rs

MemoryForgetTool

Deletes a memory by ID.

Parameters:

  • id (required) - Memory ID to delete

Behavior:

  • Requires Supervised or Full autonomy
  • Returns confirmation or "not found" error

Sources: src/tools/memory_forget.rs

Git Operations Tool

The GitOperationsTool provides structured Git repository management with parsed JSON output. It supports read-only operations (status, diff, log, branch) and write operations (commit, add, checkout, stash).

Git Operations Overview

graph TB
    GitTool["GitOperationsTool::execute()"]
    
    GitTool --> ParseOp{"operation<br/>parameter"}
    
    ParseOp -->|status| GitStatus["git_status()<br/>porcelain=2 format"]
    ParseOp -->|diff| GitDiff["git_diff()<br/>unified hunks"]
    ParseOp -->|log| GitLog["git_log()<br/>commits array"]
    ParseOp -->|branch| GitBranch["git_branch()<br/>branch list"]
    ParseOp -->|commit| GitCommit["git_commit()<br/>write op"]
    ParseOp -->|add| GitAdd["git_add()<br/>write op"]
    ParseOp -->|checkout| GitCheckout["git_checkout()<br/>write op"]
    ParseOp -->|stash| GitStash["git_stash()<br/>write op"]
    
    GitStatus --> JSONOutput["Structured JSON<br/>response"]
    GitDiff --> JSONOutput
    GitLog --> JSONOutput
    GitBranch --> JSONOutput
    
    GitCommit --> SecurityGate{"Write operation<br/>security checks"}
    GitAdd --> SecurityGate
    GitCheckout --> SecurityGate
    GitStash --> SecurityGate
    
    SecurityGate -->|approved| WriteExec["Execute git<br/>command"]
    SecurityGate -->|denied| WriteError["ToolResult error"]
    
    WriteExec --> JSONOutput
Loading

Sources: src/tools/git_operations.rs:1-567

Read-Only Operations

These operations require no special permissions and work in ReadOnly mode:

Operation Parameters Output
status None {branch, staged[], unstaged[], untracked[], clean}
diff files, cached {hunks[], file_count} with line-by-line changes
log limit {commits[{hash, author, email, date, message}]}
branch None {current, branches[{name, current}]}

Sources: src/tools/git_operations.rs:83-280

Write Operations

Write operations require Supervised or Full autonomy and enforce argument sanitization:

Operation Parameters Security
commit message Blocks injection via --exec, -c, command substitution
add paths Path sanitization, forbidden directory check
checkout branch Branch name validation, blocks @, ^, ~
stash action, index Actions: push, pop, list, drop

Injection Prevention:

The tool blocks dangerous git arguments:

  • --exec=, --upload-pack=, --receive-pack=
  • --pager=, --editor=, --no-verify
  • -c flag (git config injection)
  • Shell metacharacters: $(, `, |, ;, >

Sources: src/tools/git_operations.rs:23-50, src/tools/git_operations.rs:290-423

Cron Scheduling Tools

Cron tools enable the agent to schedule recurring or one-time tasks. Jobs can be shell commands or agent prompts, with flexible scheduling (cron expressions, intervals, or one-time execution).

Cron Tool Architecture

graph TB
    subgraph "Cron Management Tools"
        CronAddTool["CronAddTool"]
        CronListTool["CronListTool"]
        CronRemoveTool["CronRemoveTool"]
        CronUpdateTool["CronUpdateTool"]
        CronRunTool["CronRunTool"]
        CronRunsTool["CronRunsTool"]
    end
    
    subgraph "Cron Job Storage"
        CronDB[("SQLite DB<br/>cron_jobs table")]
    end
    
    subgraph "Scheduler Background Process"
        SchedulerLoop["scheduler::run()<br/>poll loop"]
        DueJobs["due_jobs()<br/>query next jobs"]
        ExecuteJob["execute_job_with_retry()"]
        PersistResult["persist_job_result()"]
    end
    
    CronAddTool --> CronDB
    CronListTool --> CronDB
    CronRemoveTool --> CronDB
    CronUpdateTool --> CronDB
    CronRunTool --> ExecuteJob
    CronRunsTool --> CronDB
    
    SchedulerLoop --> DueJobs
    DueJobs --> CronDB
    DueJobs --> ExecuteJob
    
    ExecuteJob -->|JobType::Shell| ShellExec["run_job_command()<br/>sh -lc"]
    ExecuteJob -->|JobType::Agent| AgentExec["run_agent_job()<br/>agent::run()"]
    
    ExecuteJob --> PersistResult
    PersistResult --> CronDB
Loading

Sources: src/tools/cron_add.rs, src/tools/cron_list.rs, src/tools/cron_remove.rs, src/tools/cron_update.rs, src/tools/cron_run.rs, src/tools/cron_runs.rs, src/cron/scheduler.rs:21-45

Cron Job Types

ZeroClaw supports two job types:

Shell Jobs:

  • Execute via sh -lc in the workspace directory
  • Subject to allowed_commands and path security checks
  • Timeout: 120 seconds (configurable via test mocks)

Agent Jobs:

  • Execute via agent::run() with a prompt
  • Optionally specify a different model
  • Use isolated or main conversation session

Sources: src/cron/scheduler.rs:377-467, src/cron/scheduler.rs:119-150

Schedule Types

Type Syntax Example
Cron expression Standard cron format "0 */6 * * *" (every 6 hours)
Interval { every_ms: N } { every_ms: 300000 } (every 5 minutes)
One-time { at: TIMESTAMP } { at: "2024-06-15T10:00:00Z" }

Sources: src/cron/mod.rs

Delivery Configuration

Jobs can announce results to channels:

Parameters:

  • mode - "announce" or "silent"
  • channel - "telegram", "discord", "slack", "mattermost"
  • to - Target identifier (chat_id, channel_id, etc.)
  • best_effort - If true, job succeeds even if delivery fails

Sources: src/cron/scheduler.rs:240-317

Security Enforcement in Scheduler

The scheduler enforces security checks before executing shell jobs:

  1. Autonomy Check - Blocks execution in ReadOnly mode
  2. Rate Limiting - Checks max_actions_per_hour
  3. Command Allowlist - Validates command against allowed_commands
  4. Path Argument Scanning - Detects forbidden paths in command arguments
  5. Action Recording - Decrements action budget

Sources: src/cron/scheduler.rs:377-467

Configuration Tools

ScheduleTool

Creates one-time scheduled tasks (simpler API than cron tools).

Parameters:

  • command - Shell command to execute
  • when - Execution time (ISO 8601 timestamp)
  • name (optional) - Job name

Behavior:

  • Creates a Schedule::At job with delete_after_run = true
  • Requires Supervised or Full autonomy

Sources: src/tools/schedule.rs

ProxyConfigTool

Manages proxy configuration at runtime.

Parameters:

  • action - "show", "set", "clear"
  • proxy_url (for set) - Proxy URL (e.g., http://proxy:8080)

Behavior:

  • Read-only "show" works in any autonomy mode
  • "set" and "clear" require Supervised or Full
  • Applies to future HTTP requests via build_runtime_proxy_client()

Sources: src/tools/proxy_config.rs

PushoverTool

Sends push notifications via Pushover API.

Parameters:

  • message (required) - Notification text
  • title (optional) - Notification title
  • priority (optional) - -2 (silent) to 2 (emergency)
  • sound (optional) - Sound override

Credentials:

  • Reads PUSHOVER_TOKEN and PUSHOVER_USER_KEY from .env file
  • Supports export prefix and quoted values
  • Ignores comments (lines starting with #)

Sources: src/tools/pushover.rs:1-216

Tool Execution Flow

The following diagram shows how tools are discovered and executed during an agent turn:

sequenceDiagram
    participant LLM as Provider
    participant Agent as Agent::turn()
    participant Dispatcher as ToolDispatcher
    participant Registry as Tool Registry
    participant Tool as Tool::execute()
    participant Security as SecurityPolicy
    
    Agent->>LLM: chat(messages, tools)
    LLM-->>Agent: ChatResponse{tool_calls}
    
    loop For each tool_call
        Agent->>Dispatcher: dispatch_tool_calls()
        Dispatcher->>Registry: Find tool by name
        Registry-->>Dispatcher: Tool instance
        
        Dispatcher->>Tool: execute(args)
        
        Tool->>Security: can_act()?
        Security-->>Tool: true/false
        
        Tool->>Security: record_action()?
        Security-->>Tool: true/false
        
        alt Security approved
            Tool->>Tool: Perform operation
            Tool-->>Dispatcher: ToolResult{success: true}
        else Security denied
            Tool-->>Dispatcher: ToolResult{success: false, error}
        end
        
        Dispatcher-->>Agent: Vec<ToolExecutionResult>
    end
    
    Agent->>Agent: Append tool results to history
    Agent->>LLM: chat(messages + tool_results)
    LLM-->>Agent: ChatResponse{text}
Loading

Sources: src/agent/agent.rs, src/agent/dispatcher.rs, src/tools/traits.rs

Tool Result Structure

All tools return a ToolResult with three fields:

pub struct ToolResult {
    pub success: bool,
    pub output: String,
    pub error: Option<String>,
}

Success case: success = true, output contains result data, error = None
Failure case: success = false, output may be empty, error contains error message

Sources: src/tools/traits.rs

Summary Table

Tool Purpose Autonomy Requirement Rate Limited
ShellTool Execute shell commands Supervised/Full Yes
FileReadTool Read file content Any No
FileWriteTool Write/append files Supervised/Full Yes
MemoryStoreTool Store context Supervised/Full Yes
MemoryRecallTool Search memories Any No
MemoryForgetTool Delete memory Supervised/Full Yes
GitOperationsTool (read) status, diff, log, branch Any No
GitOperationsTool (write) commit, add, checkout, stash Supervised/Full Yes
CronAddTool Create scheduled job Supervised/Full Yes
CronListTool List jobs Any No
CronRemoveTool Delete job Supervised/Full Yes
CronUpdateTool Modify job Supervised/Full Yes
CronRunTool Execute job now Supervised/Full Yes
CronRunsTool List job history Any No
ScheduleTool One-time task Supervised/Full Yes
ProxyConfigTool (show) Display proxy Any No
ProxyConfigTool (set/clear) Modify proxy Supervised/Full Yes
PushoverTool Send notification Supervised/Full Yes

Sources: src/tools/mod.rs:72-238, src/security/policy.rs

Home

  1. Overview

  2. Getting Started

  3. Core Architecture

  4. Configuration

  5. Providers

  6. Channels

  7. Agent Core

  8. Tools

  9. Memory System

  10. Gateway

  11. Scheduler

  12. Development Guide

  13. Deployment

  14. Maturity Framework

Clone this wiki locally
⚡