docs(tools): DiffResultView.diffs may be a whole-file diff, not only hunks

The write-diff-card fix made write's presentResult return an args-derived
whole-file diff (oldText:null) for a create / unchanged overwrite, but the
DiffResultView contract and its mirrored docs still said `diffs` is ALWAYS
the applied contextual hunks computed from before/after. Correct the type
JSDoc, the write execute-side comment, and the four mirrored surfaces
(tools.md, tools README, acp-feature-support, adding-a-tool cookbook) to
say: typically the applied hunks, or a whole-file diff when there is no
before-image (a create) — and that a mutation returns the diff result even
when it duplicates the call-time card, since a tool_call_update.content
replace would otherwise clobber the diff with the model-facing text.
Regenerate the cordis catalog (source line shift).

packages/core/tools/README.md

@@ -79,7 +79,7 @@ A tool owns how ITS calls render in a UI (an editor's tool-call card, a CLI log
 - `presentResult(args, result): ToolResultView | undefined` — the COMPLETED state, given the same `args` and the `{ content, isError, meta? }` result, one of:
   - `{ card: 'generic', title?, content? }` — an optional replacement `title` and reformatted `content`.
   - `{ card: 'terminal', title?, output?, exitCode?, signal? }` — a terminal run's captured `output` and exit status. A capable UI shows an exit-status pill; an incapable UI gets a fenced ` ```console ` fallback the BRIDGE derives from `output` (the tool does not encode the fences).
-  - `{ card: 'diff', title?, diffs }` — a completed file mutation as an inline diff. `diffs` is `FileDiff[]` — the APPLIED hunks with surrounding context (one entry per changed site), computed from the before/after file content, distinct from the call-time whole-snippet `diff`. Used by `write`/`edit`; a `tool_call_update.content` replaces the call's content, so this supersedes the pending snippet.
+  - `{ card: 'diff', title?, diffs }` — a completed file mutation as an inline diff. `diffs` is `FileDiff[]` — typically the applied hunks with surrounding context computed from the before/after content, or a whole-file diff (`oldText: null`) when there is no before-image (a file create). Used by `write`/`edit`; a `tool_call_update.content` replaces the call's content, so a mutation tool returns this even when it duplicates the call-time snippet (else the result text would clobber the pending diff).
 
 Returning `undefined` (or omitting a method) tells a UI to fall back to a generic presentation (title = tool name, raw args as input, raw result content). Both methods must be **pure and side-effect-free**: a UI may call them during live streaming AND during a session-log replay, so they depend only on their arguments. `result.meta` is the tool's own optional presentation payload (opaque `unknown`, JSON-serializable), attached by `execute` (see below) and persisted on the `tool/result` event, so a `presentResult` reading it stays replay-deterministic (the same `meta` is read back from the log). With `defineTool`, `args` is the typed `InferArgs<S>` shape; the helper soft-validates before calling (a malformed/older logged arg shape yields `undefined` rather than throwing, since display must never crash a replay). The views are provider-neutral — the ACP bridge (`dsh-acp`) maps each `card` to ACP `tool_call`/`tool_call_update` wire fields (a `diff` card to a `{ type: 'diff' }` content block, a `terminal` card to the `_meta` terminal convention), and relativizes a file card's title against the session cwd. See the render-intent-union RFC (`docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md`) and the applied-hunk-diffs RFC (`docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md`); `dsh-tool-bash` (terminal) and `dsh-tool-fs` (diff/generic) are the reference implementations.
 

packages/core/tools/src/index.ts

@@ -220,19 +220,21 @@ export interface TerminalResultView {
 
 /**
  * A completed file mutation rendered as an inline diff card, the *result-time*
- * analogue of {@link DiffCallView}. Set by a tool whose `execute` applied a
- * file change (e.g. `write`, `edit`): `diffs` are the APPLIED hunks computed
- * from the before/after file content (one entry per hunk, each with surrounding
- * context lines), so the editor shows the real change with context — distinct
- * from the call-time whole-snippet {@link DiffCallView}. A `tool_call_update`'s
- * content REPLACES the call's content in an editor, so this result diff
- * supersedes the pending snippet.
+ * analogue of {@link DiffCallView}. Set by a tool whose `execute` applied a file
+ * change (e.g. `write`, `edit`): `diffs` are the change to show — typically the
+ * APPLIED hunks computed from the before/after content (one entry per hunk, each
+ * with surrounding context lines), so the editor shows the real change in place;
+ * a tool with no before-image (e.g. a file create) may instead give a whole-file
+ * diff (`oldText: null`). A `tool_call_update`'s content REPLACES the call's
+ * content in an editor, so a mutation tool returns this even when it duplicates
+ * the call-time snippet — otherwise the model-facing result text would replace
+ * (clobber) the pending diff card.
  */
 export interface DiffResultView {
   card: 'diff'
   /** Replacement title for the completed call. Omit to keep the pending-state title. */
   title?: string
-  /** One entry per applied hunk (a contextual diff), in file order. */
+  /** The change to show, in file order — applied contextual hunks, or a whole-file diff when there is no before-image. */
   diffs: FileDiff[]
 }