@flotiarenor/dsh-tool-text-editor 1.1.2 → 1.3.0

package/lib/editor.mjs

@@ -3,44 +3,43 @@
 /**
  * editor.mjs —— dsh 模型工具插件：`edit_text` / `write_text`。
  *
- * 为什么存在：dsh 原生的 `write` / `edit` 在 Windows 上会丢掉 UTF-8 BOM，原生 `write` 还会把
- * CRLF 文件改写成 LF（实测确认；`@deepseek-ai/dsh-fs-local` 全文没有 BOM 处理，Node 的
- * `TextDecoder` 默认吞掉前导 BOM 字节）。本插件用**进程内 Node 实现**（`lib/core.mjs`）做同样
- * 的事，但把 BOM 与行尾保真、dry-run diff、自动备份、编辑台账、grep/lines 锚点一起带上。
+ * 原生 `write` / `edit`（由 `@deepseek-ai/dsh-fs-local` 实现）做不到的事，本插件用**进程内 Node 实现**
+ * （`lib/core.mjs`）补上，并把 `grep` / `lines` 锚点与宽松匹配一起带上：
+ *   1. **丢 UTF-8 BOM**：该实现没有 BOM 处理，Node 的 `TextDecoder` 默认吞掉前导 BOM 字节（`edit` 与
+ *      `write` 都丢）；
+ *   2. **不还原行尾**：`writeText` 按 `content` 里的行尾原样落盘，所以往 CRLF 文件里写 LF 内容就把它
+ *      变成 LF——本插件还原文件自身的风格；
+ *   3. **只做精确匹配**：`old_string` 差一个空格就报 `FS_EDIT_NOT_FOUND`，没有回退。
  *
- * 与原生工具的关系：注册的是两个**不与原生重名**的工具，原生 `edit`/`write` 原样保留，
- * 因此没有同名注册冲突，回退就是给 preset 行加 `disabled: true`。
+ * 与原生工具的关系：注册的是两个**不与原生重名**的工具，原生 `edit` / `write` 原样保留，因此没有同名注册
+ * 冲突，回退就是给 preset 行加 `disabled: true`。
  *
- * 依赖：**零**。只用 `node:` 内置模块 —— 不启动解释器或外部命令，不 import 任何包，没有构建
- * 步骤、没有第三方依赖、没有外部运行时。因此本文件既能被 preset 行用绝对路径加载，也能被 link
- * 进 profile 后按包名加载（preset 行的裸包名走宿主基址解析，模块内部的裸 import 走文件真实路径
- * 解析；零依赖让两种挂载方式都成立）。内嵌的 JSON Schema 是用 dsh 自己的
- * `parameterSchemaSpecToJsonSchema` / `valueSchemaSpecToJsonSchema` 生成的（生成脚本在仓库里，见
- * `tools/gen-schema.mjs`；它不随包发布）。
+ * 依赖：**零**。只用 `node:` 内置模块——不启动解释器或外部命令，不 import 任何包，没有构建步骤、没有第三方
+ * 依赖、没有外部运行时。因此本文件既能被 preset 行用绝对路径加载，也能被 link 进 profile 后按包名加载
+ * （preset 行的裸包名走宿主基址解析，模块内部的裸 import 走文件真实路径解析；零依赖让两种挂载方式都成立）。
+ * 内嵌的 JSON Schema 由 dsh 自己的 `parameterSchemaSpecToJsonSchema` / `valueSchemaSpecToJsonSchema`
+ * 生成（生成脚本见 `tools/gen-schema.mjs`，不随包发布）。
  *
  * 有意为之的取舍：
- *   * 写盘**不经过** `ctx.fs`：绕过 fs 观察策略（先读后写 / 版本新鲜度）、沙箱与
- *     `sandbox_permissions` 审批升权、原生原子写与 Windows DACL 保留。原生原子写与本插件的
- *     临时文件 + fsync + rename 等价，这段绕过的代价已在 README 写明。
- *   * 模型可见文本受上限约束：路径仅出现一次，正文为一行统计加经 `diffBudget` 裁剪的 diff
- *     （`brief` / `diff`）；备份文件名等细节只保留在台账与 `stdout` 中。完整 diff 经
- *     `presentationMeta` 投影为 UI 卡片，该路径不进入模型上下文。理由见 `lib/core.mjs` 头部。
+ *   * 写盘**不经过** `ctx.fs`：绕过 fs 观察策略（先读后写 / 版本新鲜度）、沙箱与 `sandbox_permissions`
+ *     审批升权、原生原子写与 Windows DACL 保留。原生原子写与本插件的临时文件 + fsync + rename 等价，
+ *     代价已在 README 写明。正因为这条路径上没有第二个强制点，插件把会话文件策略里**唯一禁止写入的那一档**
+ *     镜像了回来：`read-only` 会话下在任何 I/O 之前拒写（见 `isReadOnly`）。
+ *   * 模型可见文本只有一行统计（外加必要的警告）：**既不回显改动内容，也不回显路径**——结果与调用一一绑定，
+ *     `new_text` 与 `file_path` 都在调用方那一轮里。理由与实测数字见 `renderResult`。
+ *   * **不写旁路记录**：没有备份、没有台账，改动只落在目标文件上。
  *   * `lines` / `before <行号>` 是**盲锚点**：行号错了不会报错，会改在别的地方。
  *   * 同目标串行只覆盖**本进程内**；跨进程（另一个 dsh 实例、你手边的编辑器）仍可能互相覆盖。
  *
  * 配置（本插件没有 Config schema，preset 行的 `config:` 字段原样透传）：
- *   backup: boolean               默认 true（落盘前备份到 artifactsDir/backups）
- *   ledger: boolean               默认 true（追加 artifactsDir/edits.log）
- *   artifactsDir: string          默认 <工作区>/.dsh
  *   newFileBom: boolean           默认 false（新建文件是否写 BOM）
- *   context: number               人读 diff 的上下文行数，默认 3（只影响 stdout 与 UI 卡片）
- *   diff: 'auto'|'full'|'none'    模型可见 diff 正文的默认策略，默认 'auto'
- *   maxDiffLines: number          模型可见 diff 正文的行数预算，默认 30
+ *   guidance: 'full' | 'short' | false  默认 'full'；短版去掉"优先于原生"那半句（原生已被
+ *                                 `lib/mask.mjs` 屏蔽时才该用），false 则整段不注册
  *   root: string                  没有 agent 会话时的回退工作区
  * 新建文件的行尾推断可用环境变量 `DSH_TEXT_EDITOR_EOL` = lf | crlf 覆盖（见 lib/core.mjs）。
  */
 
-import { DIFF_MODES, UsageError, applyPlan, hunksFromDiff, toLf } from './core.mjs'
+import { UsageError, applyPlan, toLf } from './core.mjs'
 
 export const name = 'tool-text-editor'
 
@@ -53,46 +52,45 @@ const TIMEOUT_MS = 60_000
 const EDIT_MODES = ['replace', 'after', 'before', 'append', 'prepend']
 
 /** 工具引导（order 116，落在工具引导区间 100–199）。文本里不能出现双花括号（会被当提示词变量）。 */
-const GUIDANCE =
-  'Prefer `edit_text` and `write_text` for text changes in this workspace: they preserve a UTF-8 BOM and '
-  + 'the file existing CRLF/LF style, print a unified diff, back the previous content up, and accept `grep` '
-  + 'or `lines` anchors so the old text never has to be copied by hand. The built-in `write` tool drops the '
-  + 'BOM and rewrites a CRLF file as LF, and the built-in `edit` tool drops the BOM; use the built-ins '
-  + 'only when a `_text` call reports that it cannot run.'
+const GUIDANCE_FULL =
+  'Prefer `edit_text`/`write_text` over the built-in `edit`/`write` for text changes: they keep the UTF-8 '
+  + 'BOM and the file CRLF/LF style. The built-ins drop the BOM, and `write` flattens CRLF to LF; use them '
+  + 'only when a `_text` call cannot run.'
+
+/**
+ * `guidance: 'short'` 用的文本：原生 `edit`/`write` 已被 `lib/mask.mjs` 从这个 agent 的可见面去掉，
+ * "prefer … over the built-in" 这半句成了死重（模型看不到那两个工具），所以只留"用哪个、保什么"。
+ */
+const GUIDANCE_SHORT =
+  'Use `edit_text` for targeted changes and `write_text` to create or replace a file: both keep the UTF-8 '
+  + 'BOM and the file CRLF/LF style, and report one stat line.'
+
+/** `guidance` 的合法取值。 */
+const GUIDANCE_MODES = ['full', 'short', false]
 
 const EDIT_DESCRIPTION =
-  'Edit one existing text file. Preserves the UTF-8 BOM and the file line-ending style, backs the previous '
-  + 'content up, and returns a stat line plus the changed lines when the diff is small (see '
-  + '`diff`). Give exactly ONE anchor: `old_text` (literal, '
-  + 'copied from `read`), `grep` (a regular expression whose matching line/block becomes the anchor), or '
-  + '`lines` (e.g. "263:270"). `mode` defaults to `replace`; use `after`/`before` to insert beside a '
-  + '`grep`/`lines` anchor, `append`/`prepend` for the file ends. Prefer `old_text`/`grep`: a wrong line '
-  + 'number does not fail, it edits the wrong place. A literal that occurs more than once is refused unless '
-  + '`nth` or `count` says which/how many. Set `dry_run` to preview without writing.'
+  'Edit one existing text file. Preserves the BOM and line endings; returns one stat line '
+  + '(`replace@17 +1/-1`) instead of echoing the change. Give exactly ONE anchor: `old_text`, `grep` '
+  + '(regex) or `lines`. Prefer `old_text`/`grep`: a wrong line number edits the wrong place without '
+  + 'failing. A literal matching more than once is refused unless `count` declares how many you expect; a near '
+  + 'miss returns the closest candidates.'
 
 const WRITE_DESCRIPTION =
-  'Create or completely replace one text file. Preserves the UTF-8 BOM and the file line-ending style, backs '
-  + 'the previous content up, and returns a stat line instead of echoing the content '
-  + 'back (see `diff`). Creation needs no flag: '
-  + 'the tool detects whether the target exists, and a brand-new file follows the line-ending style of its '
-  + 'sibling files. Set `dry_run` to preview without writing.'
+  'Create or completely replace one text file. Preserves the BOM and line endings; returns one stat line '
+  + 'instead of echoing the content. A missing target is created, parent directories included, and empty '
+  + 'content creates a zero-byte file; a new file borrows its siblings\' line-ending style.'
 
 /** 参数 schema（等价于 defineTool 对 `tools/gen-schema.mjs` 里 DSL 的产物；那里会校验二者一致）。 */
 export const EDIT_PARAMETERS = {
   type: 'object',
   properties: {
-    file_path: { type: 'string', description: 'Target file, resolved against the session working directory when relative.' },
+    file_path: { type: 'string', description: 'Target file; relative resolves against the session cwd.' },
     new_text: { type: 'string', description: 'Replacement / inserted text.' },
-    old_text: { type: 'string', description: 'Literal anchor text to replace (exactly one anchor source).' },
-    grep: { type: 'string', description: 'Regular-expression anchor: the matching line or line block is replaced.' },
-    lines: { type: 'string', description: 'Line anchor, e.g. "263:270" or "120".' },
-    mode: { type: 'string', description: 'Edit kind. Default replace.', enum: EDIT_MODES },
-    count: { type: 'number', description: 'Require exactly N occurrences and replace all of them.' },
-    nth: { type: 'number', description: 'Replace the k-th occurrence only (1-based).' },
-    strict: { type: 'boolean', description: 'Disable relaxed matching.' },
-    diff: { type: 'string', description: 'Diff detail in the result: auto (default, small changes only) | full (always, capped) | none.', enum: DIFF_MODES },
-    dry_run: { type: 'boolean', description: 'Print the diff without writing.' },
-    note: { type: 'string', description: 'One-line reason recorded in the edit ledger.' },
+    old_text: { type: 'string', description: 'Literal anchor text (exactly one anchor source).' },
+    grep: { type: 'string', description: 'Regex anchor: the matching line block, its trailing newline included.' },
+    lines: { type: 'string', description: 'Line anchor, e.g. "263:270" or "120"; trailing newline included.' },
+    mode: { type: 'string', description: 'replace (default) substitutes the anchor; after/before insert beside a grep/lines anchor; append/prepend use the file ends.', enum: EDIT_MODES },
+    count: { type: 'number', description: 'Declare the expected number of hits (mismatch refuses to write); for `lines` anchors it declares how many lines the anchor covers.' },
   },
   required: ['file_path', 'new_text'],
 }
@@ -100,66 +98,46 @@ export const EDIT_PARAMETERS = {
 export const WRITE_PARAMETERS = {
   type: 'object',
   properties: {
-    file_path: { type: 'string', description: 'Target file, resolved against the session working directory when relative.' },
+    file_path: { type: 'string', description: 'Target file; relative resolves against the session cwd.' },
     content: { type: 'string', description: 'Complete new file content.' },
-    diff: { type: 'string', description: 'Diff detail in the result: auto (default, small changes only) | full (always, capped) | none.', enum: DIFF_MODES },
-    dry_run: { type: 'boolean', description: 'Print the diff without writing.' },
-    note: { type: 'string', description: 'One-line reason recorded in the edit ledger.' },
   },
   required: ['file_path', 'content'],
 }
 
-/** 两个工具共用的规范返回值。一切都在进程内完成，所以只有结果，没有退出码或后端标记。 */
+/**
+ * 两个工具共用的规范返回值。一切都在进程内完成，所以只有结果，没有退出码或后端标记。
+ *
+ * 四个字段全部是**模型通道**的依据（`render` 只读它们），没有呈现层载荷。
+ */
 export const OUTPUT_SCHEMA = {
   type: 'object',
   additionalProperties: false,
   properties: {
     path: { type: 'string' },
     ok: { type: 'boolean' },
-    wrote: { type: 'boolean' },
-    dryRun: { type: 'boolean' },
-    stdout: { type: 'string' },
-    stderr: { type: 'string' },
     brief: { type: 'string' },
-    diff: { type: 'string' },
+    stderr: { type: 'string' },
   },
-  required: ['path', 'ok', 'wrote', 'dryRun', 'stdout', 'stderr', 'brief', 'diff'],
+  required: ['path', 'ok', 'brief', 'stderr'],
 }
 
 /**
- * 模型可见的结果文本：**一行统计、受上限约束的 diff 正文**。
+ * 模型可见的结果文本：成功是**一行统计**（`WROTE` 加 `brief`），失败是**完整原因**（`FAIL` 加 `stderr`）。
+ *
+ * 成功路径不回显改动内容：调用方刚发过 `new_text`，`replace@17 +1/-1` 已说明改在哪几行、改了多少，要看正文
+ * `read` 一次即可。失败路径相反——原因必须完整，它决定下一次调用。
  *
- * 成功路径只返回 `brief` 与 `diff`：路径仅出现一次，备份文件名只保留在台账与 `stdout` 中，
- * 完整 diff 由 UI 卡片承载。失败路径相反——原因必须完整，它决定调用方的下一次调用。
+ * 也不回显路径：结果与调用一一绑定（`tool/result` 带 `source.callId`），调用参数里的 `file_path` 就在同一轮
+ * 历史里，逐字回显它新信息量为零。实测（本机 79 个会话、86 条当前形状的结果）：成功路径单条平均 116 B，
+ * 其中 `WROTE <路径>` 一行占 55.6 B；去掉路径后降到 66 B（−43%）。改动本身只在 GUI 的工具调用参数里可见。
  */
 function renderResult(_args, value) {
-  const where = value.path === '' ? '' : ' ' + value.path
   if (!value.ok) {
-    const detail = [value.stderr.trim(), value.stdout.trim()].filter((part) => part !== '').join('\n')
-    return [{ type: 'text', text: 'FAIL' + where + '\n' + (detail === '' ? '(no output)' : detail) }]
+    const detail = value.stderr.trim()
+    return [{ type: 'text', text: 'FAIL\n' + (detail === '' ? '(no reason given)' : detail) }]
   }
-  const head = value.dryRun ? 'DRY RUN' + where + ' (nothing written)' : 'WROTE' + where
-  const body = [value.brief, value.diff].map((part) => part.trim()).filter((part) => part !== '')
-  return [{ type: 'text', text: [head, ...body].join('\n') }]
-}
-
-/**
- * UI diff 卡片：**完整** diff（含配置的上下文行）只走这条路径。
- * 元数据随 `tool/result` 持久化，供实时与回放两条路径使用；模型永远看不到它。
- */
-function presentationMeta(_args, value) {
-  const diffs = value.ok === true && value.wrote === true ? hunksFromDiff(value.stdout, value.path) : []
-  return { diffs, path: value.path }
-}
-
-/** 有 diff 卡片可用就交给 UI；否则返回 `undefined`，让宿主回退到文本渲染。 */
-function presentResult(_args, result) {
-  if (result.isError === true) return undefined
-  const meta = result.meta
-  const diffs = meta !== null && typeof meta === 'object' && Array.isArray(meta.diffs) ? meta.diffs : []
-  if (diffs.length === 0) return undefined
-  const title = typeof meta.path === 'string' && meta.path !== '' ? meta.path : undefined
-  return title === undefined ? { card: 'diff', diffs } : { card: 'diff', title, diffs }
+  const body = value.brief.trim()
+  return [{ type: 'text', text: body === '' ? 'WROTE' : 'WROTE\n' + body }]
 }
 
 function stringArg(value, label, { required = false } = {}) {
@@ -180,20 +158,6 @@ function integerArg(value, label, minimum) {
   return value
 }
 
-function booleanArg(value, label) {
-  if (value === undefined) return undefined
-  if (typeof value !== 'boolean') throw new UsageError(`${label} must be a boolean`)
-  return value
-}
-
-function diffModeArg(value) {
-  if (value === undefined) return undefined
-  if (typeof value !== 'string' || !DIFF_MODES.includes(value)) {
-    throw new UsageError('diff must be one of ' + DIFF_MODES.join(' / '))
-  }
-  return value
-}
-
 /**
  * 校验并归一 `edit_text` 入参。
  * @throws {UsageError} 参数不合法（不会落盘）。
@@ -206,6 +170,9 @@ export function planEdit(args) {
     throw new UsageError('mode must be one of ' + EDIT_MODES.join(' / '))
   }
   const oldText = stringArg(args.old_text, 'old_text')
+  // 空锚点没有内容可寻址（`lines` / `grep` 才是点名行块的那两条路），而且它在匹配层会走成
+  // "零长命中"，所以在这里就拒掉，别让一次参数错误变成一次全文扫描。
+  if (oldText === '') throw new UsageError('old_text must not be empty: use lines / grep to name a line block')
   const grep = stringArg(args.grep, 'grep')
   const lines = args.lines === undefined ? undefined : String(args.lines)
   const anchors = []
@@ -222,8 +189,6 @@ export function planEdit(args) {
     throw new UsageError(mode + ' takes no anchor, got ' + anchors.join(' + '))
   }
   const count = integerArg(args.count, 'count', 1)
-  const nth = integerArg(args.nth, 'nth', 1)
-  if (count !== undefined && nth !== undefined) throw new UsageError('count and nth are mutually exclusive')
   return {
     kind: 'edit',
     filePath,
@@ -232,11 +197,6 @@ export function planEdit(args) {
     oldText: oldText === undefined ? null : toLf(oldText),
     anchor: grep !== undefined ? { value: grep } : lines !== undefined ? { value: lines } : null,
     count,
-    nth,
-    strict: booleanArg(args.strict, 'strict') === true,
-    dryRun: booleanArg(args.dry_run, 'dry_run') === true,
-    diff: diffModeArg(args.diff),
-    note: stringArg(args.note, 'note') ?? '',
   }
 }
 
@@ -248,9 +208,6 @@ export function planWrite(args) {
     kind: 'write',
     filePath,
     content: toLf(args.content),
-    dryRun: booleanArg(args.dry_run, 'dry_run') === true,
-    diff: diffModeArg(args.diff),
-    note: stringArg(args.note, 'note') ?? '',
   }
 }
 
@@ -262,19 +219,52 @@ function workspaceRoot(exec, fallback) {
   return fallback
 }
 
-function fail(path, message) {
-  return {
-    path: typeof path === 'string' ? path : '',
-    ok: false,
-    wrote: false,
-    dryRun: false,
-    stdout: '',
-    stderr: message,
-    brief: '',
-    diff: '',
+// ─────────────────────────────────────────────────────────────────────────────
+// 会话文件策略：read-only 时一并拒写
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** read-only 会话里的拒写原因。说清"是策略，不是参数错"，否则调用方会浪费一次重试。 */
+const READ_ONLY_REASON = 'the session file policy is read-only, so writing is refused (the policy comes from the session settings, not from the path).'
+
+/** 宿主返回值是外部输入，先窄化成"普通对象"再读字段。 */
+function recordOf(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null
+}
+
+/**
+ * 会话当前是否处于 `read-only` 文件策略。
+ *
+ * 本插件的写入**绕开 `ctx.fs`**（fs seam 的变更原语只有 `writeText` / `editText`，会丢 BOM、拍平 CRLF），
+ * 因此没有第二个强制点：沙箱、审批、`fs/observed` 都不在这条路径上。这里读宿主自己的 `sandboxPolicy`
+ * 归属方（`resolve({ session })`），把 read-only 这一档镜像回来——不新增任何提示词或 schema 字段，只在真的
+ * 拒一次时产生一行失败原因。
+ *
+ * 取舍：`sandboxPolicy` 是**可选**消费（`ctx.get`，不进 `inject`），服务缺席或解析失败一律按"不是只读"
+ * 处理——本工具不是安全边界，策略服务异常不该把写盘全禁掉。`workspace-write` 与 `danger-full-access` 仍走
+ * 既有的常量护栏（见 README 已知限制）。
+ *
+ * @param ctx - 插件上下文（用于 `ctx.get('sandboxPolicy')`）。
+ * @param exec - 工具执行上下文（提供会话）。
+ * @returns 是否只读。
+ */
+function isReadOnly(ctx, exec) {
+  // 模拟 ctx（自测与量测脚本）没有 `get`：当成"没有策略事实"。
+  if (ctx === null || typeof ctx !== 'object' || typeof ctx.get !== 'function') return false
+  const policy = ctx.get('sandboxPolicy')
+  if (policy === null || typeof policy !== 'object' || typeof policy.resolve !== 'function') return false
+  try {
+    const session = exec && exec.agent ? exec.agent.session : undefined
+    const resolved = policy.resolve({ session })
+    return recordOf(resolved) !== null && resolved.mode === 'read-only'
+  } catch {
+    return false
   }
 }
 
+function fail(path, message) {
+  return { path: typeof path === 'string' ? path : '', ok: false, brief: '', stderr: message }
+}
+
 /**
  * 注册 `edit_text` / `write_text` 与工具引导段。
  * @param ctx - 插件上下文（注册随其 fiber 释放）。
@@ -283,22 +273,17 @@ function fail(path, message) {
 export function apply(ctx, config) {
   const settings = config === undefined || config === null ? {} : config
   const fallbackRoot = typeof settings.root === 'string' && settings.root !== '' ? settings.root : process.cwd()
-  const artifactsDir = typeof settings.artifactsDir === 'string' && settings.artifactsDir !== ''
-    ? settings.artifactsDir
-    : undefined
-  const planOptions = {
-    backup: settings.backup !== false,
-    log: settings.ledger !== false,
-    context: Number.isFinite(settings.context) ? settings.context : undefined,
-    newFileBom: settings.newFileBom === true,
-    ...(Number.isFinite(settings.maxDiffLines) && settings.maxDiffLines >= 1
-      ? { maxDiffLines: Math.floor(settings.maxDiffLines) }
-      : {}),
+  const newFileBom = settings.newFileBom === true
+  const guidance = settings.guidance === undefined ? 'full' : settings.guidance
+  if (!GUIDANCE_MODES.includes(guidance)) {
+    throw new Error(`tool-text-editor: guidance must be one of full | short | false, got ${JSON.stringify(settings.guidance)}`)
   }
-  /** 配置层的默认 diff 策略；逐调用的 `diff` 参数优先于它。 */
-  const diffDefault = DIFF_MODES.includes(settings.diff) ? settings.diff : 'auto'
 
-  ctx.systemPrompt.section({ name: 'tool:edit_text', order: 116, text: GUIDANCE })
+  // 引导段是可选的：屏蔽掉原生工具后（见 `lib/mask.mjs`），`guidance: 'short'` 省掉那半句已经作废的
+  // "prefer … over the built-in"；`false` 则整段不注册（工具描述本身已经讲清用法）。
+  if (guidance !== false) {
+    ctx.systemPrompt.section({ name: 'tool:edit_text', order: 116, text: guidance === 'short' ? GUIDANCE_SHORT : GUIDANCE_FULL })
+  }
 
   /**
    * 组装上下文并执行。
@@ -306,22 +291,15 @@ export function apply(ctx, config) {
    * @param exec - 工具执行上下文（提供会话工作区）。
    */
   async function run(plan, exec) {
-    const root = workspaceRoot(exec, fallbackRoot)
-    return await applyPlan(plan, {
-      root,
-      ...(artifactsDir === undefined ? {} : { artifactsDir }),
-      ...planOptions,
-      diff: plan.diff ?? diffDefault,
-      tool: plan.kind === 'write' ? WRITE_TOOL : EDIT_TOOL,
-    })
+    if (isReadOnly(ctx, exec)) return fail(plan.filePath, READ_ONLY_REASON)
+    return await applyPlan(plan, { root: workspaceRoot(exec, fallbackRoot), newFileBom })
   }
 
   ctx.tools.register({
     name: EDIT_TOOL,
     description: EDIT_DESCRIPTION,
     parameters: EDIT_PARAMETERS,
-    output: { schema: OUTPUT_SCHEMA, render: renderResult, presentationMeta },
-    presentResult,
+    output: { schema: OUTPUT_SCHEMA, render: renderResult },
     timeoutMs: TIMEOUT_MS,
     async execute(args, exec) {
       let plan
@@ -339,8 +317,7 @@ export function apply(ctx, config) {
     name: WRITE_TOOL,
     description: WRITE_DESCRIPTION,
     parameters: WRITE_PARAMETERS,
-    output: { schema: OUTPUT_SCHEMA, render: renderResult, presentationMeta },
-    presentResult,
+    output: { schema: OUTPUT_SCHEMA, render: renderResult },
     timeoutMs: TIMEOUT_MS,
     async execute(args, exec) {
       let plan