@swoop111/dsh-tool-fs 0.0.0-stage → 0.2.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,142 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md
+/:
+  en: 52b93805befe8077
+  zh: 9786e662303f0e2f
+/deepseek-ai-dsh-tool-fs:
+  en: fc8f28deebe5fa6b
+  zh: 738c6ad45034da88
+/deepseek-ai-dsh-tool-fs/summary:
+  en: c8f608c85c8d6626
+  zh: 4133a867517baca5
+/deepseek-ai-dsh-tool-fs/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-fs/use-this-package:
+  en: 8fd62afcdabe55d4
+  zh: 9bdcae272575be8c
+/deepseek-ai-dsh-tool-fs/use-this-package/minimal-composition:
+  en: eb21d89a3ecbd2d4
+  zh: f05ccbb1e7515f32
+/deepseek-ai-dsh-tool-fs/use-this-package/the-tools:
+  en: acc54c7be5b7397c
+  zh: 99ea9935645aa347
+/deepseek-ai-dsh-tool-fs/use-this-package/configuration:
+  en: 037c36f06859e293
+  zh: aeb3b35361de0165
+/deepseek-ai-dsh-tool-fs/use-this-package/policy-and-sandbox-behavior:
+  en: 53d4ac2db089ef39
+  zh: 214ea051ed56f500
+/deepseek-ai-dsh-tool-fs/use-this-package/failures-and-recovery:
+  en: c9eb77c3c3deceb9
+  zh: b474cd2a764021db
+/deepseek-ai-dsh-tool-fs/understand-the-implementation:
+  en: e30f7038c28e93f8
+  zh: a3868dbd90367b13
+/deepseek-ai-dsh-tool-fs/understand-the-implementation/design-concept:
+  en: 454b5291db9ba847
+  zh: 9fe7081dfb416c93
+/deepseek-ai-dsh-tool-fs/understand-the-implementation/source-map:
+  en: 6c84b66a20a4cc5b
+  zh: cf840725912bc6f8
+/deepseek-ai-dsh-tool-fs/understand-the-implementation/per-tool-flow:
+  en: dad0c07c04e0fdb5
+  zh: caa0c4be18ee866c
+/deepseek-ai-dsh-tool-fs/understand-the-implementation/observation-and-concurrency:
+  en: 665d437dc35bf05f
+  zh: 8004334d6a3246b4
+/deepseek-ai-dsh-tool-fs/further-exploration:
+  en: 485bc55482f576bc
+  zh: fc5fa55b41098bd0
+/deepseek-ai-dsh-tool-fs/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt:
+  en: cf78b9dd5596495f
+  zh: bd44560f8c2435e8
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees:
+  en: b09ee4be5e522c29
+  zh: ffd30b57d7fc96e8
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/read-guidance:
+  en: f8961df3f3a6a671
+  zh: 85c7bd418b40b089
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/write-guidance:
+  en: 7e34af48c583f210
+  zh: e39ad6823689c665
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/edit-guidance:
+  en: 28f07502a411303b
+  zh: 437897dc99fc4360
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt/token-effect:
+  en: 7a44cabe439a879a
+  zh: 1adf9bf3de7658b6
+/deepseek-ai-dsh-tool-fs/model-experience/system-prompt/kv-cache-effect:
+  en: 4f1b5639f91405a8
+  zh: f90ffe077a2e52a3
+/deepseek-ai-dsh-tool-fs/model-experience/tool-schemas:
+  en: 3039bc5e7a796b21
+  zh: 6b7a9eaf69c9ea53
+/deepseek-ai-dsh-tool-fs/model-experience/tool-schemas/what-the-model-sees:
+  en: 6f2a072c474e39e7
+  zh: dbee4c2b206bf68f
+/deepseek-ai-dsh-tool-fs/model-experience/tool-schemas/token-effect:
+  en: 68517f7d65ef7e9d
+  zh: 544a4b81e8ea16c0
+/deepseek-ai-dsh-tool-fs/model-experience/tool-schemas/kv-cache-effect:
+  en: 1e6d3da20012762d
+  zh: 482f8bc569b8b490
+/deepseek-ai-dsh-tool-fs/model-experience/read-result:
+  en: ebd38733c0490428
+  zh: b45101c325efe784
+/deepseek-ai-dsh-tool-fs/model-experience/read-result/what-the-model-sees:
+  en: 68047e354dfb387c
+  zh: 1456ebecbedf7a90
+/deepseek-ai-dsh-tool-fs/model-experience/read-result/token-effect:
+  en: 4269b4368622ec2f
+  zh: f4df80c1fb6972f1
+/deepseek-ai-dsh-tool-fs/model-experience/read-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/deepseek-ai-dsh-tool-fs/model-experience/image-read-result:
+  en: 9dac44e6d0b9d8de
+  zh: 7bc4dc1c5df39eaf
+/deepseek-ai-dsh-tool-fs/model-experience/image-read-result/what-the-model-sees:
+  en: 9252b6d73776c5ff
+  zh: d6e433450989399e
+/deepseek-ai-dsh-tool-fs/model-experience/image-read-result/token-effect:
+  en: 68bd5255f1c9ca48
+  zh: 0474213531c1aae3
+/deepseek-ai-dsh-tool-fs/model-experience/image-read-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 48e202e396bc5fcc
+/deepseek-ai-dsh-tool-fs/model-experience/write-and-edit-results:
+  en: 1b3b6cfa3605d0b4
+  zh: 78e37c2aa4f76d54
+/deepseek-ai-dsh-tool-fs/model-experience/write-and-edit-results/what-the-model-sees:
+  en: bb2a92e0e43e3273
+  zh: a744395576b48a93
+/deepseek-ai-dsh-tool-fs/model-experience/write-and-edit-results/token-effect:
+  en: fb4d0b17a99f49cf
+  zh: 17460a2a5d72f6cc
+/deepseek-ai-dsh-tool-fs/model-experience/write-and-edit-results/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/deepseek-ai-dsh-tool-fs/model-experience/tool-errors:
+  en: 2d4f2c8605eccab3
+  zh: 67f1f0218f73c6bf
+/deepseek-ai-dsh-tool-fs/model-experience/tool-errors/what-the-model-sees:
+  en: 4e8fac7bac8ced61
+  zh: 7ba921dbcddc9f97
+/deepseek-ai-dsh-tool-fs/model-experience/tool-errors/token-effect:
+  en: 681cadd5be7b8ac1
+  zh: 65e483f62fb819d9
+/deepseek-ai-dsh-tool-fs/model-experience/tool-errors/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/deepseek-ai-dsh-tool-fs/known-limitations-and-deferred-work:
+  en: ce7a91d41d2f7597
+  zh: d4a3c905e124fd7f
+/deepseek-ai-dsh-tool-fs/known-limitations-and-deferred-work/dev-note:
+  en: 0c4d0c465413d319
+  zh: a20efeb10121b927

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+---
+description: "The model-facing read, read_image, write, and edit tools for users and maintainers composing or debugging filesystem access for agents."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @deepseek-ai/dsh-tool-fs
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `dsh-tool-fs` to let a model read UTF-8 files with line numbers, read supported images, create or atomically replace files, and apply targeted literal edits. Results are capped, and failures provide stable error codes and recovery instructions. Add `dsh-fs-observation-policy` when writes and edits must follow a successful read; without it, mutations remain atomic but are unconditional. Image reads require durable attachment storage and an image-capable routed model. Choose the sibling discovery package for glob or grep searches.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the tools after a `ctx.fs` backend and, for read-before-write/edit behavior, the policy plugin. The model then gets line-numbered reads, atomic writes and edits, and — with an attachment store mounted — image reads; every result is capped, and failures carry stable codes with recovery instructions.
+
+### Minimal composition
+
+A backend, the policy plugin, then the tools; the attachment store is optional and enables `read_image`.
+
+```yaml
+- name: '@deepseek-ai/dsh-fs-local'
+- name: '@deepseek-ai/dsh-fs-observation-policy'
+- name: '@deepseek-ai/dsh-tool-fs'
+```
+
+The policy plugin is optional: without it the tools run against the bare provider (unconditional write, overwrite, and edit with no observed-state). A deployment that loads these tools is expected to also load it, so the behavior is read-before-write/edit. `read_image` registers only while a durable `ctx.attachments` service is mounted; execution additionally refuses on a route whose exact model does not declare image input, so a text route's durable history stays free of image blocks.
+
+### The tools
+
+| Tool | Arguments | Behavior |
+|---|---|---|
+| `read` | `file_path`, `offset?`, `limit?`, `force?` | Line-numbered UTF-8 content with a pagination footer; `offset` is 1-based and `limit` defaults to and caps at the configured `readLimit`; `force` (present when `readRepair.duplicate` is enabled) reads the window even when the duplicate guard would refuse it |
+| `read_image` | `file_path` | Reads and persists a PNG/JPEG/WebP/GIF source; an extension-less path (normalized attachment object paths included) is identified from its file signature; normalization can downscale it before the next model request, so the model need not create a thumbnail first |
+| `write` | `file_path`, `content` | Creates or fully replaces a file; with the policy plugin, overwriting requires a prior `read` at the unchanged version, creating does not |
+| `edit` | `file_path`, `old_string`, `new_string`, `replace_all?` | Literal replacement requiring a unique match unless `replace_all` is true; with the policy plugin, requires a prior `read` and an unchanged file |
+
+Field names are snake_case to match Claude Code and existing harness tool schemas. Successes return compact envelopes — a read window, an image reference, or a `Created file`/`Updated file` confirmation — and `write`/`edit` derive replayable diff-card metadata for UI presentation.
+
+### Configuration
+
+All keys are optional; the defaults are the shipped read caps.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `readLimit` | `2000` | Default and maximum lines returned by one `read` call |
+| `readMaxLineLength` | `2000` | Characters kept per line before truncation |
+| `readMaxBytes` | `51200` | Byte cap on one `read` call's selected lines; overflow ends the window with a capped footer |
+| `readStreamMinSize` | `10485760` | Files at or above this size (or of unknown size) stream instead of loading whole into memory |
+| `readRepair.enabled` | `true` | Run the read repair rules for `read`'s addressing and path failures; disable to always error |
+| `readRepair.duplicate.enabled` | `true` | Refuse a read fully covered by this session's recent window of the same unchanged file version, answering with the delivered range instead of the content |
+| `readRepair.duplicate.maxSteps` | `4` | Steps committed since the recorded window beyond which the model is assumed to have forgotten the content, so the re-read is served |
+| `readRepair.completion.enabled` | `true` | Complete a window's structural boundaries: prepend the line that opened the construct the window starts inside, append the lines that close the construct it ends inside (fence, bracket block, indentation block) |
+| `readRepair.completion.maxLines` | `40` | Maximum lines appended to close the tail, and how far back the head search may reach for the opening line |
+| `editRepair.enabled` | `true` | Run the `fs-edit-repair` engine when `edit`'s `old_string` fails to match verbatim, and re-anchor `edit` to a verified matching path when the target is absent; disable to always error |
+| `editRepair.maxFileChars` | `1000000` | Content length above which the line-window repair rules are skipped |
+| `editRepair.maxWindowLines` | `64` | `old_string` line count above which the line-window repair rules are skipped |
+| `writeRepair.pathHint` | `true` | On a create, disclose a verified high-similarity existing path as a note — the write itself is never rewritten |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-fs) is the exhaustive source for every accepted field and its JSDoc.
+
+### Policy and sandbox behavior
+
+Path authorization for `read` and `read_image` belongs entirely to `ctx.fs`; media-type declarations and file signatures only decide whether `read_image` accepts the bytes returned by that backend.
+
+With the policy plugin mounted, `write` and `edit` obtain their guard from the `fs/*` intent slots, so an unread target or a stale observation fails with `FS_NOT_OBSERVED` or `FS_STALE_VERSION` and a recovery instruction. Under a confining backend (`fs-sandbox`), `write`/`edit` additionally advertise `sandbox_permissions` and `justification`; a denied mutation returns the `[sandbox: file access denied under <mode> mode]` marker with the same-turn escalation hint, and an approved retry may stamp a strictly wider mode for that one call. The justification asks the model to use the language of the current user request.
+
+### Failures and recovery
+
+Failures are normalized as `Error: <message>` with a structured code preserved for callers. Stable messages include `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, the duplicate refusal `duplicate read blocked: lines <first>-<last> unchanged, delivered <n> steps ago; that content is still above. Use offset=<next>, or force=true.`, and the image-route refusal `cannot read "<path>" as an image: model "<model>" does not declare image input; switch to an image-capable model to read images`. `FS_NOT_OBSERVED` is normalized to `cannot modify "<path>": file has not been read — read the file, then retry`, independent of whether the policy or provider rejected the operation; `FS_STALE_VERSION` retains the provider's reason and appends `— re-read the file, then retry`. After the reread confirms absence, `edit` reports `FS_NOT_FOUND` instead of repeating a stale remedy, while `write` uses guarded creation.
+
+With `readRepair` enabled (the default), `read` repairs its measured addressing failures instead of erroring: a 0-based or otherwise invalid `offset` reads from line 1, a non-positive or over-cap `limit` lands on the configured cap, a start past the file's end reads the last window of the requested length (an empty file returns the empty window), and a missing path is re-anchored through the `fs-edit-repair` engine — a unique match from this session's prior successful path arguments, then a unique directory-tree completion, each verified present. Disclosure is minimal: the two argument normalizations are stated once per session in a `(repair: …)` line after the footer, because the delivered window and its footer already carry the effective range; a re-anchored path is stated every time, because the corrected path is a new fact; and the tail anchor states nothing.
+
+With `readRepair.duplicate.enabled`, a read fully covered by this session's recent window of the same file version is refused: it fails with `duplicate read blocked: …`, naming the unchanged range, the steps since, and the two ways on (`force: true`, or continuing at the offset after the delivered range). The forgetting rule keeps legitimate re-reads — a mutating tool committed for the file, a compaction replaced the surface, or more than `maxSteps` steps passed since the recorded window. With `readRepair.completion.enabled`, a window that starts inside a construct gains the line that opened it, and one that ends inside a construct gains the following lines that close it; neither boundary is stated, because the added lines carry their own numbers and the footer counts the window that was delivered. Completion never modifies, reorders, or drops a delivered line, adds no opening line when the opener lies outside the searched range, and appends nothing when no closure is provable within `maxLines`. A window whose construct runs to the end of the file is served unchanged.
+
+When an `edit` fails because its target is absent (confirmed by a stat), the engine re-anchors the edit to a verified path — a unique match from this session's prior successful path arguments, then a unique directory-tree completion — applies it through the same guarded seam, and discloses the substitution in a `(repair: …)` line; a genuine stale-version failure (target present) keeps its own remedy, and a refusal on the repaired path (unread target, sandbox denial) surfaces as-is. A `write` that creates a file at a path similar to an existing one appends a `(hint: …)` line naming that path — creation at the requested path is legitimate, so the write itself is never rewritten.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the tool suite and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The tools are the executor; policy is an event gate. The tools inject no policy service and inspect no cache — each mutation asks the single intent slot for its guard through `ctx.waterfall`, and each operation emits `fs/observed` only after it succeeded. Reads do exactly one provider `stat` (type and size routing plus the observed version); mutations do none, because the guard comes from the intent slot and the provider re-checks under its lock.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config`, tool composition, `read_image` attachments gate |
+| [`src/read.ts`](src/read.ts) | `read` executor: one stat, streaming decision, window build, observation |
+| [`src/read-image.ts`](src/read-image.ts) | `read_image` executor: route and media-type gates, bounded bytes, attachment save |
+| [`src/write.ts`](src/write.ts) | `write` executor: intent waterfall, atomic write, observation |
+| [`src/edit.ts`](src/edit.ts) | `edit` executor: intent waterfall, literal edit, observation |
+| [`src/read-render.ts`](src/read-render.ts) | Cordis-free windowing and envelope formatting |
+| [`src/structure.ts`](src/structure.ts) | Fence, bracket, and indentation analysis of window boundaries |
+| [`src/completion.ts`](src/completion.ts) | Structural completion: head and tail assembly over the window's neighbouring lines |
+| [`src/sandbox.ts`](src/sandbox.ts) | Escalation API shared by `write`/`edit`: policy resolution and denial-marker mapping |
+| [`src/error.ts`](src/error.ts) | Stable model-facing diagnostics for guarded-mutation failures |
+
+### Per-tool flow
+
+All four tools share one flow shape: resolve the path with the calling session's cwd, run the applicable gate, perform exactly one provider operation, and emit `fs/observed` only after success. `read` and `read_image` pay one `stat` for type and size routing; `write` and `edit` pay none because their guard comes from the intent slot, and provider failures surface as typed `FsError` results. The per-tool executors live in `src/read.ts`, `src/read-image.ts`, `src/write.ts`, and `src/edit.ts`.
+
+Window completion reads the file again for the lines on each side of the window: the preceding lines whenever the window starts after line 1, and the following lines only when the window ends inside an open construct. Both fetches are capped at `readRepair.completion.maxLines` lines and never alter the window's own lines.
+
+### Observation and concurrency
+
+`fs/observed` fires after the operation succeeded via a plain `ctx.emit`; a listener is contractually a synchronous, side-effect-only recorder, so async or fallible observation does not belong on this event. `read` opts into concurrent scheduling because its only mutation is the synchronous version recorder; recorder races fail closed when a later `write` or `edit` re-checks the version under its target lock, and both mutation tools remain exclusive.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the tools to the contract, backends, and policy they compose with.
+
+- [Filesystem subsystem](../../../docs/subsystems/filesystem.md) — exhaustive provider contract, policy events, and error taxonomy.
+- [dsh-fs](../fs/README.md) — the `ctx.fs` contract these tools consume.
+- [fs-local](../fs-local/README.md) — the host-filesystem backend these tools run against.
+- [fs-sandbox](../fs-sandbox/README.md) — the sandbox-enforcing backend that adds the escalation fields.
+- [fs-observation-policy](../fs-observation-policy/README.md) — the policy plugin that guards mutations through the `fs/*` events.
+- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs) — the exhaustive schemas this package registers.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+At assembly time, each guidance section checks `ctx.tools.get(name, scope)` and renders only while its tool is visible to that agent. The write paragraph recommends edit only while edit is visible. The text below is unchanged when all three tools are available; restrictions, their removal, and tool registration changes take effect on the next assembly. The same check works for direct agent restrictions and subagent `toolFilter`, including PTC capabilities behind `run_code`. The read-before-mutation sentences in write/edit describe the observation policy, not a requirement to invoke the tool named `read`. They remain when `read` is hidden: the policy still guards mutations, and another observing operation, such as `str_replace_editor` with `command: view`, can establish the same file observation. Tool visibility does not disable that precondition.
+
+##### Read guidance
+
+```markdown
+Use the read tool — not shell commands like cat — to inspect text files. Use offset and limit to continue reading large files.
+```
+
+##### Write guidance
+
+```markdown
+Read an existing file before overwriting it with write (the default fs-observation-policy requires it) and prefer edit for targeted changes.
+```
+
+##### Edit guidance
+
+```markdown
+Read a file before editing it (the default fs-observation-policy requires it), unless you just created or edited it in this session.
+```
+
+#### Token effect
+
+Guidance cost follows the visible tools and their applicable cross-tool recommendations.
+
+#### KV Cache effect
+
+Prefix-stable while the visible tool set, plugin scope, and guidance text are unchanged. Restrictions or plugin lifecycle changes may invalidate reuse from the first changed section.
+
+### Tool schemas
+
+#### What the model sees
+
+The model sees the generated [`read`, `read_image`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. The image tool appears only while a durable attachment store is mounted; its schema is route-independent, and the strict gate refuses at execution. Scoped tool restrictions can remove any definition for one agent.
+
+#### Token effect
+
+Fixed schema cost on every request in that tool view.
+
+#### KV Cache effect
+
+Prefix-stable while the visible tool definitions and order are unchanged. Registration lifecycle or scoped restrictions may invalidate reuse from the first changed schema token.
+
+### Read result
+
+#### What the model sees
+
+A successful read is exactly `<path><displayPath></path>`, newline, `<type>file</type>`, newline, `<content>`, numbered lines as `<lineNumber>: <text>`, a blank line, one footer, and `</content>`. The footer is exactly `(Output capped. Showing lines <start>-<end>. Use offset=<next> to continue.)`, `(Showing lines <start>-<end> of <total>. Use offset=<next> to continue.)`, or `(End of file - total <total> lines)`. A long line ends exactly `... (line truncated to <max> chars)`. When a read states a repair, exactly one `(repair: <what>)` line follows the footer. A missing read still returns `FS_NOT_FOUND`, but it records confirmed absence for the calling session; after an externally deleted file is re-read, a retried `write` can safely recreate it through the provider's no-replace guard.
+
+#### Token effect
+
+Read output is capped by `readLimit`, `readMaxLineLength`, and `readMaxBytes`; the retained call and result are resent until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Image read result
+
+#### What the model sees
+
+A successful `read_image` returns `<path><displayPath></path>`, `<type>image</type>`, and a `<content>` envelope naming the media type, normalized dimensions, and byte size, followed by the image itself as a native image block. The result is logged with its durable reference before the next model request.
+
+#### Token effect
+
+The image is billed on every later request until compaction. Each call is independently bounded by the attachment store's `maxImageBytes`/`maxImagePixels`/`maxImageDimension`; repeated successful calls accumulate history, and content addressing deduplicates only the stored bytes, not the per-request token cost.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Write and edit results
+
+#### What the model sees
+
+Write returns the exact five-line envelope `<path><displayPath></path>`, `<type>file</type>`, `<content>`, `Created file` or `Updated file`, then `</content>`. Edit returns exactly `The file <displayPath> has been updated successfully.` or, for `replace_all`, `The file <displayPath> has been updated. All occurrences were successfully replaced.` The full write or replacement text remains in the assistant tool-call arguments.
+
+#### Token effect
+
+Success text is small, but large mutation arguments and any result are resent until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Tool errors
+
+#### What the model sees
+
+Failures are normalized as `Error: <message>`. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to <max>`, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "<path>": not found`, `cannot read "<path>": not a regular file`, `offset <offset> is out of range for "<path>" (<total> lines)`, `cannot read "<path>": the <ext> extension does not declare a supported image format; read_image accepts PNG/JPEG/WebP/GIF files, including extension-less files in those formats`, `cannot read "<path>": the file content is not a supported image format; read_image accepts PNG/JPEG/WebP/GIF`, `cannot read "<path>": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image; the file may be truncated or corrupt`, `cannot read "<path>" as an image: model "<model>" does not declare image input; switch to an image-capable model to read images`, and the mismatch repair `cannot read "<path>": the <ext> extension declares <type>, but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats` (an extension-less mismatch reports `cannot read "<path>": the file signature claims <type>, but the bytes decode as a different image format; the file may be corrupt`). A failed 16-bit conversion reports `cannot read "<path>": the 16-bit PNG could not be converted to the normalized 8-bit sRGB form; convert it to an 8-bit PNG/JPEG/WebP and retry`. Provider and policy templates are quoted in their package READMEs. The model-facing error wrapper normalizes every `FS_NOT_OBSERVED` source to `cannot modify "<path>": file has not been read — read the file, then retry`; `FS_STALE_VERSION` keeps the provider's reason and adds `— re-read the file, then retry`. Both retain the structured error code and original cause. After that reread confirms absence, `edit` reports `FS_NOT_FOUND` instead of repeating a stale remedy, while `write` uses guarded creation.
+
+#### Token effect
+
+Only a failing call adds these retained tokens.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the tool suite is a poor fit or needs special operational care. They are current package constraints, not a general filesystem comparison or a task backlog.
+
+- **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling `dsh-tool-fs-search` package supplies ripgrep-backed `glob` and `grep` rather than extending the filesystem seam.
+- **`read` handles UTF-8 text files only** — images use the separate `read_image` tool; PDF, audio, and video remain deferred. A directory target is `FS_NOT_REGULAR_FILE`.
+- **Extension-declared media type** — an extension selects the declared type and the attachment store's magic-byte validation stays authoritative; a correctly formatted image under a wrong extension is refused with the rename remedy rather than sniffed. Only a path with no extension is identified from its file signature.
+- **Object paths re-enter source admission** — `read_image` on a normalized attachment object re-admits its bytes as a new source, so a deployment whose `maxImageBytes`/`maxMessageImageBytes` sit below the normalized-image byte budget can refuse an object path that `ctx.attachments.readImage` still serves; shipped defaults keep the normalized budget (4 MiB) far under the source caps (20 MiB).
+- **Inline image preview rides the UI composition** — the tool-result card renders the image through the browser's `tool.call.images` slot, which the attachment presentation plugin fills; a UI without that plugin shows the result's envelope text instead.
+- **No attachment-region tool** — an agent may crop an image through another available tool when it has a filesystem path; a pasted or dragged image without a path cannot be re-read at higher resolution.
+- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no timeout budget; cancellation rides `exec.signal` only ([provider rationale](../README.md)).
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. This model-facing adapter has no independent lifecycle stream; execution relations are owned by the capability seam it calls.