dsh-hashline-edit 0.1.1 → 0.2.1

package/README.md

@@ -2,9 +2,9 @@
 
 Hash-anchored file editing for [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) on Windows.
 
-`dsh-hashline-edit` is a dsh bundle that shadows the host's built-in `read` and `edit` tools with hashline equivalents and adds `undo_last_edit`. Every line a served read shows carries a stable 4-character base62 anchor (`A–Z`, `a–z`, `0–9`) derived from the file's canonical path and the line's content. An edit names two anchors and new text; it never re-types existing code. Anchors for unchanged lines stay stable across edits, and every successful edit returns fresh anchors for the changed lines, so chained edits need no re-read.
+`dsh-hashline-edit` is a dsh bundle that shadows the host's built-in `read` with hash-anchored output, registers `apply_patch` as the only file-mutation entry point, and adds `undo_last_edit`. The native `write`/`edit`/`str_replace_editor` surface is hidden; there is no pi host support, because this package targets DeepSeek Harness only. Every line a served read shows carries a stable 4-character base62 anchor (`A–Z`, `a–z`, `0–9`) derived from the file's canonical path and the line's content. An `apply_patch` hunk either names served anchors or matches file content; the model never re-types existing code. Anchors for unchanged lines stay stable across edits, and every successful `apply_patch` call returns fresh anchors for the changed lines, so chained calls need no re-read.
 
-The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-edit) v2.16.0 hashline engine (MIT). The `dsh/` tree is this repository's DeepSeek Harness host layer: tool registration, filesystem bridge, encoding governance, prompt guidance, shell integration, write integration and telemetry. See [`dsh/README.md`](dsh/README.md) for the host-layer map.
+The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-edit) v2.16.0 hashline engine (MIT), carried as an internal engine; the pi host integration has been removed. The `dsh/` tree is this repository's DeepSeek Harness host layer: tool registration, filesystem bridge, UTF-8-only admission, prompt guidance, shell integration, write integration and telemetry. See [`dsh/README.md`](dsh/README.md) for the host-layer map.
 
 ## Requirements
 
@@ -13,7 +13,7 @@ The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-e
 | OS | Windows — this branch targets Windows only (see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)) |
 | Node.js | ≥ 24.0.0 |
 | pnpm | 12.x |
-| DeepSeek Harness | plugin-capable build; the repository is developed against `@deepseek-ai/dsh-*@0.2.1-rc.2` |
+| DeepSeek Harness | plugin-capable build; the repository is developed against `@deepseek-ai/dsh-*@0.2.2-rc.1` (host packages are declared as peer dependencies) |
 
 ## Install
 
@@ -36,7 +36,7 @@ For a tarball, pack first and add the archive:
 
 ```sh
 pnpm pack
-dsh plugin add ./dsh-hashline-edit-0.1.0.tgz
+dsh plugin add ./dsh-hashline-edit-0.2.1.tgz
 ```
 
 The bundle ships `lib/index.js` plus `lib/types/**`; `prompts/` must sit next to `lib/` in the installed package (it is in `files`). Guidance override files are materialized under `<DSH_HOME>/plugins/dsh-hashline-edit/guidance/` and are shared between profiles.
@@ -55,7 +55,7 @@ p9rX│  return total;
 a1bX│}
 ```
 
-Copy only the 4 characters before `│` into `anchor_from` / `anchor_to`. An edit targets an inclusive range and returns a diff whose modified and context rows carry fresh anchors:
+Copy only the 4 characters before `│` into `anchor_from` / `anchor_to`. An `apply_patch` identity hunk targets an inclusive served range; a successful call returns a diff whose modified and context rows carry fresh anchors:
 
 ```text
 - szJx│  let total = 0;
@@ -81,51 +81,61 @@ read({
     | { around_anchor: string; radius?: number }   // radius defaults to 10
   >,
   mode?: "served" | "verbatim", // default "served"
-  encoding?: string,            // reopen a non-UTF-8 file, e.g. "gbk", "big5", "shift_jis", "utf16le"
 })
 ```
 
-- **Served mode** returns one `HASH│content` row per line and records every shown row as a lease for this session. A windowed read also includes a `[Lines A-B of N total]` page header. Every row shown is usable by one subsequent edit, even when the windows are far apart.
-- **Verbatim mode** returns the same page as plain text with no anchors and serves nothing; an edit cannot target those lines.
-- A small requested window may widen to its enclosing function, method, class, section or paragraph; a `[widened …]` note names the block that was served. Expansion applies in both modes.
-- `offset`/`limit` and `windows` are page requests, not anchors: only `served` output grants edit leases.
+- **Served mode** returns one `HASH│content` row per line and records every shown row as a lease for this session. A windowed read also includes a `[Lines A-B of N total]` page header. Every row shown is usable by one subsequent `apply_patch`, even when the windows are far apart.
+- **Verbatim mode** returns the same page as plain text with no anchors and serves nothing; an `apply_patch` identity hunk cannot target those lines.
+- A small requested window — up to 61 lines after folding — may widen to its enclosing function, method, class, section or paragraph; a `[widened …]` note names the block that was served. Expansion applies in both modes. Languages: TypeScript/TSX, Python, Go, Rust, Java and Vue through pinned tree-sitter wasm grammars (fetched lazily and verified against a committed SHA-256), plus Bash through the existing `unbash` parser (no wasm). Vue widens a top-level `template`/`script`/`style` block without parsing embedded JS/TS. SQL is not supported: real migrations largely fail to parse and `.tql` is a Java template, not SQL (see [`docs/spec/sql-vue-feasibility-gate.md`](docs/spec/sql-vue-feasibility-gate.md)).
+- `offset`/`limit` and `windows` are page requests, not anchors: only `served` output grants mutation leases.
 
-### `edit`
+### `apply_patch`
 
-```ts
-edit({
-  file: string,                 // one text file per call
-  edits: [{
-    anchor_from: string,        // bare 4-char anchor of the first range line (inclusive)
-    anchor_to: string,          // bare 4-char anchor of the last range line (inclusive)
-    text?: string,              // by-value content; "" deletes an in-place range
-    text_ref?: {                // by-reference content from a served span
-      anchor_from: string,
-      anchor_to: string,
-      file?: string,            // another served file (foreign-source copy/cut)
-      mode: "copy" | "cut",     // required: copy keeps the source, cut retires the span
-    },
-    at?: "in-place" | "before" | "after",  // default "in-place"
-  }],
-  mode?: "general" | "literal", // "general" refuses served-row echoes; "literal" declares them intended
-})
-```
-
-Each item carries exactly one of `text` or `text_ref`; supplying both or neither is refused. `before`/`after` insert at the range boundary and require a single-line resolved target. A foreign-source `cut` writes both files as one correlated transaction; `undo_last_edit` reverts both members. An edit never silently rewrites submitted text — a refused edit writes nothing.
+The only file-mutation entry point. One call carries one Codex patch document and commits the whole
+batch as one correlated transaction (pre-mirror, undo rows, deterministic member order, all-or-nothing
+rollback, then per-file store commits).
 
-The result is the core's unified diff with fresh anchors for the changed lines, so the next edit can chain from them without a `read`. The host's built-in `write` is not replaced: the plugin guards it against served-row echoes and appends an anchored auto-read so following edits can use its output.
+```text
+*** Begin Patch
+*** Update File: src/config.ts
+@@
+-  retries: 3,
++  retries: 5,
+*** Add File: src/new.ts
++export const x = 1;
+*** End Patch
+```
 
+Addressing works in two modes, and one patch may mix them:
+
+- **Fragment hunks** use the official Codex syntax. `@@` starts the search window at the file start;
+  `@@ <one context line>` moves the window after that line's unique match. Body lines are
+  ` ` (context), `-` (remove) and `+` (add). Matching is byte-exact and must be unique: zero or
+  multiple matches reject the whole call and serve the candidate rows back.
+- **Identity hunks** use the `@@<a>` / `@@<a>-<b>` extension: two inclusive 4-char anchors from rows
+  this session served. The body is `+` lines only; an empty body deletes the span. A stale, unknown
+  or foreign anchor is rejected with the file's current rows served.
+- **Reference hunks** `*** Copy From: <path> <a>-<b>` / `*** Cut From: <path> <a>-<b>` take the
+  bytes of another served span; a cut also retires the source span in the same transaction.
+- **Lifecycle** `*** Add File:`, `*** Delete File:` and `*** Move to:` join text edits in the same
+  transaction and the same undo record. `*** End of File` pins a hunk to the file tail.
+
+`@@` followed by a space is Codex's context mode; `@@` immediately followed by four anchor
+characters is identity mode. Any rejection leaves every file byte-identical and reports every
+independent problem with its patch line number and `[E_*`] code. Success returns a file-level summary
+(A/M/R/D) followed by fresh `HASH│content` anchors for every changed line, so the next call can chain
+without a `read`. To replace a whole file, use one `*** Update File:` identity hunk spanning every served line.
 ### `undo_last_edit`
 
 ```ts
 undo_last_edit({ path: string })
 ```
 
-Restores the previous file content, BOM, line endings and original anchors from a snapshot-pinned undo record. The record survives agent restarts. A file changed externally after the edit is refused with `[E_UNDO_STALE]`. A correlated cut's undo restores every member of the transaction, not only the named path.
+Restores the previous file content, BOM, line endings and original anchors from a snapshot-pinned undo record. The record survives agent restarts. A file changed externally after the patch is refused with `[E_UNDO_STALE]`. A correlated cut's undo restores every member of the transaction, not only the named path.
 
 ## Shell view
 
-The plugin installs a `tools/post-execute` listener for the host's `pwsh` and `bash` tools. When the command is a whitelisted read-only file view, the captured stdout is replaced with the aligned file's `HASH│content` rows, and those rows are served (leased) exactly like a read — a following `edit` can use them with no re-read.
+The plugin installs a `tools/post-execute` listener for the host's `pwsh`, `bash` and built-in `grep` tools. When the command is a whitelisted read-only file view, the captured stdout is replaced with the aligned file's `HASH│content` rows, and those rows are served (leased) exactly like a read — a following `apply_patch` can use them with no re-read. A built-in grep result whose matches are proven against disk is served the same way (see the table below).
 
 | Command shape | Served as |
 | --- | --- |
@@ -134,36 +144,24 @@ The plugin installs a `tools/post-execute` listener for the host's `pwsh` and `b
 | `Get-Content <file> \| Select-Object -Skip N -First M` (either order) | disk lines N+1 through N+M |
 | `Select-String <pattern> <file>` | the matched lines, with their line numbers |
 | `rg <pattern> <file>` (explicit single file, no switches) | the matched lines, with their line numbers |
+| built-in `grep` (`@deepseek-ai/dsh-tool-fs-search`) | the matched lines grouped per file, each row `HASH│content` |
 
-Alignment is strict: stdout lines are mapped to 1-based disk line numbers with a monotonic, unique match (search output's own line numbers are used as hints). Every served view is prefixed with the shared `[Bash view: <file> (lines a-b of N total)]` page header, so the positions the raw output used to name are not lost. Anything the view cannot prove — an unknown pipeline, a statement separator (`;`), a variable path (`$f`), a wildcard, formatted output, a truncated capture, a failed command — passes through byte-for-byte. The hook never guesses and never serves the wrong occurrence of a duplicated line.
-
-## Encoding governance
-
-The dsh host reintroduces a VS Code-style encoding model on top of the UTF-8 core. Read admission is deterministic:
-
-1. explicit `read({ encoding })` hint;
-2. BOM sniff (UTF-8, UTF-16LE/BE and UTF-32LE/BE BOMs);
-3. strict UTF-8 decode;
-4. the `autoGuessEncoding` gate (off by default);
-5. Top-3 candidate preview on refusal, e.g. `not readable UTF-8 text — top guesses: gbk("你好"); try read({encoding: "<encoding>"}) or enable autoGuessEncoding to decode automatically`.
-
-Text encodings offered to the model are `gbk`, `big5`, `shift_jis`, `euc-kr`, `windows-1251` and `utf16le` (case-insensitive), in addition to UTF-8 and BOM-detected Unicode.
+The grep view applies the host's spill policy: at most 250 matches and at most 12,500 inline tokens (the host estimate `ceil(chars / 4) + 4`). A result over either cap, a failed call, a forged or stale match line, or non-ascending coordinates passes through byte-for-byte with no lease.
 
-A governed read records the file's encoding state (encoding, BOM, line ending, file version). Both the `edit` lane and the built-in `write` lane invert that state on save through a single codec:
-
-- a GBK file edited through `read` → `edit` stays GBK on disk (byte comparison, not text equality);
-- a UTF-16LE file with a BOM keeps its BOM and its byte order;
-- a UTF-8 BOM file round-trips byte-for-byte.
+Alignment is strict: stdout lines are mapped to 1-based disk line numbers with a monotonic, unique match (search output's own line numbers are used as hints). Every served view is prefixed with the shared `[Bash view: <file> (lines a-b of N total)]` page header, so the positions the raw output used to name are not lost. Anything the view cannot prove — an unknown pipeline, a statement separator (`;`), a variable path (`$f`), a wildcard, formatted output, a truncated capture, a failed command — passes through byte-for-byte. The hook never guesses and never serves the wrong occurrence of a duplicated line.
+## Encoding: UTF-8 only
 
-When a legacy code page cannot represent the new text, the save degrades to UTF-8 and appends a model-facing warning instead of writing lossy bytes:
+The dsh host reads and writes UTF-8. Read admission is one rule with one exemption:
 
-> Warning: the file was written as UTF-8 because the recorded gbk encoding cannot represent the edited text. Re-read the file before the next edit.
+1. a leading UTF-8 BOM (`EF BB BF`) is stripped, so it never reaches an anchor;
+2. the remaining bytes must be strict UTF-8.
 
-Undo also inverts the recorded state for every member of a correlated cut — but only when a governed read recorded that file's encoding state in the same plugin process. Without a recorded state, undo keeps the core's UTF-8 behavior; on a legacy file that can surface as `[E_UNDO_STALE]` rather than a guessed re-encode.
+A file that is not valid UTF-8 is refused with `[E_UNSUPPORTED_FILE]` naming the file path and telling the model to ask the user how to handle it — for example a GBK-encoded source file or a BOM-less UTF-16LE file. The host does not guess a code page, offers no reopen-with-encoding parameter, keeps no encoding/BOM memo, and does not re-encode on save. UTF-16/UTF-32 BOMs are still recognized by kind detection: they are named in the refusal (e.g. `UTF-16LE encoded text`) instead of being decoded. Convert a non-UTF-8 file with an external tool before editing it here.
 
+`apply_patch` and `undo_last_edit` speak the same contract: they write UTF-8, and every file this plugin serves is UTF-8. The built-in `write` integration keeps the same contract for a profile that deliberately keeps `write` visible.
 ## Sandbox behavior
 
-`edit` and `undo_last_edit` carry the host's optional escalation fields `sandbox_permissions` and `justification` only when a confining filesystem backend is mounted. `dsh/sandbox.ts` mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller: it validates the field pairing, repeats the standing mode without approval, and resolves a strictly wider mode through the host's approval channel before touching the filesystem. A provider `FS_SANDBOX_DENIED` error is mapped to the standard model-facing denial marker plus escalation hint; other errors pass through unchanged.
+`apply_patch` and `undo_last_edit` carry the host's optional escalation fields `sandbox_permissions` and `justification` only when a confining filesystem backend is mounted. `dsh/sandbox.ts` mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller: it validates the field pairing, repeats the standing mode without approval, and resolves a strictly wider mode through the host's approval channel before touching the filesystem. A provider `FS_SANDBOX_DENIED` error is mapped to the standard model-facing denial marker plus escalation hint; other errors pass through unchanged.
 
 ### Host-side `0xC0000142` workspace-write finding
 
@@ -184,7 +182,7 @@ The M3/M4 smoke runs therefore used `DSH_PERMISSION_MODE=danger-full-access`; th
 | `pnpm run lint` | `oxlint .` + `knip --max-issues 0` |
 | `pnpm run verify` | lint + format + typecheck + Windows coverage |
 
-The build enforces its own packaging contract: host packages stay external, the pi utility package is aliased to `dsh/host-compat.ts` (the bundle must not reference pi), and no bare import outside the allowlist can slip in. See [`dsh/README.md`](dsh/README.md#build-and-packaging).
+The build enforces its own packaging contract: host packages stay external, the bundle must not reference pi (there is no pi host integration), and no bare import outside the allowlist can slip in. See [`dsh/README.md`](dsh/README.md#build-and-packaging).
 
 ## Error and warning codes
 
@@ -195,7 +193,7 @@ Every refusal carries a bracketed code; `src/domain-errors.ts` is the source of
 | `[E_ACCESS]` | The filesystem denied access to the target path. |
 | `[E_BAD_PAYLOAD]` | Malformed or unknown tool payload; nothing is written. |
 | `[E_BATCH_ABORT]` | A batch item failed; the whole batch was not applied. |
-| `[E_EMPTY_RANGE]` | The edit would empty a non-empty file; use `write`. |
+| `[E_EMPTY_RANGE]` | The patch would empty a non-empty file; use `write`. |
 | `[E_FOREIGN_ANCHOR]` | The anchor belongs to a different file. |
 | `[E_INTERNAL_INVARIANT]` | An internal invariant was violated. |
 | `[E_LARGE_FILE]` | The file exceeds the served line or byte budget. |
@@ -203,37 +201,40 @@ Every refusal carries a bracketed code; `src/domain-errors.ts` is the source of
 | `[E_MALFORMED_ANCHOR]` | The anchor token cannot be parsed. |
 | `[E_NOOP_LOOP]` | Repeated identical no-op edits; refused with the current range served. |
 | `[E_NOT_FOUND]` | The target file does not exist or is unreachable. |
+| `[E_PATCH_SYNTAX]` | The apply_patch text is not valid syntax; nothing is written. |
 | `[E_STALE_ANCHOR]` | A boundary anchor no longer resolves against the file. |
-| `[E_STALE_RANGE]` | The served range changed between serve and edit. |
+| `[E_STALE_RANGE]` | The served range changed between serve and patch. |
 | `[E_SUSPICIOUS_TEXT]` | The replacement reproduces served anchor text (a copied `HASH│` echo). |
 | `[E_TARGET_LOST]` | The target line identity can no longer be resolved. |
 | `[E_UNDO_REVERT_FAILED]` | A correlated revert failed mid-way; a repair run finishes it. |
 | `[E_UNDO_STALE]` | The undo record is stale relative to the file. |
 | `[E_UNDO_UNAVAILABLE]` | There is no undo history for the path. |
+| `[E_UNIQUE_MATCH]` | A fragment hunk matched zero or multiple places; candidates are served back. |
 | `[E_UNKNOWN]` | An unclassified failure; the message carries the cause. |
 | `[E_UNKNOWN_ANCHOR]` | The anchor was never served in this session. |
-| `[E_UNSUPPORTED_FILE]` | Binary, image or directory targets are not editable text. |
+| `[E_UNSUPPORTED_FILE]` | Binary, image or directory targets are not editable text; a non-UTF-8 file is refused with its path and an instruction to ask the user how to handle it. |
 | `[E_UNVERIFIED_RANGE]` | The range interior cannot be verified (never served). |
-| `[W_LITERAL_BYPASS]` | Literal `HASH│` bytes were written through `edit` and accepted with a warning. |
-| `[W_NEVER_SERVED_SHAPE]` | A never-served hint was attached to an accepted edit. |
-| `[W_NOOP]` | The edit produced no content change and was accepted as a no-op. |
-| `[W_NOOP_INSERT]` | An insert-shaped edit produced no change. |
+| `[W_LITERAL_BYPASS]` | Literal `HASH│` bytes were written through `apply_patch` and accepted with a warning. |
+| `[W_NEVER_SERVED_SHAPE]` | A never-served hint was attached to an accepted patch. |
+| `[W_NOOP]` | The patch produced no content change and was accepted as a no-op. |
+| `[W_NOOP_INSERT]` | An insert-shaped hunk produced no change. |
 | `[W_REVERSED_ANCHORS]` | Boundaries were reversed and healed. |
 | `[W_SERVED_PREFIX_MISMATCH]` | A served prefix does not match; fresh rows were served. |
 | `[W_UNICODE_LITERAL]` | A Unicode literal in the payload looks like a copied anchor. |
 
+Range-family rejections render their current-row evidence exactly once: the headline plus one `Current range (fresh read):` block. A single-line anchor pair (`anchor_from` equals `anchor_to`) is listed once, and the distinct-anchor lists de-duplicate. `[E_UNKNOWN_ANCHOR]` and `[E_FOREIGN_ANCHOR]` also name each distinct anchor once.
+
 ## Current limitations
 
-- **`ctx.fs` is read-only.** The read path can consume a mounted `ctx.fs` through the `CoreReadIo` port, but the mutation seams — `writeAtomic`, the edit engine and undo — remain local-only. `edit` and `undo_last_edit` fail closed with `E_NOT_FOUND` when the target is reachable only through `ctx.fs`.
-- **`edit`, `undo_last_edit` and `writeAtomic` are local-only.** A remote or sandboxed backend needs target-keyed store state and versioned writes; that is deferred to M6 (see [`dsh/README.md`](dsh/README.md#ctxfs-bridge-m5-read-only)).
-- **Undo preserves a legacy encoding only with recorded state.** The encoding memo lives in the plugin process and is version-gated; a fresh process or a file never governed-read in that process has no state to invert, so undo keeps the core's UTF-8 behavior.
+- **Mutation stays on the local `node:fs` seam.** The read path consumes a `CoreReadIo` port (local or mounted `ctx.fs`), but `writeAtomic`, the `apply_patch` engine and undo remain local-only. `apply_patch` and `undo_last_edit` fail closed with `E_NOT_FOUND` when the target is reachable only through `ctx.fs`. A full mutation bridge needs target-keyed store state: the host's `ctx.fs` already exposes versioned writes in `0.2.2-alpha.3`, but the snapshot/lease store still keys on absolute paths and local stat identity (M6, see [`dsh/README.md`](dsh/README.md#ctxfs-deferral-m6)).
+- **UTF-8 only.** Non-UTF-8 files are refused on read and must be converted with an external tool; the plugin does not decode legacy code pages, does not re-encode on save, and keeps no encoding state.
 - **Windows-only.** The branch targets Windows; POSIX-only suites are excluded in `vitest.config.windows.ts`, and that exclusion list must shrink, never grow (see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)).
 
 ## Repository layout
 
 | Path | Role |
 | --- | --- |
-| `src/` | upstream pi-better-edit core (semantic source; synced from upstream) |
+| `src/` | hashline engine core derived from pi-better-edit (semantic source; upstream fixes are picked selectively, see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)) |
 | `dsh/` | DeepSeek Harness host layer — the only code that differs from upstream; map in [`dsh/README.md`](dsh/README.md) |
 | `dsh/UPSTREAM.md` | upstream sync cursor, policy and Windows adaptation patches |
 | `dsh/baseline/` | milestone measurement baselines (M0–M5) |
@@ -242,7 +243,7 @@ Every refusal carries a bracketed code; `src/domain-errors.ts` is the source of
 
 ## Upstream attribution
 
-The hashline engine is [**pi-better-edit**](https://github.com/Rianico/pi-better-edit) by [Rianico](https://github.com/Rianico), used under the MIT license and synced at upstream `673964c` (`v2.16.0`; see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)). This repository keeps the upstream history and tree; the `dsh/` adapter is ours, is never merged upstream, and contains only host wiring.
+The hashline engine is [**pi-better-edit**](https://github.com/Rianico/pi-better-edit) by [Rianico](https://github.com/Rianico), used under the MIT license and synced at upstream `673964c` (`v2.16.0`; see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)). This repository is a self-maintained fork: upstream is the semantic source of the hashline core and a place to pick bug-fix commits from, recorded in `dsh/UPSTREAM.md`; there is no commit-for-commit sync promise. The `dsh/` adapter is ours, is never merged upstream, and contains only host wiring.
 
 ## License
 

package/cordis.patch.yml

@@ -1,8 +1,8 @@
 # dsh-hashline-edit bundle patch: mount the host-plane plugin row.
 # Installed via `dsh plugin --profile <name> add dsh-hashline-edit` (or a
-# profile's bundle list). The plugin hooks agent/created and shadows the
-# built-in read/edit tools on each agent's own scope layer, so no preset
-# editing or user config is needed.
+# profile's bundle list). The plugin hooks agent/created, shadows the built-in
+# read tool, and hides the native write/edit/str_replace_editor surface on each
+# agent's own scope layer, so no preset editing or user config is needed.
 - insert:
     - id: dsh-hashline-edit
       name: dsh-hashline-edit