Agent Filesystem Tool Layer • FILESYSTEM.md

Builder procedure

Purpose

Agents do not call your storage SDK. They call tools. The tool layer is the public ABI.

Recommended tool set

Tool	Maps to	Notes
`list` / `LS`	`list(path)`	Return names + types
`read_file`	`read(path)`	Cap max bytes; support offset/limit if large
`write_file`	`write(..., overwrite)`	Prefer patches when available
`edit_file`	surgical update	Reduces rewrite risk
`append_file`	`write(..., append)`	For `LOGS/` and observations
`grep` / `search`	indexed or ripgrep	Exact match for configs
`bash`	shell in sandbox	Powerful; needs strict policy

Keep names stable. Document them in TOOLS.md without secrets.

Schema tips (SHOULD)

Validate paths with a jail-aware normalizer before I/O
Mark tools read-only vs destructive for permission engines
Bound output size (maxResultSizeChars) so tool results cannot blow the context window
Return structured errors agents can recover from

Concurrency (SHOULD)

Reads: usually concurrency-safe
Writes to the same path: serialize or reject
bash: treat as potentially destructive; gate with permissions

Mapping to FILESYSTEM.md

FILESYSTEM.md abstract op	Tool
Orient	`list`, `grep`
Execute write	`write_file` / `edit_file`
Memory append	`append_file`
Skill load	`read_file SKILLS/.../SKILL.md`
Log	`append_file LOGS/...`

See For Agents → Operations and Claude Code mapping.

Anti-patterns

One mega-run_code tool with no path policy
Returning entire repos from a single read
Silent overwrite of append-only logs
Tool descriptions that contradict FILESYSTEM.md

Industrial harnesses (see the Claude Code study tool chapters) separate tool type systems, permission checks, and UI/progress. You do not need feature parity on day one — you need a safe, path-centric MVP.