Filesystem Tools

Use sandboxed file tools for safe agent read/write operations (no path traversal), with an explicit root directory you control.

This page covers:

• The sandbox model (what paths are allowed)
• Registering filesystem tools
• Executing read/write/append/replace safely

Table of Contents

1. Sandbox model
2. Register filesystem tools
3. Examples

Sandbox model

Filesystem tools operate under a configured base directory (sandbox root). Requests like:

• ../secrets.txt
• /etc/passwd

should be rejected or normalized to stay within the sandbox.

Recommended layout:

• store agent file outputs under something like ./.sentience/files/

Register filesystem tools

from predicate.tools import ToolRegistry, FileSandbox, ToolContext, register_filesystem_tools

registry = ToolRegistry()
sandbox = FileSandbox("./.sentience/files")
register_filesystem_tools(registry, sandbox)

ctx = ToolContext(runtime, files=sandbox)

Examples

Write then read a file

await registry.execute("write_file", {"path": "notes.txt", "content": "hello"}, ctx=ctx)
result = await registry.execute("read_file", {"path": "notes.txt"}, ctx=ctx)
print(result.content)

Related topics

• Tool Registry — typed tool execution + tool-call trace events