@x1a0f3n9/dsh-tool-fs 0.1.5-rc.4 → 0.1.7-rc.2

package/README.i18n.yaml

@@ -1,6 +1,142 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# 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
-README.md: 9d338a6227b7f02ef43fcbe97900b166cb722817
-README.zh.md: 0c34f840ad449847a649df8abdadec01f772f37b
+/:
+  en: 52b93805befe8077
+  zh: 9786e662303f0e2f
+/x1a0f3n9-dsh-tool-fs:
+  en: c53838f9abadf120
+  zh: e65d8cbc2c3a6691
+/x1a0f3n9-dsh-tool-fs/summary:
+  en: c8f608c85c8d6626
+  zh: 4133a867517baca5
+/x1a0f3n9-dsh-tool-fs/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/x1a0f3n9-dsh-tool-fs/use-this-package:
+  en: 8fd62afcdabe55d4
+  zh: 9bdcae272575be8c
+/x1a0f3n9-dsh-tool-fs/use-this-package/minimal-composition:
+  en: eb21d89a3ecbd2d4
+  zh: f05ccbb1e7515f32
+/x1a0f3n9-dsh-tool-fs/use-this-package/the-tools:
+  en: e70e0164411016b5
+  zh: 3fa6caa8f3d70552
+/x1a0f3n9-dsh-tool-fs/use-this-package/configuration:
+  en: 7eb705e3b132fcba
+  zh: 883207b13d381f9e
+/x1a0f3n9-dsh-tool-fs/use-this-package/policy-and-sandbox-behavior:
+  en: 53d4ac2db089ef39
+  zh: 214ea051ed56f500
+/x1a0f3n9-dsh-tool-fs/use-this-package/failures-and-recovery:
+  en: 962b09e21305a04b
+  zh: 382d2b8cce217569
+/x1a0f3n9-dsh-tool-fs/understand-the-implementation:
+  en: e30f7038c28e93f8
+  zh: a3868dbd90367b13
+/x1a0f3n9-dsh-tool-fs/understand-the-implementation/design-concept:
+  en: 454b5291db9ba847
+  zh: 9fe7081dfb416c93
+/x1a0f3n9-dsh-tool-fs/understand-the-implementation/source-map:
+  en: e8220ed04480aadc
+  zh: 1cc5f9a505953102
+/x1a0f3n9-dsh-tool-fs/understand-the-implementation/per-tool-flow:
+  en: d741e01be9fddb76
+  zh: 7aa1d7ca719a4aac
+/x1a0f3n9-dsh-tool-fs/understand-the-implementation/observation-and-concurrency:
+  en: 665d437dc35bf05f
+  zh: 8004334d6a3246b4
+/x1a0f3n9-dsh-tool-fs/further-exploration:
+  en: 485bc55482f576bc
+  zh: fc5fa55b41098bd0
+/x1a0f3n9-dsh-tool-fs/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt:
+  en: cf78b9dd5596495f
+  zh: bd44560f8c2435e8
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees:
+  en: b09ee4be5e522c29
+  zh: ffd30b57d7fc96e8
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/read-guidance:
+  en: f8961df3f3a6a671
+  zh: 85c7bd418b40b089
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/write-guidance:
+  en: 7e34af48c583f210
+  zh: e39ad6823689c665
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt/what-the-model-sees/edit-guidance:
+  en: 28f07502a411303b
+  zh: 437897dc99fc4360
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt/token-effect:
+  en: 7a44cabe439a879a
+  zh: 1adf9bf3de7658b6
+/x1a0f3n9-dsh-tool-fs/model-experience/system-prompt/kv-cache-effect:
+  en: 4f1b5639f91405a8
+  zh: f90ffe077a2e52a3
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-schemas:
+  en: 3039bc5e7a796b21
+  zh: 6b7a9eaf69c9ea53
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-schemas/what-the-model-sees:
+  en: 6f2a072c474e39e7
+  zh: dbee4c2b206bf68f
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-schemas/token-effect:
+  en: 68517f7d65ef7e9d
+  zh: 544a4b81e8ea16c0
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-schemas/kv-cache-effect:
+  en: 1e6d3da20012762d
+  zh: 482f8bc569b8b490
+/x1a0f3n9-dsh-tool-fs/model-experience/read-result:
+  en: ebd38733c0490428
+  zh: b45101c325efe784
+/x1a0f3n9-dsh-tool-fs/model-experience/read-result/what-the-model-sees:
+  en: 06e250bd8788248a
+  zh: e00d36b48068909a
+/x1a0f3n9-dsh-tool-fs/model-experience/read-result/token-effect:
+  en: 4269b4368622ec2f
+  zh: f4df80c1fb6972f1
+/x1a0f3n9-dsh-tool-fs/model-experience/read-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/x1a0f3n9-dsh-tool-fs/model-experience/image-read-result:
+  en: 9dac44e6d0b9d8de
+  zh: 7bc4dc1c5df39eaf
+/x1a0f3n9-dsh-tool-fs/model-experience/image-read-result/what-the-model-sees:
+  en: 9252b6d73776c5ff
+  zh: d6e433450989399e
+/x1a0f3n9-dsh-tool-fs/model-experience/image-read-result/token-effect:
+  en: 68bd5255f1c9ca48
+  zh: 0474213531c1aae3
+/x1a0f3n9-dsh-tool-fs/model-experience/image-read-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 48e202e396bc5fcc
+/x1a0f3n9-dsh-tool-fs/model-experience/write-and-edit-results:
+  en: 1b3b6cfa3605d0b4
+  zh: 78e37c2aa4f76d54
+/x1a0f3n9-dsh-tool-fs/model-experience/write-and-edit-results/what-the-model-sees:
+  en: bb2a92e0e43e3273
+  zh: a744395576b48a93
+/x1a0f3n9-dsh-tool-fs/model-experience/write-and-edit-results/token-effect:
+  en: fb4d0b17a99f49cf
+  zh: 17460a2a5d72f6cc
+/x1a0f3n9-dsh-tool-fs/model-experience/write-and-edit-results/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-errors:
+  en: 2d4f2c8605eccab3
+  zh: 67f1f0218f73c6bf
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-errors/what-the-model-sees:
+  en: 4e8fac7bac8ced61
+  zh: 7ba921dbcddc9f97
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-errors/token-effect:
+  en: 681cadd5be7b8ac1
+  zh: 65e483f62fb819d9
+/x1a0f3n9-dsh-tool-fs/model-experience/tool-errors/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 3d6bc05b9eadfbc2
+/x1a0f3n9-dsh-tool-fs/known-limitations-and-deferred-work:
+  en: ce7a91d41d2f7597
+  zh: d4a3c905e124fd7f
+/x1a0f3n9-dsh-tool-fs/known-limitations-and-deferred-work/dev-note:
+  en: 0c4d0c465413d319
+  zh: a20efeb10121b927

package/README.md

@@ -67,7 +67,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 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.
+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
 
@@ -138,19 +138,19 @@ At assembly time, each guidance section checks `ctx.tools.get(name, scope)` and
 ##### 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.
+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
-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-observation-policy requires it) and prefer edit for targeted changes.
+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
-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-observation-policy requires it), unless you just created or edited it in this session.
+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

package/README.zh.md

@@ -67,7 +67,7 @@ kind: "package-reference"
 
 `read` 与 `read_image` 的路径授权完全由 `ctx.fs` 负责；媒体类型声明和文件签名只决定 `read_image` 是否接受该后端返回的字节。
 
-挂载策略插件后，`write` 与 `edit` 从 `fs/*` 意图槽位取得防护，因此未读目标或陈旧观察会以 `FS_NOT_OBSERVED` 或 `FS_STALE_VERSION` 及恢复指令失败。使用施加沙箱限制的后端（`fs-sandbox`）时，`write`/`edit` 还会公开 `sandbox_permissions` 与 `justification`；被拒绝的变更返回 `[sandbox: file access denied under <mode> mode]` 标记与同轮次升级提示，获批的重试可以在该次调用中加盖严格更宽的模式。
+挂载策略插件后，`write` 与 `edit` 从 `fs/*` 意图槽位取得防护，因此未读目标或陈旧观察会以 `FS_NOT_OBSERVED` 或 `FS_STALE_VERSION` 及恢复指令失败。使用施加沙箱限制的后端（`fs-sandbox`）时，`write`/`edit` 还会公开 `sandbox_permissions` 与 `justification`；被拒绝的变更返回 `[sandbox: file access denied under <mode> mode]` 标记与同轮次升级提示，获批的重试可以在该次调用中加盖严格更宽的模式。理由字段提示模型使用用户当前提问的语言。
 
 ### 失败与恢复
 
@@ -138,19 +138,19 @@ kind: "package-reference"
 ##### Read 指导
 
 ```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.
+Use the read tool — not shell commands like cat — to inspect text files. Use offset and limit to continue reading large files.
 ```
 
 ##### Write 指导
 
 ```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-observation-policy requires it) and prefer edit for targeted changes.
+Read an existing file before overwriting it with write (the default fs-observation-policy requires it) and prefer edit for targeted changes.
 ```
 
 ##### Edit 指导
 
 ```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-observation-policy requires it), unless you just created or edited it in this session.
+Read a file before editing it (the default fs-observation-policy requires it), unless you just created or edited it in this session.
 ```
 
 #### Token 影响

package/lib/index.js

@@ -1,10 +1,11 @@
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@x1a0f3n9/dsh-tools";
 import { FsError } from "@x1a0f3n9/dsh-fs";
-import { ESCALATION_TARGETS, approveEscalation, canonicalPath, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@x1a0f3n9/dsh-sandbox";
+import { readLangHintForPath as langFromPath } from "@x1a0f3n9/dsh-util-code-language";
 import { structuredPatch } from "diff";
 import { basename, extname } from "node:path";
 import { AttachmentError, AttachmentId } from "@x1a0f3n9/dsh-attachment";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, sandboxPermissionsDescription, validateEscalationArgs } from "@x1a0f3n9/dsh-sandbox";
 //#region lib/types/read-render.js
 /**
 * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
@@ -110,71 +111,6 @@ ${outcome.lines.length > 0 ? `${outcome.lines.map((line) => `${line.number}: ${l
 </content>`;
 }
 /**
-* Lowercased file-extension to syntax-highlighting language hint. Keys are the
-* extension without its dot; a UI treats an absent key as plain text. The map is
-* intentionally small — common source, config, and markup extensions a
-* line-numbered code view benefits from highlighting — not an exhaustive registry.
-*/
-const LANG_BY_EXTENSION = {
-	ts: "ts",
-	tsx: "tsx",
-	mts: "ts",
-	cts: "ts",
-	js: "js",
-	jsx: "jsx",
-	mjs: "js",
-	cjs: "js",
-	json: "json",
-	jsonc: "json",
-	py: "py",
-	rb: "rb",
-	go: "go",
-	rs: "rs",
-	java: "java",
-	c: "c",
-	h: "c",
-	cc: "cpp",
-	cpp: "cpp",
-	hpp: "cpp",
-	cxx: "cpp",
-	cs: "cs",
-	kt: "kotlin",
-	swift: "swift",
-	php: "php",
-	sh: "sh",
-	bash: "sh",
-	zsh: "sh",
-	yaml: "yaml",
-	yml: "yaml",
-	toml: "toml",
-	ini: "ini",
-	md: "md",
-	markdown: "md",
-	mdx: "mdx",
-	html: "html",
-	htm: "html",
-	css: "css",
-	scss: "scss",
-	less: "less",
-	sql: "sql",
-	xml: "xml",
-	lua: "lua"
-};
-/**
-* Derive a syntax-highlighting language hint from a read path's file extension.
-* Pure and case-insensitive on the extension; a dotfile with no extension
-* (`.gitignore`) and an unknown extension both yield `undefined`.
-* @param path - the model-facing path the read reported.
-* @returns the language hint for {@link LANG_BY_EXTENSION}, or `undefined` when the extension maps to none.
-*/
-function langFromPath(path) {
-	const base = path.slice(Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1);
-	const dot = base.lastIndexOf(".");
-	if (dot <= 0) return void 0;
-	const ext = base.slice(dot + 1).toLowerCase();
-	return Object.hasOwn(LANG_BY_EXTENSION, ext) ? LANG_BY_EXTENSION[ext] : void 0;
-}
-/**
 * Whether `value` is a valid {@link FileTextLine} (defensive narrowing from
 * opaque `meta`). `number` must be a 1-based integer line number, since a card
 * rendered from a zero, fractional, or non-finite line number would violate the
@@ -229,28 +165,22 @@ function readMetaFromMeta(meta) {
 * `process.cwd()` at the tool boundary.
 * @module @x1a0f3n9/dsh-tool-fs/session-cwd
 */
-const PARENT_PATH_SEGMENT = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
 /**
 * The session workspace cwd for this call, or `undefined` when none applies.
 * @param exec - the tool-execution context; only its optional `agent` is read.
-* @param requestedPath - the path the provider will resolve; parent traversal
-*   makes a symlinked cwd's filesystem identity observable.
 * @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
 */
-function sessionCwd(exec, requestedPath) {
-	const cwd = exec.agent?.session.header.cwd;
-	if (cwd === void 0 || !PARENT_PATH_SEGMENT.test(cwd) && !PARENT_PATH_SEGMENT.test(requestedPath)) return cwd;
-	return canonicalPath(cwd);
+function sessionCwd(exec) {
+	return exec.agent?.session.header.cwd;
 }
 /**
 * Resolution options shared by all model-facing filesystem tools.
 * @param exec - the tool-execution context supplying session cwd and cancellation.
-* @param requestedPath - the path the provider will resolve.
 * @param policyWorkspaceRoot - resolved per-call root, when a mutation carries sandbox policy.
 * @returns provider resolution options for the current tool call.
 */
-function sessionResolveOptions(exec, requestedPath, policyWorkspaceRoot) {
-	const cwd = policyWorkspaceRoot ?? sessionCwd(exec, requestedPath);
+function sessionResolveOptions(exec, policyWorkspaceRoot) {
+	const cwd = policyWorkspaceRoot ?? sessionCwd(exec);
 	return {
 		...cwd !== void 0 ? { cwd } : {},
 		signal: exec.signal
@@ -270,7 +200,7 @@ function sessionResolveOptions(exec, requestedPath, policyWorkspaceRoot) {
 * @returns the resolved target and its single stat result.
 */
 async function resolveRegularReadTarget(ctx, exec, requestedPath) {
-	const target = await ctx.fs.resolve(requestedPath, sessionResolveOptions(exec, requestedPath));
+	const target = await ctx.fs.resolve(requestedPath, sessionResolveOptions(exec));
 	const info = await ctx.fs.stat(target, exec.signal);
 	if (info === void 0) {
 		ctx.emit("fs/observed", target, { kind: "absent" }, exec);
@@ -326,7 +256,7 @@ function applyReadTool(ctx, caps) {
 	ctx.systemPrompt.section({
 		name: "tool:read",
 		order: ctx.systemPrompt.getSectionOrder("TOOL_READ"),
-		text: ({ scope }) => ctx.tools.get("read", scope) === void 0 ? "" : "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."
+		text: ({ scope }) => ctx.tools.get("read", scope) === void 0 ? "" : "Use the read tool — not shell commands like cat — to inspect text files. Use offset and limit to continue reading large files."
 	});
 	ctx.tools.register(defineTool({
 		name: "read",
@@ -591,7 +521,7 @@ function applyWriteTool(ctx, sandbox) {
 	ctx.systemPrompt.section({
 		name: "tool:write",
 		order: ctx.systemPrompt.getSectionOrder("TOOL_WRITE"),
-		text: ({ scope }) => ctx.tools.get("write", scope) === void 0 ? "" : "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-observation-policy requires it)" + (ctx.tools.get("edit", scope) === void 0 ? "" : " and prefer edit for targeted changes") + "."
+		text: ({ scope }) => ctx.tools.get("write", scope) === void 0 ? "" : "Read an existing file before overwriting it with write (the default fs-observation-policy requires it)" + (ctx.tools.get("edit", scope) === void 0 ? "" : " and prefer edit for targeted changes") + "."
 	});
 	ctx.tools.register(defineTool({
 		name: "write",
@@ -637,16 +567,19 @@ function applyWriteTool(ctx, sandbox) {
 				type: "text",
 				text: formatWriteOutput(value.path, value)
 			}],
-			presentationMeta: (args, value) => ({ diffs: value.before === null ? [] : computeHunkDiffs(args.file_path, value.before, value.after).map(({ path, oldText, newText }) => ({
-				path,
-				oldText,
-				newText
-			})) })
+			presentationMeta: (args, value) => ({
+				operation: value.operation,
+				diffs: value.before === null ? [] : computeHunkDiffs(args.file_path, value.before, value.after).map(({ path, oldText, newText }) => ({
+					path,
+					oldText,
+					newText
+				}))
+			})
 		},
 		async execute(args, exec) {
 			const input = parseWriteArgs(args);
 			const sandboxPolicy = await sandbox.resolvePolicy("write", args, exec);
-			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot));
+			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, sandboxPolicy?.workspaceRoot));
 			const intent = await ctx.waterfall("fs/write-intent", target, exec, () => void 0);
 			let outcome;
 			try {
@@ -736,7 +669,7 @@ function applyEditTool(ctx, sandbox) {
 	ctx.systemPrompt.section({
 		name: "tool:edit",
 		order: ctx.systemPrompt.getSectionOrder("TOOL_EDIT"),
-		text: ({ scope }) => ctx.tools.get("edit", scope) === void 0 ? "" : "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-observation-policy requires it), unless you just created or edited it in this session."
+		text: ({ scope }) => ctx.tools.get("edit", scope) === void 0 ? "" : "Read a file before editing it (the default fs-observation-policy requires it), unless you just created or edited it in this session."
 	});
 	ctx.tools.register(defineTool({
 		name: "edit",
@@ -750,7 +683,7 @@ function applyEditTool(ctx, sandbox) {
 			old_string: {
 				type: "string",
 				required: true,
-				description: "Literal text to replace. Must match exactly."
+				description: "Literal text to replace."
 			},
 			new_string: {
 				type: "string",
@@ -795,7 +728,7 @@ function applyEditTool(ctx, sandbox) {
 		async execute(args, exec) {
 			const input = parseEditArgs(args);
 			const sandboxPolicy = await sandbox.resolvePolicy("edit", args, exec);
-			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot));
+			const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, sandboxPolicy?.workspaceRoot));
 			let outcome;
 			try {
 				const intent = await ctx.waterfall("fs/edit-intent", target, exec, () => void 0);
@@ -1040,7 +973,7 @@ function imageReadContent(value) {
 function applyReadImageTool(ctx) {
 	ctx.tools.register(defineTool({
 		name: "read_image",
-		description: "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.",
+		description: "Read a PNG/JPEG/WebP/GIF file and return the image itself. Large images are downscaled automatically; do not install image libraries or create thumbnails to inspect an image.",
 		parameters: { file_path: {
 			type: "string",
 			required: true,
@@ -1165,18 +1098,19 @@ var FsSandboxController = class {
 			sandbox_permissions: {
 				type: "string",
 				enum: [...this.escalationModes],
-				description: "The wider sandbox mode this file operation needs. Only valid as a one-shot retry of an operation the sandbox just denied; requires justification and user approval."
+				description: sandboxPermissionsDescription("operation")
 			},
 			justification: {
 				type: "string",
-				description: "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access."
+				description: "Required with sandbox_permissions: one sentence for the user explaining why this exact file operation needs the wider access. Use the language of the user’s current request."
 			}
 		};
 	}
 	/**
 	* The policy to stamp onto this mutation: an approved escalation grant (a
 	* strictly wider retry resolved through `ctx.approval` before anything
-	* executes), else the session's standing mode. The calling session's cwd is
+	* executes), else the session's standing mode. Repeating the standing mode
+	* requires no approval. The calling session's cwd is
 	* always carried as the workspace root. Validates the escalation argument
 	* pairing first.
 	* @param toolName - the mutating tool's name, for the approval audit trail.

package/lib/types/diff.d.ts

@@ -8,13 +8,16 @@ import type { FileDiff } from '@x1a0f3n9/dsh-tools';
 export declare const DIFF_CONTEXT = 3;
 /**
  * The `write`/`edit` tools' private `tool/result` `meta` payload: the applied
- * contextual-diff hunks. Attached opaquely (as `unknown`) on the tool result and
+ * contextual-diff hunks, and for `write` whether the call created or updated
+ * the file, which tells an empty hunk list of a create from one of an
+ * unchanged overwrite. Attached opaquely (as `unknown`) on the tool result and
  * persisted with the session log — it must be JSON-serializable (the session
  * validates this at `append`), so `presentResult` reproduces the diff card on
  * replay. The producing tool owns and narrows this opaque shape.
  */
 export type FsDiffMeta = {
     diffs: FileDiff[];
+    operation?: 'create' | 'update';
 };
 /**
  * Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the

package/lib/types/read-render.d.ts

@@ -64,13 +64,16 @@ export declare function buildWindow(chunks: AsyncIterable<string> | Iterable<str
  */
 export declare function formatReadOutput(displayPath: string, outcome: FileReadOutcome): string;
 /**
- * Derive a syntax-highlighting language hint from a read path's file extension.
- * Pure and case-insensitive on the extension; a dotfile with no extension
- * (`.gitignore`) and an unknown extension both yield `undefined`.
+ * Derive the persisted `lang` hint from a read path's file extension. The shared
+ * table in `@x1a0f3n9/dsh-util-code-language` owns the recognized suffixes and
+ * the path rules (both separators, a leading dot as the extension separator, and
+ * prototype-key safety); `readLangHintForPath` projects the read card's short ids
+ * over it, so a suffix whose value a recorded session already holds keeps it
+ * byte-identical while every other suffix uses its language's short name.
  * @param path - the model-facing path the read reported.
- * @returns the language hint for {@link LANG_BY_EXTENSION}, or `undefined` when the extension maps to none.
+ * @returns the persisted language hint, or `undefined` when the extension maps to none.
  */
-export declare function langFromPath(path: string): string | undefined;
+export { readLangHintForPath as langFromPath } from '@x1a0f3n9/dsh-util-code-language';
 /**
  * The `read` tool's private `tool/result` `meta` payload: the structured
  * line-numbered window a capable UI renders as a code view. Attached opaquely (as

package/lib/types/sandbox.d.ts

@@ -52,7 +52,8 @@ export declare class FsSandboxController {
     /**
      * The policy to stamp onto this mutation: an approved escalation grant (a
      * strictly wider retry resolved through `ctx.approval` before anything
-     * executes), else the session's standing mode. The calling session's cwd is
+     * executes), else the session's standing mode. Repeating the standing mode
+     * requires no approval. The calling session's cwd is
      * always carried as the workspace root. Validates the escalation argument
      * pairing first.
      * @param toolName - the mutating tool's name, for the approval audit trail.

package/lib/types/session-cwd.d.ts

@@ -10,19 +10,16 @@ import type { ToolExecution } from '@x1a0f3n9/dsh-tools';
 /**
  * The session workspace cwd for this call, or `undefined` when none applies.
  * @param exec - the tool-execution context; only its optional `agent` is read.
- * @param requestedPath - the path the provider will resolve; parent traversal
- *   makes a symlinked cwd's filesystem identity observable.
  * @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
  */
-export declare function sessionCwd(exec: ToolExecution, requestedPath: string): string | undefined;
+export declare function sessionCwd(exec: ToolExecution): string | undefined;
 /**
  * Resolution options shared by all model-facing filesystem tools.
  * @param exec - the tool-execution context supplying session cwd and cancellation.
- * @param requestedPath - the path the provider will resolve.
  * @param policyWorkspaceRoot - resolved per-call root, when a mutation carries sandbox policy.
  * @returns provider resolution options for the current tool call.
  */
-export declare function sessionResolveOptions(exec: ToolExecution, requestedPath: string, policyWorkspaceRoot?: string): {
+export declare function sessionResolveOptions(exec: ToolExecution, policyWorkspaceRoot?: string): {
     cwd?: string;
     signal?: AbortSignal;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x1a0f3n9/dsh-tool-fs",
   "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)",
-  "version": "0.1.5-rc.4",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -28,39 +28,41 @@
   "license": "MIT",
   "dependencies": {
     "diff": "^9.0.0",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "@x1a0f3n9/dsh-util-code-language": "0.1.7-rc.2"
   },
   "peerDependencies": {
-    "@x1a0f3n9/dsh-attachment": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-fs": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-sandbox": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-sandbox-policy": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-session": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-system-prompt": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-user-approval": "^0.1.5-rc.4",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@x1a0f3n9/dsh-attachment": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-fs": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-sandbox": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-system-prompt": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-tools": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-user-approval": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@x1a0f3n9/dsh-agent-loop": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-agent-loop-testkit": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-attachment": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-fs": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-fs-local": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-fs-observation-policy": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-llm-deepseek": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-sandbox": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-sandbox-policy": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-session": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-system-prompt": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-tools": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-user-approval": "^0.1.5-rc.4",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-scope": "^0.1.5-rc.4",
-    "@x1a0f3n9/dsh-code-runtime": "^0.1.5-rc.4"
+    "@x1a0f3n9/dsh-agent": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-agent-loop": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-agent-loop-testkit": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-attachment": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-fs": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-fs-local": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-fs-observation-policy": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm-deepseek": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm-deepseek-api-key": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-sandbox": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-system-prompt": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-tools": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-user-approval": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@x1a0f3n9/dsh-session-projection": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-scope": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-ptc-runtime": "0.1.7-rc.2"
   }
 }