Merge remote-tracking branch 'origin/master' into pr-265

# Conflicts:
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/rfc/INDEX.md
#	examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl
#	examples/acp-agent/tests/snapshots/skill-load/session.jsonl
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/escalation-approved/session.jsonl
#	examples/sandbox-acp-agent/tests/snapshots/escalation-rejected/session.jsonl
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/src/loop.ts
#	packages/core/tools/README.md
#	packages/core/tools/src/index.ts
#	packages/core/tools/src/schema.ts
#	packages/ui/acp/src/index.ts
#	packages/ui/stdio-agent/README.md

packages/fs/tool-fs/README.md

@@ -49,3 +49,59 @@ The tool passes `exec` (the tool-execution context) as the opaque `actor` on eve
 This is exactly why `read` declares `isConcurrencySafe: () => true` while `write`/`edit` do not: `read`'s only side effect is that synchronous version recorder (same-target concurrent reads race last-writer-wins on the observed version), so the agent loop may run sibling reads in parallel. `write`/`edit` mutate the filesystem and stay exclusive barriers — the provider re-checks the observed version inside its per-target lock before mutating, so a stale read never corrupts (it only forces a re-read via `FS_STALE_VERSION`). See the [parallel tool-call RFC](../../../docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md).
 
 The read rendering (line windowing + output formatting) lives in `src/read-render.ts` (Cordis-free, independently unit-tested); `src/read.ts`/`write.ts`/`edit.ts` are the tool executors and `src/index.ts` composes them.
+
+## Model Experience
+
+### System prompt
+
+**What the model sees**: Every request in this plugin's registration scope receives the independently registered read, write, and edit guidance below. Scoped tool restrictions can hide schemas without removing these sections.
+
+**Token effect**: Fixed guidance cost per request while the plugin is active, even when a restriction hides one or more tools.
+
+#### Read guidance
+
+```markdown
+Use the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.
+```
+
+#### Write guidance
+
+```markdown
+Use the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.
+```
+
+#### Edit guidance
+
+```markdown
+Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.
+```
+
+### Tool schemas
+
+**What the model sees**: The model sees the generated [`read`, `write`, and `edit` schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-fs), with snake_case arguments. Scoped tool restrictions can remove any definition for one agent.
+
+**Token effect**: Fixed schema cost on every request in that tool view.
+
+### 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)`.
+
+**Token effect**: Read output is capped by `readLimit`, `readMaxLineLength`, and `readMaxBytes`; the retained call and result are resent until compaction.
+
+### 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.
+
+### 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`, and `offset <offset> is out of range for "<path>" (<total> lines)`; provider and policy templates are quoted in their package READMEs.
+
+**Token effect**: Only a failing call adds these retained tokens.
+
+## Known Limitations and Deferred Work
+
+- **No directory-listing, glob, grep, or search tools ship** — a deferral of [the tool-schemas RFC](../../../docs/rfc/implemented/feature/2026-06-17-filesystem-tool-schemas.md); `ctx.fs.listDir` serves provider code such as skill discovery but still has no model-facing consumer, so models fall back to `bash`.
+- **`read` handles UTF-8 text files only** — binary-safe reads and PDF/image/multimodal content are deferred; a directory target is `FS_NOT_REGULAR_FILE`.
+- **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no `timeout-policy` budget; cancellation rides `exec.signal` only (the deliberate [fs-family stance](../README.md)).

packages/fs/tool-fs/src/diff.ts

@@ -1,14 +1,6 @@
 /**
- * Result-time contextual-diff computation for the `write`/`edit` tools. Turns a
- * before/after pair of file texts into one {@link FileDiff} per applied hunk —
- * each hunk's `oldText`/`newText` reconstructed from the unified-diff lines with
- * ±{@link DIFF_CONTEXT} surrounding context lines, matching how claude-agent-acp
- * renders an editor inline diff.
- *
- * This is display-only presentation vocabulary (a UI concern), so it lives in
- * the model-facing tool, NOT the `dsh-fs` storage seam — the backend returns
- * only the raw before/after text (storage facts) and the tool computes the diff.
- *
+ * Result-time contextual diff presentation for write and edit. Storage returns before/after
+ * text; this model-facing layer derives one three-line-context card per applied hunk.
  * @module @deepseek-ai/dsh-tool-fs/src/diff
  */
 
@@ -29,18 +21,12 @@ export const DIFF_CONTEXT = 3
 export type FsDiffMeta = { diffs: FileDiff[] }
 
 /**
- * Compute one {@link FileDiff} per hunk between `before` and `after`, each
- * carrying the applied change plus {@link DIFF_CONTEXT} context lines. Returns an
- * empty array when the texts are identical (no hunks). For a scattered
- * `replace_all` edit the patch yields multiple hunks, so multiple `FileDiff`s
- * come back — matching the editor rendering one diff block per site.
+ * Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the
+ * applied change plus {@link DIFF_CONTEXT} context lines. Pure insertions use `oldText: null`,
+ * patch-only no-newline markers are omitted, and scattered replacements remain separate hunks.
  *
- * Each hunk's `oldText` is its `-` (removed) and context lines joined by `\n`;
- * `newText` is its `+` (added) and context lines. A hunk with no old lines
- * (a pure insertion) reports `oldText: null` (nothing to diff against), mirroring
- * the call-time card's new-file convention. The unified-diff "\ No newline at end
- * of file" markers are dropped — they annotate the patch, not file content.
- * @param path - the path stamped on every produced diff (the model-facing `file_path`; the bridge relativizes it).
+ * @param path - the path stamped on every produced diff (the model-facing `file_path`; the
+ *   bridge relativizes it).
  * @param before - the file text before the change (the backend's LF-normalized diff basis).
  * @param after - the file text after the change, on the same basis.
  * @returns one diff per applied hunk, in file order; empty when the texts are identical.
@@ -81,14 +67,10 @@ function isFileDiff(value: unknown): value is FileDiff {
 }
 
 /**
- * Narrow an opaque `tool/result` `meta` back to this tool's {@link FileDiff}
- * hunks, or `undefined` when it is absent/malformed. `presentResult` runs on
- * arbitrary logged `meta` (possibly from an older shape or a hand-edited log), so
- * it validates defensively rather than trusting the payload — a bad `meta` yields
- * `undefined`, and the caller decides the fallback (edit → the generic result
- * rendering; write → an args-derived whole-file diff), never a thrown presenter.
- * @param meta - the opaque `tool/result` meta payload (live or replayed from the session log).
- * @returns the validated non-empty hunk list, or undefined for an absent/empty/malformed payload.
+ * Narrow opaque live or replayed result metadata to non-empty file diffs. Malformed metadata
+ * returns `undefined` so presentation can fall back instead of throwing during replay.
+ * @param meta - result metadata.
+ * @returns validated hunks, or `undefined` for absent or malformed data.
  */
 export function diffsFromMeta(meta: unknown): FileDiff[] | undefined {
   if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined

packages/fs/tool-fs/src/edit.ts

@@ -1,14 +1,7 @@
 /**
- * The model-facing `edit` tool: update an existing UTF-8 text file by replacing
- * literal text, requiring a unique match by default. The tool is the executor:
- * it dispatches the `fs/edit-intent` waterfall to obtain the optional
- * version guard, calls `ctx.fs.editText` directly, and emits `fs/observed`. The
- * default thunk returns `undefined` (unconditional edit of the current content
- * — the bare provider); a policy plugin (`@deepseek-ai/dsh-fs-policy`)
- * occupies the single decision slot, returning `{ version: vObserved }` or
- * throwing `FS_NOT_OBSERVED` for an unread file. The tool stats ZERO times
- * either way; a missing target is reported by the provider as `FS_STALE_VERSION`.
- *
+ * Model-facing literal edit, unique-match by default. It obtains an optional guard from the
+ * single intent slot, calls `ctx.fs.editText` without a separate stat, then records the observed
+ * version; no policy means an unconditional atomic edit.
  * @module @deepseek-ai/dsh-tool-fs/src/edit
  */
 
@@ -96,22 +89,16 @@ export function applyEditTool(ctx: Context): void {
       )
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // The result-time applied-hunk diff (before→after with context lines). An
-      // edit always changes content (parseEditArgs requires old_string to differ
-      // and editText matches at least once), so there is always at least one hunk.
-      // The bridge renders these as an inline diff that supersedes the call-time
-      // snippet; the display path is the model-facing `file_path` (the bridge
-      // relativizes it).
+      // An edit necessarily changes content, so result metadata carries at least one applied hunk.
       const diffs = computeHunkDiffs(input.filePath, outcome.before, outcome.after)
       return {
         content: [{ type: 'text', text: formatEditOutput(target.displayPath, input.replaceAll) }],
         meta: { diffs },
       }
     },
-    // Pure display: a diff card of the literal replacement (old_string →
-    // new_string), derived from the call args. `oldText: old_string || null`
-    // matches claude-agent-acp's Edit arm; new_string is a required arg here, so
-    // it maps straight to newText. A follow-along location points at the file.
+    // Pure display: a diff card of the literal replacement (old_string → new_string), derived
+    // from the call args. `oldText: old_string || null` matches claude-agent-acp's Edit arm;
+    // new_string is a required arg here, so it maps straight to newText.
     presentCall(args): DiffCallView {
       return {
         card: 'diff',
@@ -120,10 +107,8 @@ export function applyEditTool(ctx: Context): void {
         locations: [{ path: args.file_path }],
       }
     },
-    // Result-time display: the applied contextual-diff hunks carried on `meta`.
-    // On success with diffs, a `diff` result card supersedes the call-time
-    // snippet; on error (nothing applied) or malformed meta, fall through to the
-    // generic "updated successfully" rendering.
+    // Applied metadata replaces the call-time snippet; errors or malformed replay metadata use
+    // the generic result rendering.
     presentResult(args, result: ToolResult): DiffResultView | undefined {
       if (result.isError) return undefined
       const diffs = diffsFromMeta(result.meta)

packages/fs/tool-fs/src/index.ts

@@ -1,24 +1,7 @@
 /**
- * The model-facing filesystem tool suite (`read`, `write`, `edit`) over the
- * `ctx.fs` provider seam. This single plugin registers all three tools.
- *
- * ## The tool is the executor; policy is an event gate
- *
- * The tool reads/writes/edits through `ctx.fs` DIRECTLY and owns model-facing
- * concerns only — tool names, JSON schemas, argument validation, prompt
- * sections, read windowing, result formatting. It does NOT inject a policy
- * service. Instead, on each write/edit it dispatches a single-slot waterfall
- * (`fs/write-intent`/`fs/edit-intent`) to obtain the OPTIONAL version guard, and
- * after every read/write/edit it emits `fs/observed` with a plain (unguarded)
- * `ctx.emit`. A policy plugin (`@deepseek-ai/dsh-fs-policy`) occupies the
- * decision slot and listens for `fs/observed` to add observed-state +
- * read-before-edit + version-guarded write/edit; a deployment that loads these
- * tools is expected to also load it. With no policy plugin the waterfalls fall
- * through to their `undefined` default (the unconstrained bare provider) and
- * `fs/observed` is unheard — the tool still functions. This package never
- * imports `node:fs`, `node:path`, or an `@deepseek-ai/dsh-fs-local`
- * implementation.
- *
+ * Model-facing read, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+ * read windows, formatting, and observation events, never a concrete provider. An optional
+ * event policy supplies mutation guards; without one the tools use unconditional provider calls.
  * @module @deepseek-ai/dsh-tool-fs
  */
 

packages/fs/tool-fs/src/read-render.ts

@@ -1,18 +1,7 @@
 /**
- * Cordis-free read rendering for `@deepseek-ai/dsh-tool-fs`: turn a file's
- * decoded text into a bounded, line-numbered window (offset/limit, byte cap,
- * per-line truncation) and format it as the model-facing text block. This is
- * the `read` tool's RENDERING detail — not a storage primitive, not freshness
- * policy — so it lives apart from the tool's I/O and event wiring as a pure,
- * independently-testable module (no cordis, no filesystem).
- *
- * The provider (`ctx.fs.readText`/`streamText`) hands back already-decoded text
- * (UTF-8 validated, binary rejected); {@link buildWindow} only scans that text
- * for newlines and builds the requested window. A capped line buffer means a
- * newline-free giant line can never balloon memory even when streamed.
- * {@link formatReadOutput} turns the resulting {@link FileReadOutcome} into the
- * `<path>/<content>` envelope the model sees.
- *
+ * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
+ * model-facing envelope. Chunk scanning caps the current line, so even one newline-free giant
+ * line cannot grow memory without bound.
  * @module @deepseek-ai/dsh-tool-fs/read-render
  */
 
@@ -113,12 +102,8 @@ function finish(acc: WindowAccumulator, request: ReadWindow, displayPath: string
 }
 
 /**
- * Build a bounded, line-numbered window from a file's decoded text chunks.
- * Accepts an `AsyncIterable<string>` (a chunked `streamText`) or an
- * `Iterable<string>` (a whole-file `readText` wrapped as `[text]`), so one code
- * path serves both. Scans for newlines with a capped line buffer (a newline-free
- * giant line is truncated, never buffered past `request.maxLineLength`),
- * enforces the byte cap, and throws `FS_NOT_FOUND` for an offset past EOF.
+ * Build one window from streamed or whole-file chunks, enforcing line and byte caps and throwing
+ * `FS_NOT_FOUND` when the requested offset is past EOF.
  * @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
  * @param request - the resolved window; the caller has already applied its defaults and caps.
  * @param displayPath - the caller-facing path used in the offset-out-of-range error.

packages/fs/tool-fs/src/read.ts

@@ -1,14 +1,6 @@
 /**
- * The model-facing `read` tool: inspect a UTF-8 text file and return
- * line-numbered content with pagination guidance. The tool is the executor — it
- * stats and reads through `ctx.fs` directly, builds the line window
- * ({@link module:@deepseek-ai/dsh-tool-fs/read-render}), and emits `fs/observed`
- * so a policy plugin (`@deepseek-ai/dsh-fs-policy`) can record the read. With
- * no policy plugin the emit is simply unheard. This module owns the
- * model-facing schema, argument validation, and the read I/O; the rendering
- * (windowing + formatting) lives in `read-render.ts` and the
- * freshness/observation policy is not its concern.
- *
+ * Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
+ * streams large or size-unknown files, renders a bounded window, then emits the observation.
  * @module @deepseek-ai/dsh-tool-fs/src/read
  */
 
@@ -105,9 +97,7 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
 
       // One stat: type check + size routing + the version recorded as observed.
-      // A writer racing between this stat and the read can at worst make a LATER
-      // guarded edit spuriously FS_STALE_VERSION (fail-closed: re-read; editText
-      // re-checks the version in its lock).
+      // A concurrent write can only make a later guarded mutation fail stale and require reread.
       const info = await ctx.fs.stat(target, exec.signal)
       if (!info) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
       if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
@@ -135,12 +125,10 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       ctx.emit('fs/observed', target, info.version, exec)
       return [{ type: 'text', text: formatReadOutput(target.displayPath, outcome) }]
     },
-    // Pure display: a generic card titled by the file with the read window
-    // appended (`Read foo.txt (5 - 8)`), `read` kind (icon), and a follow-along
-    // location whose line is the read's offset (defaulting to 1). The window is
-    // derived from the RAW args (offset/limit as the model passed them), NOT the
-    // tool's defaulted 1/configured limit, so an unbounded read shows a bare
-    // title (and the presenter stays a pure function of args, config-free).
+    // Pure display: a generic card titled by the file with the read window appended (`Read
+    // foo.txt (5 - 8)`), `read` kind (icon), and a follow-along location whose line is the
+    // read's offset (defaulting to 1). The window reflects raw args, so an omitted limit keeps
+    // the title bare instead of smuggling config into this pure presenter.
     presentCall(args): GenericCallView {
       const { offset, limit } = args
       const window = limit !== undefined && limit > 0

packages/fs/tool-fs/src/session-cwd.ts

@@ -1,18 +1,10 @@
 /**
- * Derive the working directory a filesystem tool resolves relative paths
- * against: the calling agent's per-session workspace
- * (`exec.agent.session.header.cwd`), so each ACP session's `read`/`write`/`edit`
- * act on ITS workspace, not the server's launch dir — mirroring how
+ * Derive the working directory a filesystem tool resolves relative paths against: the calling
+ * agent's per-session workspace (`exec.agent.session.header.cwd`), so each ACP session's
+ * `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
  * `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
- *
- * The `agent` is optional-chained — a non-agent caller yields `undefined`, and
- * the tool then calls `ctx.fs.resolve(path)` with no base so the backend applies
- * its own configured default (preserving the non-ACP / no-session behavior).
- * `session`/`header` are non-optional on a real `Agent`, so only `agent` needs
- * the guard (mirroring `dsh-tool-bash`'s `resolveWorkdir`). Returning `undefined`
- * rather than reading `process.cwd()` here keeps the default in ONE place (the
- * provider), per the "explicit > implicit at seams" convention.
- *
+ * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
+ * `process.cwd()` at the tool seam.
  * @module @deepseek-ai/dsh-tool-fs/session-cwd
  */
 

packages/fs/tool-fs/src/write.ts

@@ -1,13 +1,7 @@
 /**
- * The model-facing `write` tool: create or fully replace a UTF-8 text file. The
- * tool is the executor: it dispatches the `fs/write-intent` waterfall to
- * obtain the optional version guard, calls `ctx.fs.writeText` directly, and
- * emits `fs/observed`. The default thunk returns `undefined` (unconditional
- * create-or-overwrite — the bare provider); a policy plugin
- * (`@deepseek-ai/dsh-fs-policy`) occupies the single decision slot and
- * returns `createIfAbsent`/`replaceIfVersion` instead. The tool stats ZERO
- * times either way.
- *
+ * Model-facing full-file write. It obtains an optional intent from the single policy slot, calls
+ * `ctx.fs.writeText` without a stat, then records the resulting version; no policy means an
+ * unconditional atomic create-or-overwrite.
  * @module @deepseek-ai/dsh-tool-fs/src/write
  */
 
@@ -75,20 +69,17 @@ export function applyWriteTool(ctx: Context): void {
       const outcome = await ctx.fs.writeText(target, input.content, intent, exec.signal)
       // Record the observed version (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, outcome.version, exec)
-      // Attach a contextual hunk as `meta` ONLY for an overwrite (a before-version
-      // exists). A create has no "before" — `outcome.before` is null — so it
-      // carries no `meta`; `presentResult` then renders a whole-file diff from the
-      // args, so the completed card is still a diff (never the result text).
+      // Overwrites carry applied hunks. Creates have no prior text, so result presentation uses
+      // the args-derived whole-file diff instead.
       const diffs = outcome.before !== null ? computeHunkDiffs(input.filePath, outcome.before, outcome.after) : []
       return {
         content: [{ type: 'text', text: formatWriteOutput(target.displayPath, outcome) }],
         ...diffs.length > 0 ? { meta: { diffs } } : {},
       }
     },
-    // Pure display: a diff card (an editor renders write as a new-file / full-
-    // replace diff). `oldText: null` — a call-time presenter has no access to the
-    // file's prior content, so even an overwrite renders new-file style, matching
-    // claude-agent-acp. A follow-along location points at the written file.
+    // Pure display: a diff card (an editor renders write as a new-file / full- replace diff).
+    // `oldText: null` — a call-time presenter has no access to the file's prior content, so
+    // even an overwrite renders new-file style, matching claude-agent-acp.
     presentCall(args): DiffCallView {
       return {
         card: 'diff',
@@ -97,14 +88,10 @@ export function applyWriteTool(ctx: Context): void {
         locations: [{ path: args.file_path }],
       }
     },
-    // Result-time display: a `diff` card so the completed `tool_call_update`
-    // re-installs the diff rather than the model-facing result text (an ACP
-    // `tool_call_update.content` REPLACES the call's content, so a text result
-    // would clobber the pending diff card). An OVERWRITE uses the applied
-    // contextual hunks on `meta`; a CREATE has no `meta` (no prior content), so
-    // its whole-file new-file diff is derived from `args.content` (replay-safe,
-    // matching the call-time card). An error falls through to generic rendering
-    // so its message shows.
+    // Result-time display: a `diff` card so the completed `tool_call_update` re-installs the
+    // diff rather than the model-facing result text (an ACP `tool_call_update.content` REPLACES
+    // the call's content, so a text result would clobber the pending diff card). Overwrites use
+    // applied metadata; creates and identical overwrites use the replay-safe args fallback.
     presentResult(args, result: ToolResult): DiffResultView | undefined {
       if (result.isError) return undefined
       const diffs = diffsFromMeta(result.meta)

packages/fs/tool-fs/tests/harness.ts

@@ -11,15 +11,9 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 
 /**
- * Shared harness for the fs-tools with-key e2e: a minimal real agent stack (the
- * DeepSeek adapter + the real fs provider + the read-before-write/edit policy +
- * the model-facing read/write/edit tools). Lives outside the *.e2e.ts pattern so
- * importing it never re-registers another file's tests.
- *
- * `fsCwd` is the local backend's default base; a per-session cwd (set via a
- * session header) overrides it, but this harness creates agents without a
- * session cwd, so the provider default IS the workspace. `persona` is the
- * deployment persona (the system-prompt plugin's per-context config).
+ * Build the real fs-tool stack for with-key e2e tests. Agents have no session
+ * cwd, so `fsCwd` is their workspace; `persona` configures the deployment prompt.
+ * This helper lives outside the e2e glob so imports do not register tests.
  */
 export async function fsHarness(fsCwd: string, persona = ''): Promise<Context> {
   const ctx = new Context()

packages/fs/tool-fs/tests/integration.spec.ts

@@ -1,16 +1,8 @@
 /**
- * Integration tests: the real local backend (`dsh-fs-local`) plus the model
- * tools (`dsh-tool-fs`) as the executor, exercised through `ctx.tools.execute()`
- * so nothing bypasses the tool registry. Two deployments:
- *
- *  - DEFAULT — with the real `dsh-fs-policy` policy gate plugin: read-before-
- *    write/edit, version-guarded mutation, FS_NOT_OBSERVED for unread edits.
- *  - BARE — WITHOUT the policy plugin: every `fs/*` waterfall falls through to
- *    its undefined default, so write/edit are unconditional. This proves the
- *    tool carries no dependency on the policy plugin.
- *
- * These verify the WORLD — files are read back from disk and asserted
- * byte-for-byte — not the tool's self-report.
+ * End-to-end tool-registry tests against the real local backend. The policy deployment verifies
+ * observed-state and guarded mutation; the bare deployment proves unconditional tools have no
+ * policy-service dependency. Assertions read files back byte-for-byte rather than trusting tool
+ * messages.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -28,9 +20,7 @@ import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 let dir: string
 let ctx: Context
 let fiber: Awaited<ReturnType<Context['plugin']>>
-// A stable session object stands in for an agent session (the file-state
-// owner). It carries a `header` (no `cwd`) so `sessionCwd(exec)` resolves to
-// `undefined` and the backend falls back to its configured cwd (= `dir`).
+// No header cwd: sessionCwd returns undefined and the provider's configured test dir applies.
 const session = { header: {} }
 
 let callCounter = 0
@@ -290,13 +280,9 @@ describe('bare provider (no dsh-fs-policy)', () => {
   })
 })
 
-// --------------------------------------------------------------------------
-// Per-session cwd: a relative file_path resolves against the CALLING session's
-// workspace (`exec.agent.session.header.cwd`), NOT the backend's config.cwd —
-// so an ACP editor's per-session dir wins, matching dsh-tool-bash. The regression
-// this guards: before the seam fix the tool passed no cwd, so a relative write
-// landed in config.cwd instead of the session dir.
-// --------------------------------------------------------------------------
+// Per-session cwd: a relative file_path resolves against the calling session's workspace
+// (`exec.agent.session.header.cwd`), not the backend's config.cwd — so an ACP editor's
+// per-session dir wins, matching dsh-tool-bash.
 describe('per-session cwd', () => {
   let sessionDir: string
   beforeEach(async () => {
@@ -428,9 +414,8 @@ describe('signal, concurrency, and the fs/observed contract', () => {
   })
 
   it('a throwing fs/observed listener surfaces as isError, but the mutation already hit disk', async () => {
-    // fs/observed is a plain ctx.emit AFTER the write succeeded; a throwing
-    // listener cannot roll the write back — it only turns the tool result into
-    // isError. The file must still carry the written bytes.
+    // fs/observed is a plain ctx.emit after the write succeeded; a throwing listener cannot
+    // roll the write back — it only turns the tool result into isError.
     ctx.on('fs/observed', () => { throw new Error('recording bug') })
     const result = await callOwned('write', { file_path: 'w.txt', content: 'durable' })
     expect(result.isError).toBe(true)

packages/fs/tool-fs/tests/tools.spec.ts

@@ -1,11 +1,6 @@
 /**
- * Consumer-surface tests for the filesystem tools as the EXECUTOR. They run the
- * REAL `@deepseek-ai/dsh-fs-policy` gate plugin (the genuine policy
- * collaborator, per the prefer-the-real-implementation rule) over a fake
- * `ctx.fs` provider, so they verify schemas, argument validation, result
- * formatting, FsError→isError propagation, and that each tool dispatches the
- * `fs/*` waterfalls + records observed-state through the gate (read authorizes a
- * later edit) — not just that it moved bytes.
+ * Consumer-surface tests over a fake provider and the real policy collaborator: schemas,
+ * validation, formatting, typed errors, intent dispatch, and observation-driven authorization.
  */
 
 import { describe, expect, it, vi } from 'vitest'
@@ -419,9 +414,8 @@ describe('tool-owned presentation (pure presentCall)', () => {
 })
 
 describe('result-time contextual diff (meta + presentResult)', () => {
-  // An edit records the applied contextual hunk on `tool/result` meta, and the
-  // tool's presentResult narrows it back into a `diff` result card the bridge
-  // renders. Drive execute end-to-end so the meta is the REAL computed hunk.
+  // An edit records the applied contextual hunk on `tool/result` meta, and the tool's
+  // presentResult narrows it back into a `diff` result card the bridge renders.
   const withContext = 'a\nb\nc\nOLD\nd\ne\nf\n'
 
   it('edit: execute attaches the applied hunk as meta { diffs }', async () => {
@@ -462,10 +456,9 @@ describe('result-time contextual diff (meta + presentResult)', () => {
   })
 
   it('write CREATE: no before-version → no meta, but presentResult still renders a whole-file diff card', async () => {
-    // A create has no prior content (no `meta`), yet the completed card must be a
-    // `diff` — an ACP tool_call_update.content REPLACES the call's content, so a
-    // non-diff result would clobber the pending new-file diff. The whole-file diff
-    // is derived from the args (oldText:null), replay-safe.
+    // A create has no prior content (no `meta`), yet the completed card must be a `diff` — an
+    // ACP tool_call_update.content REPLACES the call's content, so a non-diff result would
+    // clobber the pending new-file diff.
     const { ctx } = await setup()
     const session = { header: {} }
     const result = await call(ctx, 'write', { file_path: 'new.txt', content: 'fresh\n' }, { session })