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

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)