cleveragents-core/docs/reference/builtin_tools.md

# Built-in File Tools

The built-in file tools provide safe file system operations for agents.
All tools are registered under the `builtin/` namespace and include
path traversal prevention.

## Tools

### builtin/file-read

Read file content.

**Inputs:**

| Parameter  | Type   | Default  | Description                     |
|------------|--------|----------|---------------------------------|
| `path`     | string | required | File path to read               |
| `encoding` | string | `utf-8`  | File encoding                   |
| `offset`   | int    | `0`      | Line offset to start from       |
| `limit`    | int    | `null`   | Maximum number of lines to read |

**Outputs:**

| Field      | Type   | Description              |
|------------|--------|--------------------------|
| `content`  | string | File content             |
| `size`     | int    | File size in bytes       |
| `encoding` | string | Encoding used            |

**Capabilities:** `read_only=True`

---

### builtin/file-write

Write content to file (create or overwrite).

**Inputs:**

| Parameter    | Type    | Default  | Description                          |
|--------------|---------|----------|--------------------------------------|
| `path`       | string  | required | File path to write                   |
| `content`    | string  | required | Content to write                     |
| `encoding`   | string  | `utf-8`  | File encoding                        |
| `create_dirs`| boolean | `true`   | Create parent directories if needed  |

**Outputs:**

| Field     | Type    | Description                    |
|-----------|---------|--------------------------------|
| `path`    | string  | Absolute path of written file  |
| `size`    | int     | Written file size in bytes     |
| `created` | boolean | Whether file was newly created |

**Capabilities:** `writes=True`

---

### builtin/file-edit

Edit file with string replacement.

**Inputs:**

| Parameter     | Type    | Default  | Description               |
|---------------|---------|----------|---------------------------|
| `path`        | string  | required | File path to edit         |
| `old_text`    | string  | required | Text to find              |
| `new_text`    | string  | required | Replacement text          |
| `replace_all` | boolean | `false`  | Replace all occurrences   |

**Outputs:**

| Field          | Type   | Description                    |
|----------------|--------|--------------------------------|
| `path`         | string | Absolute path of edited file   |
| `replacements` | int    | Number of replacements made    |

**Capabilities:** `writes=True`

---

### builtin/file-delete

Delete a file.

**Inputs:**

| Parameter | Type   | Default  | Description          |
|-----------|--------|----------|----------------------|
| `path`    | string | required | File path to delete  |

**Outputs:**

| Field    | Type    | Description                      |
|----------|---------|----------------------------------|
| `path`   | string  | Absolute path of deleted file    |
| `existed`| boolean | Whether the file existed         |

**Capabilities:** `writes=True`

---

### builtin/file-list

List directory contents.

**Inputs:**

| Parameter   | Type    | Default  | Description                    |
|-------------|---------|----------|--------------------------------|
| `path`      | string  | required | Directory path to list         |
| `pattern`   | string  | `*`      | Glob pattern to filter entries |
| `recursive` | boolean | `false`  | Recurse into subdirectories    |

**Outputs:**

| Field   | Type  | Description                                              |
|---------|-------|----------------------------------------------------------|
| `files` | array | List of entries, each with `name`, `path`, `size`, `is_dir` |

**Capabilities:** `read_only=True`

---

### builtin/file-search

Search files for content.

**Inputs:**

| Parameter     | Type   | Default  | Description                    |
|---------------|--------|----------|--------------------------------|
| `path`        | string | required | Directory path to search       |
| `pattern`     | string | required | Regex pattern to search for    |
| `include`     | string | `*`      | Glob pattern to filter files   |
| `max_results` | int    | `100`    | Maximum number of results      |

**Outputs:**

| Field     | Type  | Description                                        |
|-----------|-------|----------------------------------------------------|
| `matches` | array | List of matches, each with `file`, `line`, `content` |

**Capabilities:** `read_only=True`

## Resource Slot Requirements

All file tools accept an optional `sandbox_root` input parameter that
constrains file operations to a specific directory.  When not provided,
the current working directory is used as the sandbox root.

Path traversal attacks (using `..` to escape the sandbox) are detected
and rejected with a `ValueError`.

## ChangeSet Capture

The `ChangeSetCapture` class wraps write/edit/delete tool executions to
automatically record change entries:

- **ChangeSetEntry**: records `operation` (create/modify/delete/move),
  `path`, optional `before_hash` and `after_hash` (SHA-256), and
  arbitrary `metadata`.
- **ChangeSet**: accumulates entries with a `plan_id` and provides
  a `summary()` method.

Use `register_file_tools_with_changeset()` to register all tools with
automatic change tracking.

## Registration

```python
from cleveragents.tool.builtins import (
    register_file_tools,
    register_file_tools_with_changeset,
)
from cleveragents.tool.builtins.changeset import ChangeSetCapture
from cleveragents.tool.registry import ToolRegistry

# Simple registration
registry = ToolRegistry()
register_file_tools(registry)

# With changeset capture
capture = ChangeSetCapture(plan_id="my-plan")
registry = ToolRegistry()
register_file_tools_with_changeset(registry, capture)
```