Built-in Tool: Filesystem

Document ID: TRT-101
File Path: docs/07-tool-runtime/filesystem.md
Version: 1.0.0
Status: Draft
Owner: AI Platform Team
Last Updated: 2026-06-27

1. Purpose

The fs.* built-in tools let agents read and write files within an allowed workspace. They run in the Tool Runtime sandbox under filesystem policy.

2. Operations

Tool	Description
`fs.read`	Read a file’s contents
`fs.write`	Create/overwrite a file
`fs.append`	Append to a file
`fs.list`	List a directory
`fs.stat`	File metadata
`fs.delete`	Remove a file

3. Schema (example: `fs.read`)

// input
{ "path": "/workspace/src/config.rs" }
// output
{ "path": "...", "bytes": 1024, "content": "..." }

Inputs/outputs are validated against the tool’s JSON schema (execution API).

4. Permissions

fs:read:/workspace      fs:write:/workspace

Access is default-deny; only explicitly granted paths are reachable (tool isolation). Plugins/agents must hold the matching grant.

5. Sandbox & Safety

Runs with a fresh, isolated root; only granted paths mounted; system paths read-only.
Output is bounded (max_output_bytes) to prevent huge reads.
Path traversal outside allowed roots is rejected.
Scratch is wiped on teardown.

6. Determinism & Caching

fs.read/fs.list/fs.stat are read-only and may be cached briefly; writes are side-effecting and never cached (caching).

7. Example

wovyr tools invoke fs.read --input '{"path":"/workspace/README.md"}'

Commonly used by the Code Agent.

9. Revision History

Version	Date	Description
1.0.0	2026-06-27	Initial Filesystem tool spec