sjw1231
ea4837abb1
This pull request lands the tool; switching the shipped defaults is a separate pull request stacked on it. Every shipped `tool-fs` row states `applyPatch: false`, the `fs-observation-policy` row stays mounted, the write, edit, and apply_patch guidance names the policy, and every recorded expectation outside the apply-patch scenarios returns to the master baseline. The upgrade guide, the parity exception, and the optional classification of the policy package move to the stacked change.
description, kind
| description | kind |
|---|---|
| The filesystem package group: the ctx.fs provider contract, local and sandbox-enforcing backends, the read-before-edit policy plugin, and the model-facing file and search tools. | package-group |
packages/fs
English | 中文
Summary
The fs/ group gives agents durable, policy-governed access to files: the ctx.fs service contract in fs/, the host-filesystem and sandbox-enforcing backends in fs-local/ and fs-sandbox/, the read-before-edit policy in fs-observation-policy/, and the model-facing tools in tool-fs/ (read, read_image, write, edit, apply_patch) and tool-fs-search/ (glob, grep). A deployment mounts one backend, loads the policy for freshness-guarded mutations, and registers the tool packages the model should see; backends swap without touching the tools or the policy. File I/O takes no timeout by design: a deadline would kill work the OS still finishes, so cancellation is a best-effort signal at syscall boundaries.
Table of Contents
Packages
The packages below provide filesystem access and patch parsing; the subsystem reference owns the exhaustive contracts and the error taxonomy.
| Package | Role | ctx key |
|---|---|---|
fs/ |
ctx.fs service contract: execution-world paths, bounded text I/O, and atomic mutations with an optional version guard |
ctx.fs |
fs-patch/ |
Pure Codex-style patch parsing and hunk application | none |
fs-local/ |
Host-filesystem backend: reads, writes, edits, patches, deletes, and moves real files on the local machine | registers on ctx.fs |
fs-sandbox/ |
Sandbox-enforcing backend: fences every mutation by the per-call sandbox mode while reads pass through | registers on ctx.fs |
fs-observation-policy/ |
Read-before-edit policy: records observed presence or absence and guards mutations through the fs/* events |
fs/* listeners |
tool-fs/ |
Model-facing read, read_image, write, edit, and apply_patch tools plus their executor |
registers on ctx.tools |
tool-fs-search/ |
Model-facing glob and grep discovery tools backed by the packaged ripgrep binary |
registers on ctx.tools |
tool-str-replace-editor/ |
Standalone str_replace_editor tool: view, create, str_replace, and insert over ctx.fs |
registers on ctx.tools |
The policy is a plugin, not a service the tools inject: removing it leaves the bare provider's unconditional mutation behavior instead of breaking the tools. The mode fence in fs-sandbox and the read-before-edit gate compose. tool-fs-search deliberately does not extend the provider contract — search is a process-backed ripgrep workflow, so filesystem backends stay free of a universal search API.
Related documentation
Start with the subsystem reference for the shared vocabulary and error taxonomy, then the decisions that shaped the family.
- Filesystem subsystem — targets, outcomes, guards, policy events, and the error taxonomy.
- Cross-family fs sandbox reference — the shared sandbox mode fence over the filesystem seam.
- Portable execution world consumers decision — why filesystem and subprocess providers share one execution world.
Dev Note
Working context for maintainers — click to expand
None.