<!-- source: https://deepwiki.com/qhkm/zeptoclaw/8.4-filesystem-and-shell-tools -->

# Filesystem and Shell Tools

- src/tools/filesystem.rs
- src/tools/git.rs
- src/tools/r8r.rs
- src/tools/shell.rs
- tests/e2e.rs

This document describes ZeptoClaw's built-in filesystem and shell execution tools, which enable the AI agent to read/write files, execute commands, and interact with git repositories. These tools form the foundation for coding assistance, system automation, and project management capabilities.

For information about custom user-defined shell tools, see [Custom Tools](/qhkm/zeptoclaw/8.5-custom-tools). For web-based tools like `web_search` and `web_fetch`, see [Web Tools](/qhkm/zeptoclaw/8.3-web-tools). For the overall tool architecture, see [Tool System Architecture](/qhkm/zeptoclaw/3.4-tool-system-architecture).

## Tool Categories and Security Model

ZeptoClaw categorizes filesystem and shell tools by their risk level, which determines the approval requirements under different agent modes (Observer/Assistant/Autonomous). The security architecture applies multiple layers of defense-in-depth to prevent unauthorized file access and command injection.

### Tool Security Architecture

Title: "From Natural Language Space to Code Entity Space: Security Validation"

```

```

Sources: [src/tools/filesystem.rs33-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L33-L44) [src/tools/shell.rs146-153](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L146-L153) [src/tools/git.rs161-165](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/git.rs#L161-L165) [src/tools/r8r.rs217-220](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L217-L220)

**Security Flow**: Tools are categorized → Agent mode determines approval requirements → Path/command validation → Shell security checks → Execution within selected runtime isolation.

## Filesystem Tools

Filesystem tools operate on paths relative to the configured workspace directory. All operations are restricted to workspace-relative paths via `validate_path_in_workspace` [src/tools/filesystem.rs39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L39-L39) and security validation blocks attempts to access system directories or escape via symlinks.

### Core Filesystem Operations

### Path Resolution and Security

All filesystem tools utilize `resolve_path` to ensure operations remain within the workspace boundary.

```

```

Sources: [src/tools/filesystem.rs33-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L33-L44)

### write_file Security

The `write_file` tool implements strict checks to prevent hardlink-based attacks. On Unix systems, it uses `libc::O_NOFOLLOW` [src/tools/filesystem.rs61](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L61-L61) and verifies `nlink` counts [src/tools/filesystem.rs77-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L77-L83) to ensure a file doesn't alias content outside the workspace. The operation is wrapped in `tokio::task::spawn_blocking` to avoid stalling the async runtime [src/tools/filesystem.rs120](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L120-L120)

```

```

Sources: [src/tools/filesystem.rs47-97](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L47-L97) [src/tools/filesystem.rs116-123](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L116-L123)

## Shell Tool

The `shell` tool executes arbitrary shell commands via `sh -c` with multi-layer security validation and optional container isolation.

### Shell Execution Architecture

Title: "Shell Tool Execution Flow"

```

```

Sources: [src/tools/shell.rs146-173](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L146-L173) [src/tools/shell.rs46-49](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L46-L49)

### Shell Security Configuration

Shell command validation uses `ShellSecurityConfig` to prevent dangerous operations [src/tools/shell.rs152](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L152-L152) By default, it enforces a blocklist. In trusted environments, `ShellTool::permissive()` can be used to bypass these checks [src/tools/shell.rs91-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L91-L96)

Sources: [src/tools/shell.rs152](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L152-L152) [src/tools/shell.rs87-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L87-L96)

## Git Tool

The `git` tool provides structured access to common git operations by shelling out to the system `git` binary. It requires a configured workspace and validates that `git` is allowed by the shell security policy [src/tools/git.rs161-165](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/git.rs#L161-L165)

### Implementation Details

The `GitTool` uses a private `run` function to execute commands within the workspace directory. It uses `std::process::Command` to invoke the system binary [src/tools/git.rs80-84](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/git.rs#L80-L84)

```

```

Sources: [src/tools/git.rs80-84](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/git.rs#L80-L84)

### Supported Actions

- status : Working-tree status src/tools/git.rs 185-192
- log : Commit history (default 10, max 200) src/tools/git.rs 194-208
- diff : Unstaged diff (optionally scoped to a path).
- blame : Per-line authorship (requires path ).
- commit : Stage tracked changes and commit (requires message ).
- add : Stage a file or directory.
- checkout : Switch branches (requires branch ).

Sources: [src/tools/git.rs8-15](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/git.rs#L8-L15) [src/tools/git.rs184-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/git.rs#L184-L210)

## R8r Workflow Tool

The `r8r` tool provides a bridge to the `r8r` workflow engine for deterministic, agent-first automation [src/tools/r8r.rs3-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L3-L5) It is used for reliable multi-step pipelines and HTTP calls that complement the agent's reasoning.

### Workflow Integration

ZeptoClaw interacts with r8r via its HTTP API (defaulting to `localhost:8080`) [src/tools/r8r.rs42](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L42-L42)

Sources: [src/tools/r8r.rs47-55](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L47-L55) [src/tools/r8r.rs189-211](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/r8r.rs#L189-L211)

## Output Management

To prevent context window overflow, tool outputs are truncated using `truncate_tool_output`. This ensures that large files or command outputs do not exhaust the LLM's token budget.

- Default Max Lines : 1000 ( DEFAULT_MAX_LINES )
- Default Max Bytes : 32,768 ( DEFAULT_MAX_BYTES )

Sources: [src/tools/filesystem.rs192-196](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/filesystem.rs#L192-L196) [src/tools/shell.rs174-176](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/shell.rs#L174-L176) [src/tools/output.rs23](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/output.rs#L23-L23)
