tools — Agent Tool Implementations

🎯 Why This Module Exists

Without the tools/ module, every component in Hermes Agent — the CLI, the gateway, the batch runner — would need to independently implement command execution, file I/O, web scraping, and dozens of other capabilities. Each would maintain its own subprocess management, its own security checks, its own error handling. The result would be a fragmented, inconsistent, and deeply unsafe system where adding a single new capability means touching every integration point.

The tools module solves this by providing a single, unified registry where every agent capability is declared with its schema, handler, security gates, and resource limits. A thread-safe dispatch mechanism routes LLM tool calls to the correct handler, manages async/sync bridging, enforces per-tool and per-turn output budgets to prevent context-window overflow, and applies security policies (write deny lists, dangerous command approval, skill scanning) before any side-effecting operation executes. The pluggable environment system means the same terminal() call works identically whether the agent is running locally, inside Docker, over SSH, on Modal cloud, in a Singularity container, or through a Daytona workspace — all without the LLM or higher layers knowing the difference.

🚶 Step-by-Step Narrated Walkthrough

Follow a single terminal("ls -la /workspace") command as it flows through the entire tools pipeline:

1. LLM Generates Tool Call — The model emits a function call: {"name": "terminal", "args": {"command": "ls -la /workspace"}}. The agent runtime receives this as a structured tool-use block.
2. Registry Dispatch — model_tools.py calls registry.dispatch("terminal", args). The registry looks up the ToolEntry for "terminal", verifying the toolset's check_fn returns true (terminal is always available).
3. Approval Check — approval.py scans the command against DANGEROUS_PATTERNS (regex list for rm -rf /, chmod 777, sudo, etc.). ls -la matches no patterns, so execution proceeds without prompting.
4. Environment Resolution — terminal_tool.py resolves the execution backend: check the env parameter, then TERMINAL_ENV env var, then config.yaml, then fall back to "local". For this walkthrough, we get LocalEnvironment.
5. Session Snapshot Sourcing — BaseEnvironment._wrap_command() prepends the session snapshot (captured at init_session()) — sourcing env vars, functions, and aliases. It then cds to the tracked CWD.
6. Subprocess Spawn — LocalEnvironment._run_bash() spawns subprocess.Popen(["bash", "-c", wrapped_cmd]) with stdout/stderr piped. This is the spawn-per-call pattern — a fresh bash for every command.
7. Interrupt-Safe Polling — _wait_for_process() polls every 0.5 seconds, checking both process completion (proc.poll()) and user interrupt (is_interrupted()). If the 600-second timeout hits, it sends SIGTERM → 5s grace → SIGKILL.
8. Output Parsing — The wrapper emits CWD markers (__HERMES_CWD_{session_id}__) and exit code markers. The parser extracts the actual command output, the new CWD, and the return code.
9. CWD Persistence — The new CWD is written to /tmp/hermes-cwd-{session_id}.txt so the next command starts in the right directory.
10. Result Sizing — tool_result_storage.py checks the output size against the per-tool threshold (terminal defaults to 100K chars). Our ls -la output is small, so it returns inline.
11. JSON Serialization — The handler returns {"returncode": 0, "stdout": "total 42\ndrwxr-xr-x ...", "cwd": "/workspace"} as a JSON string.
12. Response to LLM — The serialized result is sent back to the model as a tool-result content block, completing the round-trip in typically <100ms for local commands.

Tool Approval Flow & Security Pipeline

The Problem: An autonomous AI agent that can execute arbitrary shell commands is inherently dangerous. It could rm -rf /, exfiltrate credentials via curl, or escalate privileges with sudo. The system needs to detect dangerous operations and gate them behind approval — without blocking legitimate work or creating excessive friction.

The Approach: A multi-stage security pipeline evaluates every side-effecting operation. First, regex-based pattern matching scans commands against a curated list of dangerous patterns (recursive deletion, world-writable permissions, credential access). If a match is found, the system attempts LLM-based auto-approval: a cheap model evaluates whether the command is actually low-risk in context. If auto-approval fails, the user is prompted interactively (CLI) or the command is logged and rejected (gateway). Approved commands are added to a per-session allowlist so repeated similar operations don't trigger re-approval. For file writes, a separate deny list blocks writes to sensitive paths (~/.ssh/, /etc/sudoers, ~/.hermes/.env) unconditionally.

Why This Algorithm: Pure regex matching would generate too many false positives (blocking harmless rm on temp files). Pure LLM-based analysis would be too slow and expensive for every command. The layered approach — fast regex filter → smart LLM analysis → user approval fallback — balances security, speed, and usability. Per-session allowlists prevent approval fatigue during iterative development.

graph TD
    CMD["Command Input"]
    REGEX{"Regex Match\nDANGEROUS_PATTERNS?"}
    SAFE["Execute Immediately"]
    WDENY{"Write Deny\nList Check?"}
    BLOCK["Block: Protected Path"]
    AUTO{"LLM Auto-Approve\nLow-risk in context?"}
    ALLOW["Add to Session Allowlist"]
    PROMPT{"User Approval\nCLI / Gateway?"}
    EXEC["Execute Command"]
    REJECT["Reject + Log"]

    CMD --> WDENY
    WDENY -->|"Denied Path"| BLOCK
    WDENY -->|"Allowed Path"| REGEX
    REGEX -->|"No Match"| SAFE
    REGEX -->|"Match Found"| AUTO
    AUTO -->|"Low Risk"| ALLOW --> EXEC
    AUTO -->|"High Risk"| PROMPT
    PROMPT -->|"Approved"| ALLOW
    PROMPT -->|"Denied"| REJECT
    SAFE --> EXEC

Hot Paths

The most performance-sensitive code paths in this module:

• Registry Dispatch: O(1) dict lookup per tool call — the critical path for every agent action. RWLock ensures readers never block each other; writes (MCP tool registration) acquire exclusive lock briefly.
• Session Snapshot Sourcing: Captured once at init_session(), sourced before each command via _wrap_command(). Avoids bash -l overhead (~200ms per call). Snapshot is typically <5 KB of env vars + function definitions.
• Result Persistence Check: O(1) size comparison per tool result. The 3-layer budget enforcement sorts results by size (O(n log n) for n results per turn) but n is typically <10.
• Approval Regex Scan: ~15 regex patterns evaluated per command — typically completes in <1ms. Compiled regex objects are cached at module import.

Resource Usage

• Memory: Registry holds ~40 ToolEntry objects in-memory (~50 KB). MCP tools are added dynamically but follow the same lightweight pattern. Environment objects are per-session singletons. Lazy imports (TTS, voice, browser) avoid loading heavy libraries until first use.
• I/O: Local commands spawn subprocesses (fork cost ~1-5ms). Docker/SSH/Modal commands add network round-trip (~10-100ms). Result persistence writes to /tmp/hermes-results/ only when thresholds are exceeded. Checkpoint manager does git operations with configurable timeout [10-60s].
• Concurrency: Registry supports concurrent reads via RWLock snapshots. Delegate tool caps concurrent sub-agents at 3 (configurable). Gateway sessions maintain isolated approval state via session_context context vars.