@ai-agent-forge/plugin-coding-tools 0.88.14 → 0.88.15

package/dist/version-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-registry.js","sourceRoot":"","sources":["../src/version-registry.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,2EAA2E;AAC3E,+EAA8D;AAe9D,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAErC,qFAAqF;AACrF,MAAM,UAAU,GAAG,IAAI,GAAG,EAA0C,CAAC;AAErE,SAAS,eAAe,CAAC,SAAiB,EAAkC;IAC3E,IAAI,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QACrB,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,QAAQ,CAAC;AAAA,CAChB;AAED,SAAS,KAAK,CAAC,QAAwC,EAAE,GAAW,EAAE,KAAwB,EAAQ;IACrG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzB,OAAO,QAAQ,CAAC,IAAI,GAAG,uBAAuB,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;YAAE,MAAM;QAChC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;AAAA,CACD;AAED,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,aAAqB,EAAE,OAA0B,EAAQ;IACzG,KAAK,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;AAAA,CAC1D;AAED,wEAAwE;AACxE,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,aAAqB,EAAiC;IAC3G,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;IAC/D,OAAO,KAAK,CAAC;AAAA,CACb;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,aAAqB,EAAQ;IAC7E,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;AAAA,CACjD;AAED,qEAAqE;AACrE,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAU;IAC/D,OAAO,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;AAAA,CAC5C;AAED,mDAAmD;AACnD,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAQ;IAC7D,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAAA,CAC7B","sourcesContent":["// Session-scoped version registry for the default file tools.\n//\n// Records what a session last observed for a path so `write` can refuse a\n// blind overwrite and `edit` can skip a second hash when stat is unchanged.\n// Entries never leave this process: a resumed session starts empty and the\n// first overwrite asks for a read (design: 文件写入协调设计.md §6.2).\n\nexport interface RecordedVersionV1 {\n\t/** sha256 of the raw bytes that were observed. */\n\treadonly hash: string;\n\t/** Version facts from the same fd as `hash`; absent for custom operations without fd snapshots. */\n\treadonly stat?: {\n\t\treadonly ino: string;\n\t\treadonly size: string;\n\t\treadonly mtimeNs: string;\n\t\treadonly ctimeNs: string;\n\t\treadonly mode: number;\n\t};\n}\n\nconst MAX_ENTRIES_PER_SESSION = 1024;\n\n/** Insertion order doubles as LRU order (Map preserves it; delete+set refreshes). */\nconst registries = new Map<string, Map<string, RecordedVersionV1>>();\n\nfunction sessionRegistry(sessionId: string): Map<string, RecordedVersionV1> {\n\tlet registry = registries.get(sessionId);\n\tif (registry === undefined) {\n\t\tregistry = new Map();\n\t\tregistries.set(sessionId, registry);\n\t}\n\treturn registry;\n}\n\nfunction touch(registry: Map<string, RecordedVersionV1>, key: string, value: RecordedVersionV1): void {\n\tregistry.delete(key);\n\tregistry.set(key, value);\n\twhile (registry.size > MAX_ENTRIES_PER_SESSION) {\n\t\tconst oldest = registry.keys().next();\n\t\tif (oldest.done === true) break;\n\t\tregistry.delete(oldest.value);\n\t}\n}\n\n/** Remember the version a `read` (or a successful write) observed. */\nexport function recordVersion(sessionId: string, canonicalPath: string, version: RecordedVersionV1): void {\n\ttouch(sessionRegistry(sessionId), canonicalPath, version);\n}\n\n/** What this session last observed for `canonicalPath`, if anything. */\nexport function getRecordedVersion(sessionId: string, canonicalPath: string): RecordedVersionV1 | undefined {\n\tconst registry = registries.get(sessionId);\n\tif (registry === undefined) return undefined;\n\tconst value = registry.get(canonicalPath);\n\tif (value !== undefined) touch(registry, canonicalPath, value);\n\treturn value;\n}\n\n/** Drop the entry after the file disappeared, so the next write may create it. */\nexport function forgetVersion(sessionId: string, canonicalPath: string): void {\n\tregistries.get(sessionId)?.delete(canonicalPath);\n}\n\n/** Test/diagnostic helper: number of tracked paths for a session. */\nexport function recordedVersionCount(sessionId: string): number {\n\treturn registries.get(sessionId)?.size ?? 0;\n}\n\n/** Drop a session's registry (session dispose). */\nexport function clearSessionVersions(sessionId: string): void {\n\tregistries.delete(sessionId);\n}\n"]}

package/dist/write-scope.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Child write-scope enforcement for the default file tools (design §7.2).
+ *
+ * Scope patterns are relative to the session cwd and matched against the
+ * canonical target path (`resolveSubmitTarget`), so a symlink cannot escape by
+ * pointing outside the declared tree. This is a collaboration policy, not a
+ * sandbox: `bash` is outside this check by design.
+ */
+/** True when the canonical target is inside `cwd` and matches one scope pattern. */
+export declare function isWithinWriteScope(targetPath: string, scopeCwd: string, patterns: readonly string[]): boolean;
+export declare function assertWithinWriteScope(targetPath: string, scopeCwd: string, patterns: readonly string[] | undefined): void;
+//# sourceMappingURL=write-scope.d.ts.map

package/dist/write-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-scope.d.ts","sourceRoot":"","sources":["../src/write-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA6BH,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM7G;AAED,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACrC,IAAI,CAGN","sourcesContent":["/**\n * Child write-scope enforcement for the default file tools (design §7.2).\n *\n * Scope patterns are relative to the session cwd and matched against the\n * canonical target path (`resolveSubmitTarget`), so a symlink cannot escape by\n * pointing outside the declared tree. This is a collaboration policy, not a\n * sandbox: `bash` is outside this check by design.\n */\n\nimport { realpathSync } from \"node:fs\";\nimport { isAbsolute, relative, sep } from \"node:path\";\nimport { FileCoordinationError } from \"@agent-forge/host/file-lock\";\nimport { matchesAnyPathGlob } from \"@agent-forge/host/glob\";\n\nfunction denied(targetPath: string, patterns: readonly string[]): FileCoordinationError {\n\treturn new FileCoordinationError(\n\t\t\"write_scope_denied\",\n\t\t`${targetPath} is outside this subagent's write scope. Allowed patterns: ${patterns.length === 0 ? \"(none)\" : patterns.join(\", \")}.`,\n\t\t{ path: targetPath, writeScope: [...patterns] },\n\t);\n}\n\n/**\n * Scope root must live in the same path space as the canonical target: on\n * macOS the session cwd may arrive through `/var` while\n * `resolveSubmitTarget` canonicalizes to `/private/var`, which would make\n * every relative path escape. The target is already real; bring the root over.\n */\nfunction scopeRoot(scopeCwd: string): string {\n\ttry {\n\t\treturn realpathSync(scopeCwd);\n\t} catch {\n\t\treturn scopeCwd;\n\t}\n}\n\n/** True when the canonical target is inside `cwd` and matches one scope pattern. */\nexport function isWithinWriteScope(targetPath: string, scopeCwd: string, patterns: readonly string[]): boolean {\n\tconst relativePath = relative(scopeRoot(scopeCwd), targetPath);\n\tif (relativePath === \"\" || isAbsolute(relativePath)) return false;\n\tconst normalized = relativePath.split(sep).join(\"/\");\n\tif (normalized === \"..\" || normalized.startsWith(\"../\")) return false;\n\treturn matchesAnyPathGlob(patterns, normalized);\n}\n\nexport function assertWithinWriteScope(\n\ttargetPath: string,\n\tscopeCwd: string,\n\tpatterns: readonly string[] | undefined,\n): void {\n\tif (patterns === undefined) return;\n\tif (!isWithinWriteScope(targetPath, scopeCwd, patterns)) throw denied(targetPath, patterns);\n}\n"]}

package/dist/write-scope.js

@@ -0,0 +1,46 @@
+/**
+ * Child write-scope enforcement for the default file tools (design §7.2).
+ *
+ * Scope patterns are relative to the session cwd and matched against the
+ * canonical target path (`resolveSubmitTarget`), so a symlink cannot escape by
+ * pointing outside the declared tree. This is a collaboration policy, not a
+ * sandbox: `bash` is outside this check by design.
+ */
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+import { FileCoordinationError } from "@agent-forge/host/file-lock";
+import { matchesAnyPathGlob } from "@agent-forge/host/glob";
+function denied(targetPath, patterns) {
+    return new FileCoordinationError("write_scope_denied", `${targetPath} is outside this subagent's write scope. Allowed patterns: ${patterns.length === 0 ? "(none)" : patterns.join(", ")}.`, { path: targetPath, writeScope: [...patterns] });
+}
+/**
+ * Scope root must live in the same path space as the canonical target: on
+ * macOS the session cwd may arrive through `/var` while
+ * `resolveSubmitTarget` canonicalizes to `/private/var`, which would make
+ * every relative path escape. The target is already real; bring the root over.
+ */
+function scopeRoot(scopeCwd) {
+    try {
+        return realpathSync(scopeCwd);
+    }
+    catch {
+        return scopeCwd;
+    }
+}
+/** True when the canonical target is inside `cwd` and matches one scope pattern. */
+export function isWithinWriteScope(targetPath, scopeCwd, patterns) {
+    const relativePath = relative(scopeRoot(scopeCwd), targetPath);
+    if (relativePath === "" || isAbsolute(relativePath))
+        return false;
+    const normalized = relativePath.split(sep).join("/");
+    if (normalized === ".." || normalized.startsWith("../"))
+        return false;
+    return matchesAnyPathGlob(patterns, normalized);
+}
+export function assertWithinWriteScope(targetPath, scopeCwd, patterns) {
+    if (patterns === undefined)
+        return;
+    if (!isWithinWriteScope(targetPath, scopeCwd, patterns))
+        throw denied(targetPath, patterns);
+}
+//# sourceMappingURL=write-scope.js.map

package/dist/write-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-scope.js","sourceRoot":"","sources":["../src/write-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAE5D,SAAS,MAAM,CAAC,UAAkB,EAAE,QAA2B,EAAyB;IACvF,OAAO,IAAI,qBAAqB,CAC/B,oBAAoB,EACpB,GAAG,UAAU,8DAA8D,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EACpI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAC/C,CAAC;AAAA,CACF;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAC,QAAgB,EAAU;IAC5C,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,QAAQ,CAAC;IACjB,CAAC;AAAA,CACD;AAED,oFAAoF;AACpF,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,QAAgB,EAAE,QAA2B,EAAW;IAC9G,MAAM,YAAY,GAAG,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC;IAC/D,IAAI,YAAY,KAAK,EAAE,IAAI,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrD,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,OAAO,kBAAkB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAAA,CAChD;AAED,MAAM,UAAU,sBAAsB,CACrC,UAAkB,EAClB,QAAgB,EAChB,QAAuC,EAChC;IACP,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO;IACnC,IAAI,CAAC,kBAAkB,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC;QAAE,MAAM,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;AAAA,CAC5F","sourcesContent":["/**\n * Child write-scope enforcement for the default file tools (design §7.2).\n *\n * Scope patterns are relative to the session cwd and matched against the\n * canonical target path (`resolveSubmitTarget`), so a symlink cannot escape by\n * pointing outside the declared tree. This is a collaboration policy, not a\n * sandbox: `bash` is outside this check by design.\n */\n\nimport { realpathSync } from \"node:fs\";\nimport { isAbsolute, relative, sep } from \"node:path\";\nimport { FileCoordinationError } from \"@agent-forge/host/file-lock\";\nimport { matchesAnyPathGlob } from \"@agent-forge/host/glob\";\n\nfunction denied(targetPath: string, patterns: readonly string[]): FileCoordinationError {\n\treturn new FileCoordinationError(\n\t\t\"write_scope_denied\",\n\t\t`${targetPath} is outside this subagent's write scope. Allowed patterns: ${patterns.length === 0 ? \"(none)\" : patterns.join(\", \")}.`,\n\t\t{ path: targetPath, writeScope: [...patterns] },\n\t);\n}\n\n/**\n * Scope root must live in the same path space as the canonical target: on\n * macOS the session cwd may arrive through `/var` while\n * `resolveSubmitTarget` canonicalizes to `/private/var`, which would make\n * every relative path escape. The target is already real; bring the root over.\n */\nfunction scopeRoot(scopeCwd: string): string {\n\ttry {\n\t\treturn realpathSync(scopeCwd);\n\t} catch {\n\t\treturn scopeCwd;\n\t}\n}\n\n/** True when the canonical target is inside `cwd` and matches one scope pattern. */\nexport function isWithinWriteScope(targetPath: string, scopeCwd: string, patterns: readonly string[]): boolean {\n\tconst relativePath = relative(scopeRoot(scopeCwd), targetPath);\n\tif (relativePath === \"\" || isAbsolute(relativePath)) return false;\n\tconst normalized = relativePath.split(sep).join(\"/\");\n\tif (normalized === \"..\" || normalized.startsWith(\"../\")) return false;\n\treturn matchesAnyPathGlob(patterns, normalized);\n}\n\nexport function assertWithinWriteScope(\n\ttargetPath: string,\n\tscopeCwd: string,\n\tpatterns: readonly string[] | undefined,\n): void {\n\tif (patterns === undefined) return;\n\tif (!isWithinWriteScope(targetPath, scopeCwd, patterns)) throw denied(targetPath, patterns);\n}\n"]}

package/dist/write.d.ts

@@ -1,30 +1,55 @@
+import { type StatVersionV1 } from "@agent-forge/host/file-lock";
 import type { ToolDefinition } from "@agent-forge/host/tool-definition";
 import { type Static, Type } from "typebox";
+import { type CoordinationLeaseCheckV1 } from "./lease-check.ts";
 import { type AgentTool } from "./types.ts";
 declare const writeSchema: Type.TObject<{
     path: Type.TString;
     content: Type.TString;
+    expectedVersion: Type.TOptional<Type.TString>;
 }>;
 export declare const writeToolSystemPromptContribution: {
     readonly snippet: "Create or overwrite files";
-    readonly guidelines: readonly ["Use write only for new files or complete rewrites."];
+    readonly guidelines: readonly ["Use write only for new files or complete rewrites.", "Reading the file first is required before overwriting an existing file; without a prior read the write is rejected."];
 };
 export type WriteToolInput = Static<typeof writeSchema>;
+export interface WriteToolDetails {
+    /** Lines added by the write (empty text is 0 lines; "a" and "a\n" are both 1 line). */
+    addedLines: number;
+    /** Lines removed from the previous content. Omitted when the previous content could not be read. */
+    deletedLines?: number;
+    /** Set when the file did not exist before the write. */
+    created?: true;
+    /** Present only when the operations could not commit atomically (design §13.2 tier B). */
+    coordination?: {
+        atomic: false;
+    };
+}
 /**
  * Pluggable operations for the write tool.
  * Override these to delegate file writing to remote systems (for example SSH).
  */
 export interface WriteOperations {
+    /** Read the current file contents (used to compute line-count details). */
+    readFile?: (absolutePath: string) => Promise<Buffer>;
     /** Write content to a file */
     writeFile: (absolutePath: string, content: string) => Promise<void>;
     /** Create directory recursively */
     mkdir: (dir: string) => Promise<void>;
+    /** Atomic-commit tier (design §13.2): all three required; see EditOperations. */
+    statVersion?: (absolutePath: string) => Promise<StatVersionV1 | undefined>;
+    writeTemp?: (absolutePath: string, content: string) => Promise<string>;
+    commitSync?: (tempPath: string, targetPath: string) => void;
 }
 export interface WriteToolOptions {
     /** Custom operations for file writing. Default: local filesystem */
     operations?: WriteOperations;
+    /** Relative write-path globs from the child task profile; absent = unrestricted. */
+    writeScope?: readonly string[];
+    /** `file.coordination@1` consumer face; absent = no advisory lease checks. */
+    coordination?: CoordinationLeaseCheckV1;
 }
-export declare function createWriteToolDefinition(cwd: string, options?: WriteToolOptions): ToolDefinition<typeof writeSchema, undefined>;
+export declare function createWriteToolDefinition(cwd: string, options?: WriteToolOptions): ToolDefinition<typeof writeSchema, WriteToolDetails | undefined>;
 export declare function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema>;
 export {};
 //# sourceMappingURL=write.d.ts.map

package/dist/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAA+C,MAAM,mCAAmC,CAAC;AAErH,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,KAAK,SAAS,EAAsB,MAAM,YAAY,CAAC;AAEhE,QAAA,MAAM,WAAW;;;EAGf,CAAC;AAEH,eAAO,MAAM,iCAAiC;;;CAGpC,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,8BAA8B;IAC9B,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,mCAAmC;IACnC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAOD,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,CAAC;CAC7B;AA6ID,wBAAgB,yBAAyB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACxB,cAAc,CAAC,OAAO,WAAW,EAAE,SAAS,CAAC,CAgF/C;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEtG","sourcesContent":["// Migrated from packages/agent-forge/src/core/tools/write (batch 1, copy-then-delete);\n// host modules are imported through supply keys (@agent-forge/host/*).\n\nimport { mkdir as fsMkdir, writeFile as fsWriteFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { withFileMutationQueue } from \"@agent-forge/host/file-mutation-queue\";\nimport { t } from \"@agent-forge/host/i18n\";\nimport { keyHint } from \"@agent-forge/host/keybinding-hints\";\nimport { resolveToCwd } from \"@agent-forge/host/path-utils\";\nimport { normalizeDisplayText, renderToolPath, replaceTabs, str } from \"@agent-forge/host/render-utils\";\nimport { getLanguageFromPath, highlightCode, type Theme } from \"@agent-forge/host/theme\";\nimport type { ToolDefinition, ToolExecuteContext, ToolRenderResultOptions } from \"@agent-forge/host/tool-definition\";\nimport { Container, Text } from \"@agent-forge/tui\";\nimport { type Static, Type } from \"typebox\";\nimport { type AgentTool, wrapToolDefinition } from \"./types.ts\";\n\nconst writeSchema = Type.Object({\n\tpath: Type.String({ description: \"Path to the file to write (relative or absolute)\" }),\n\tcontent: Type.String({ description: \"Content to write to the file\" }),\n});\n\nexport const writeToolSystemPromptContribution = {\n\tsnippet: \"Create or overwrite files\",\n\tguidelines: [\"Use write only for new files or complete rewrites.\"],\n} as const;\n\nexport type WriteToolInput = Static<typeof writeSchema>;\n\n/**\n * Pluggable operations for the write tool.\n * Override these to delegate file writing to remote systems (for example SSH).\n */\nexport interface WriteOperations {\n\t/** Write content to a file */\n\twriteFile: (absolutePath: string, content: string) => Promise<void>;\n\t/** Create directory recursively */\n\tmkdir: (dir: string) => Promise<void>;\n}\n\nconst defaultWriteOperations: WriteOperations = {\n\twriteFile: (path, content) => fsWriteFile(path, content, \"utf-8\"),\n\tmkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => {}),\n};\n\nexport interface WriteToolOptions {\n\t/** Custom operations for file writing. Default: local filesystem */\n\toperations?: WriteOperations;\n}\n\ntype WriteHighlightCache = {\n\trawPath: string | null;\n\tlang: string;\n\trawContent: string;\n\tnormalizedLines: string[];\n\thighlightedLines: string[];\n};\n\nclass WriteCallRenderComponent extends Text {\n\tcache?: WriteHighlightCache;\n\n\tconstructor() {\n\t\tsuper(\"\", 0, 0);\n\t}\n}\n\nconst WRITE_PARTIAL_FULL_HIGHLIGHT_LINES = 50;\n\nfunction highlightSingleLine(line: string, lang: string): string {\n\tconst highlighted = highlightCode(line, lang);\n\treturn highlighted[0] ?? \"\";\n}\n\nfunction refreshWriteHighlightPrefix(cache: WriteHighlightCache): void {\n\tconst prefixCount = Math.min(WRITE_PARTIAL_FULL_HIGHLIGHT_LINES, cache.normalizedLines.length);\n\tif (prefixCount === 0) return;\n\tconst prefixSource = cache.normalizedLines.slice(0, prefixCount).join(\"\\n\");\n\tconst prefixHighlighted = highlightCode(prefixSource, cache.lang);\n\tfor (let i = 0; i < prefixCount; i++) {\n\t\tcache.highlightedLines[i] =\n\t\t\tprefixHighlighted[i] ?? highlightSingleLine(cache.normalizedLines[i] ?? \"\", cache.lang);\n\t}\n}\n\nfunction rebuildWriteHighlightCacheFull(rawPath: string | null, fileContent: string): WriteHighlightCache | undefined {\n\tconst lang = rawPath ? getLanguageFromPath(rawPath) : undefined;\n\tif (!lang) return undefined;\n\tconst displayContent = normalizeDisplayText(fileContent);\n\tconst normalized = replaceTabs(displayContent);\n\treturn {\n\t\trawPath,\n\t\tlang,\n\t\trawContent: fileContent,\n\t\tnormalizedLines: normalized.split(\"\\n\"),\n\t\thighlightedLines: highlightCode(normalized, lang),\n\t};\n}\n\nfunction updateWriteHighlightCacheIncremental(\n\tcache: WriteHighlightCache | undefined,\n\trawPath: string | null,\n\tfileContent: string,\n): WriteHighlightCache | undefined {\n\tconst lang = rawPath ? getLanguageFromPath(rawPath) : undefined;\n\tif (!lang) return undefined;\n\tif (!cache) return rebuildWriteHighlightCacheFull(rawPath, fileContent);\n\tif (cache.lang !== lang || cache.rawPath !== rawPath) return rebuildWriteHighlightCacheFull(rawPath, fileContent);\n\tif (!fileContent.startsWith(cache.rawContent)) return rebuildWriteHighlightCacheFull(rawPath, fileContent);\n\tif (fileContent.length === cache.rawContent.length) return cache;\n\n\tconst deltaRaw = fileContent.slice(cache.rawContent.length);\n\tconst deltaDisplay = normalizeDisplayText(deltaRaw);\n\tconst deltaNormalized = replaceTabs(deltaDisplay);\n\tcache.rawContent = fileContent;\n\tif (cache.normalizedLines.length === 0) {\n\t\tcache.normalizedLines.push(\"\");\n\t\tcache.highlightedLines.push(\"\");\n\t}\n\n\tconst segments = deltaNormalized.split(\"\\n\");\n\tconst lastIndex = cache.normalizedLines.length - 1;\n\tcache.normalizedLines[lastIndex] += segments[0];\n\tcache.highlightedLines[lastIndex] = highlightSingleLine(cache.normalizedLines[lastIndex], cache.lang);\n\tfor (let i = 1; i < segments.length; i++) {\n\t\tcache.normalizedLines.push(segments[i]);\n\t\tcache.highlightedLines.push(highlightSingleLine(segments[i], cache.lang));\n\t}\n\trefreshWriteHighlightPrefix(cache);\n\treturn cache;\n}\n\nfunction trimTrailingEmptyLines(lines: string[]): string[] {\n\tlet end = lines.length;\n\twhile (end > 0 && lines[end - 1] === \"\") {\n\t\tend--;\n\t}\n\treturn lines.slice(0, end);\n}\n\nfunction formatWriteCall(\n\targs: { path?: string; file_path?: string; content?: string } | undefined,\n\toptions: ToolRenderResultOptions,\n\ttheme: Theme,\n\tcache: WriteHighlightCache | undefined,\n\tcwd: string,\n): string {\n\tconst rawPath = str(args?.file_path ?? args?.path);\n\tconst fileContent = str(args?.content);\n\tconst pathDisplay = renderToolPath(rawPath, theme, cwd);\n\tlet text = `${theme.fg(\"toolTitle\", theme.bold(\"write\"))} ${pathDisplay}`;\n\n\tif (fileContent === null) {\n\t\ttext += `\\n\\n${theme.fg(\"error\", \"[invalid content arg - expected string]\")}`;\n\t} else if (fileContent) {\n\t\tconst lang = rawPath ? getLanguageFromPath(rawPath) : undefined;\n\t\tconst renderedLines = lang\n\t\t\t? (cache?.highlightedLines ?? highlightCode(replaceTabs(normalizeDisplayText(fileContent)), lang))\n\t\t\t: normalizeDisplayText(fileContent).split(\"\\n\");\n\t\tconst lines = trimTrailingEmptyLines(renderedLines);\n\t\tconst totalLines = lines.length;\n\t\tconst maxLines = options.expanded ? lines.length : 10;\n\t\tconst displayLines = lines.slice(0, maxLines);\n\t\tconst remaining = lines.length - maxLines;\n\t\ttext += `\\n\\n${displayLines.map((line) => (lang ? line : theme.fg(\"toolOutput\", replaceTabs(line)))).join(\"\\n\")}`;\n\t\tif (remaining > 0) {\n\t\t\ttext += `${theme.fg(\"muted\", `\\n... (${remaining} more lines, ${totalLines} total,`)} ${keyHint(\"app.tools.expand\", \"to expand\")}${theme.fg(\"muted\", \")\")}`;\n\t\t}\n\t}\n\n\treturn text;\n}\n\nfunction formatWriteResult(\n\tresult: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; isError?: boolean },\n\ttheme: Theme,\n): string | undefined {\n\tif (!result.isError) {\n\t\treturn undefined;\n\t}\n\tconst output = result.content\n\t\t.filter((c) => c.type === \"text\")\n\t\t.map((c) => c.text || \"\")\n\t\t.join(\"\\n\");\n\tif (!output) {\n\t\treturn undefined;\n\t}\n\treturn `\\n${theme.fg(\"error\", output)}`;\n}\n\nexport function createWriteToolDefinition(\n\tcwd: string,\n\toptions?: WriteToolOptions,\n): ToolDefinition<typeof writeSchema, undefined> {\n\tconst ops = options?.operations ?? defaultWriteOperations;\n\treturn {\n\t\tname: \"write\",\n\t\tlabel: \"write\",\n\t\tdescription:\n\t\t\t\"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.\",\n\t\tpromptSnippet: writeToolSystemPromptContribution.snippet,\n\t\tpromptGuidelines: [...writeToolSystemPromptContribution.guidelines],\n\t\tparameters: writeSchema,\n\t\tconstrainedSampling: { type: \"json_schema\", strict: \"prefer\" },\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ path, content }: { path: string; content: string },\n\t\t\tsignal?: AbortSignal,\n\t\t\t_onUpdate?,\n\t\t\tctx?: ToolExecuteContext,\n\t\t) {\n\t\t\tconst absolutePath = resolveToCwd(path, ctx?.cwd || cwd);\n\t\t\tconst dir = dirname(absolutePath);\n\t\t\treturn withFileMutationQueue(absolutePath, async () => {\n\t\t\t\t// Do not reject from an abort event listener here: that would release the\n\t\t\t\t// mutation queue while an in-flight filesystem operation may still finish.\n\t\t\t\t// Checking signal.aborted after each await observes the same aborts while\n\t\t\t\t// keeping the queue locked until the current operation has settled.\n\t\t\t\tconst throwIfAborted = (): void => {\n\t\t\t\t\tif (signal?.aborted) throw new Error(t(\"Operation aborted\"));\n\t\t\t\t};\n\n\t\t\t\tthrowIfAborted();\n\t\t\t\t// Create parent directories if needed.\n\t\t\t\tawait ops.mkdir(dir);\n\t\t\t\tthrowIfAborted();\n\n\t\t\t\t// Write the file contents.\n\t\t\t\tawait ops.writeFile(absolutePath, content);\n\t\t\t\tthrowIfAborted();\n\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: `Successfully wrote to ${path}` }],\n\t\t\t\t\tdetails: undefined,\n\t\t\t\t};\n\t\t\t});\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst renderArgs = args as { path?: string; file_path?: string; content?: string } | undefined;\n\t\t\tconst rawPath = str(renderArgs?.file_path ?? renderArgs?.path);\n\t\t\tconst fileContent = str(renderArgs?.content);\n\t\t\tconst component =\n\t\t\t\t(context.lastComponent as WriteCallRenderComponent | undefined) ?? new WriteCallRenderComponent();\n\t\t\tif (fileContent !== null) {\n\t\t\t\tcomponent.cache = context.argsComplete\n\t\t\t\t\t? rebuildWriteHighlightCacheFull(rawPath, fileContent)\n\t\t\t\t\t: updateWriteHighlightCacheIncremental(component.cache, rawPath, fileContent);\n\t\t\t} else {\n\t\t\t\tcomponent.cache = undefined;\n\t\t\t}\n\t\t\tcomponent.setText(\n\t\t\t\tformatWriteCall(\n\t\t\t\t\trenderArgs,\n\t\t\t\t\t{ expanded: context.expanded, isPartial: context.isPartial },\n\t\t\t\t\ttheme,\n\t\t\t\t\tcomponent.cache,\n\t\t\t\t\tcontext.cwd,\n\t\t\t\t),\n\t\t\t);\n\t\t\treturn component;\n\t\t},\n\t\trenderResult(result, _options, theme, context) {\n\t\t\tconst output = formatWriteResult({ ...result, isError: context.isError }, theme);\n\t\t\tif (!output) {\n\t\t\t\tconst component = (context.lastComponent as Container | undefined) ?? new Container();\n\t\t\t\tcomponent.clear();\n\t\t\t\treturn component;\n\t\t\t}\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(output);\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema> {\n\treturn wrapToolDefinition(createWriteToolDefinition(cwd, options));\n}\n"]}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAaA,OAAO,EAEN,KAAK,aAAa,EAMlB,MAAM,6BAA6B,CAAC;AAQrC,OAAO,KAAK,EAAE,cAAc,EAA+C,MAAM,mCAAmC,CAAC;AAErH,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,KAAK,wBAAwB,EAAoB,MAAM,kBAAkB,CAAC;AAEnF,OAAO,EAAE,KAAK,SAAS,EAAsB,MAAM,YAAY,CAAC;AAIhE,QAAA,MAAM,WAAW;;;;EASf,CAAC;AAEH,eAAO,MAAM,iCAAiC;;;CAMpC,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAChC,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,2FAA0F;IAC1F,YAAY,CAAC,EAAE;QAAE,MAAM,EAAE,KAAK,CAAA;KAAE,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,8BAA8B;IAC9B,SAAS,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,mCAAmC;IACnC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,kFAAiF;IACjF,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IAC3E,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5D;AAeD,MAAM,WAAW,gBAAgB;IAChC,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,oFAAoF;IACpF,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,8EAA8E;IAC9E,YAAY,CAAC,EAAE,wBAAwB,CAAC;CACxC;AA+JD,wBAAgB,yBAAyB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,gBAAgB,GACxB,cAAc,CAAC,OAAO,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC,CA2PlE;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,OAAO,WAAW,CAAC,CAEtG","sourcesContent":["// Migrated from packages/agent-forge/src/core/tools/write (batch 1, copy-then-delete);\n// host modules are imported through supply keys (@agent-forge/host/*).\n\nimport { randomUUID } from \"node:crypto\";\nimport { constants, renameSync } from \"node:fs\";\nimport {\n\taccess as fsAccess,\n\tmkdir as fsMkdir,\n\treadFile as fsReadFile,\n\twriteFile as fsWriteFile,\n} from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { countDiffLines } from \"@agent-forge/host/edit-diff\";\nimport {\n\tFileCoordinationError,\n\ttype StatVersionV1,\n\tsha256Hex,\n\tstatLooksChanged,\n\tstatVersionOf,\n\tstatVersionSync,\n\twithFileMutationLock,\n} from \"@agent-forge/host/file-lock\";\nimport { withFileMutationQueue } from \"@agent-forge/host/file-mutation-queue\";\nimport { t } from \"@agent-forge/host/i18n\";\nimport { keyHint } from \"@agent-forge/host/keybinding-hints\";\nimport { resolveToCwd } from \"@agent-forge/host/path-utils\";\nimport { formatPathRelativeToCwdOrAbsolute } from \"@agent-forge/host/paths\";\nimport { normalizeDisplayText, renderToolPath, replaceTabs, str } from \"@agent-forge/host/render-utils\";\nimport { getLanguageFromPath, highlightCode, type Theme } from \"@agent-forge/host/theme\";\nimport type { ToolDefinition, ToolExecuteContext, ToolRenderResultOptions } from \"@agent-forge/host/tool-definition\";\nimport { Container, Text } from \"@agent-forge/tui\";\nimport { type Static, Type } from \"typebox\";\nimport { commitPreparedContent } from \"./atomic-ops.ts\";\nimport { type CoordinationLeaseCheckV1, checkIntentLease } from \"./lease-check.ts\";\nimport { hasAtomicTier, probeSnapshot, readSnapshot } from \"./snapshot-ops.ts\";\nimport { type AgentTool, wrapToolDefinition } from \"./types.ts\";\nimport { forgetVersion, getRecordedVersion, recordVersion } from \"./version-registry.ts\";\nimport { assertWithinWriteScope } from \"./write-scope.ts\";\n\nconst writeSchema = Type.Object({\n\tpath: Type.String({ description: \"Path to the file to write (relative or absolute)\" }),\n\tcontent: Type.String({ description: \"Content to write to the file\" }),\n\texpectedVersion: Type.Optional(\n\t\tType.String({\n\t\t\tdescription:\n\t\t\t\t\"Optional sha256 of the current content. When set, the write fails if the file changed. Programmatic callers use this instead of an in-session read.\",\n\t\t}),\n\t),\n});\n\nexport const writeToolSystemPromptContribution = {\n\tsnippet: \"Create or overwrite files\",\n\tguidelines: [\n\t\t\"Use write only for new files or complete rewrites.\",\n\t\t\"Reading the file first is required before overwriting an existing file; without a prior read the write is rejected.\",\n\t],\n} as const;\n\nexport type WriteToolInput = Static<typeof writeSchema>;\n\nexport interface WriteToolDetails {\n\t/** Lines added by the write (empty text is 0 lines; \"a\" and \"a\\n\" are both 1 line). */\n\taddedLines: number;\n\t/** Lines removed from the previous content. Omitted when the previous content could not be read. */\n\tdeletedLines?: number;\n\t/** Set when the file did not exist before the write. */\n\tcreated?: true;\n\t/** Present only when the operations could not commit atomically (design §13.2 tier B). */\n\tcoordination?: { atomic: false };\n}\n\n/**\n * Pluggable operations for the write tool.\n * Override these to delegate file writing to remote systems (for example SSH).\n */\nexport interface WriteOperations {\n\t/** Read the current file contents (used to compute line-count details). */\n\treadFile?: (absolutePath: string) => Promise<Buffer>;\n\t/** Write content to a file */\n\twriteFile: (absolutePath: string, content: string) => Promise<void>;\n\t/** Create directory recursively */\n\tmkdir: (dir: string) => Promise<void>;\n\t/** Atomic-commit tier (design §13.2): all three required; see EditOperations. */\n\tstatVersion?: (absolutePath: string) => Promise<StatVersionV1 | undefined>;\n\twriteTemp?: (absolutePath: string, content: string) => Promise<string>;\n\tcommitSync?: (tempPath: string, targetPath: string) => void;\n}\n\nconst defaultWriteOperations: WriteOperations = {\n\treadFile: (path) => fsReadFile(path),\n\twriteFile: (path, content) => fsWriteFile(path, content, \"utf-8\"),\n\tmkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => {}),\n\tstatVersion: (path) => statVersionOf(path),\n\twriteTemp: async (path, content) => {\n\t\tconst tempPath = `${path}.${randomUUID()}.agent-forge-tmp`;\n\t\tawait fsWriteFile(tempPath, content, { encoding: \"utf-8\", mode: 0o600 });\n\t\treturn tempPath;\n\t},\n\tcommitSync: (tempPath, targetPath) => renameSync(tempPath, targetPath),\n};\n\nexport interface WriteToolOptions {\n\t/** Custom operations for file writing. Default: local filesystem */\n\toperations?: WriteOperations;\n\t/** Relative write-path globs from the child task profile; absent = unrestricted. */\n\twriteScope?: readonly string[];\n\t/** `file.coordination@1` consumer face; absent = no advisory lease checks. */\n\tcoordination?: CoordinationLeaseCheckV1;\n}\n\nfunction versionConflict(path: string, currentVersion: string, expectedVersion: string): FileCoordinationError {\n\treturn new FileCoordinationError(\n\t\t\"file_version_conflict\",\n\t\t`${path} changed on disk since it was read. Re-read the file and retry.`,\n\t\t{ path, currentVersion, expectedVersion },\n\t);\n}\n\n/** Reject a read-only target so the atomic replace cannot bypass the permission bit. */\nasync function ensureWritable(target: string, displayPath: string): Promise<void> {\n\ttry {\n\t\tawait fsAccess(target, constants.W_OK);\n\t} catch (error: unknown) {\n\t\tconst errorMessage = error instanceof Error && \"code\" in error ? `Error code: ${error.code}` : String(error);\n\t\tthrow new Error(t(\"Could not write file: {path}. {errorMessage}.\", { path: displayPath, errorMessage }));\n\t}\n}\n\ntype WriteHighlightCache = {\n\trawPath: string | null;\n\tlang: string;\n\trawContent: string;\n\tnormalizedLines: string[];\n\thighlightedLines: string[];\n};\n\nclass WriteCallRenderComponent extends Text {\n\tcache?: WriteHighlightCache;\n\n\tconstructor() {\n\t\tsuper(\"\", 0, 0);\n\t}\n}\n\nconst WRITE_PARTIAL_FULL_HIGHLIGHT_LINES = 50;\n\nfunction highlightSingleLine(line: string, lang: string): string {\n\tconst highlighted = highlightCode(line, lang);\n\treturn highlighted[0] ?? \"\";\n}\n\nfunction refreshWriteHighlightPrefix(cache: WriteHighlightCache): void {\n\tconst prefixCount = Math.min(WRITE_PARTIAL_FULL_HIGHLIGHT_LINES, cache.normalizedLines.length);\n\tif (prefixCount === 0) return;\n\tconst prefixSource = cache.normalizedLines.slice(0, prefixCount).join(\"\\n\");\n\tconst prefixHighlighted = highlightCode(prefixSource, cache.lang);\n\tfor (let i = 0; i < prefixCount; i++) {\n\t\tcache.highlightedLines[i] =\n\t\t\tprefixHighlighted[i] ?? highlightSingleLine(cache.normalizedLines[i] ?? \"\", cache.lang);\n\t}\n}\n\nfunction rebuildWriteHighlightCacheFull(rawPath: string | null, fileContent: string): WriteHighlightCache | undefined {\n\tconst lang = rawPath ? getLanguageFromPath(rawPath) : undefined;\n\tif (!lang) return undefined;\n\tconst displayContent = normalizeDisplayText(fileContent);\n\tconst normalized = replaceTabs(displayContent);\n\treturn {\n\t\trawPath,\n\t\tlang,\n\t\trawContent: fileContent,\n\t\tnormalizedLines: normalized.split(\"\\n\"),\n\t\thighlightedLines: highlightCode(normalized, lang),\n\t};\n}\n\nfunction updateWriteHighlightCacheIncremental(\n\tcache: WriteHighlightCache | undefined,\n\trawPath: string | null,\n\tfileContent: string,\n): WriteHighlightCache | undefined {\n\tconst lang = rawPath ? getLanguageFromPath(rawPath) : undefined;\n\tif (!lang) return undefined;\n\tif (!cache) return rebuildWriteHighlightCacheFull(rawPath, fileContent);\n\tif (cache.lang !== lang || cache.rawPath !== rawPath) return rebuildWriteHighlightCacheFull(rawPath, fileContent);\n\tif (!fileContent.startsWith(cache.rawContent)) return rebuildWriteHighlightCacheFull(rawPath, fileContent);\n\tif (fileContent.length === cache.rawContent.length) return cache;\n\n\tconst deltaRaw = fileContent.slice(cache.rawContent.length);\n\tconst deltaDisplay = normalizeDisplayText(deltaRaw);\n\tconst deltaNormalized = replaceTabs(deltaDisplay);\n\tcache.rawContent = fileContent;\n\tif (cache.normalizedLines.length === 0) {\n\t\tcache.normalizedLines.push(\"\");\n\t\tcache.highlightedLines.push(\"\");\n\t}\n\n\tconst segments = deltaNormalized.split(\"\\n\");\n\tconst lastIndex = cache.normalizedLines.length - 1;\n\tcache.normalizedLines[lastIndex] += segments[0];\n\tcache.highlightedLines[lastIndex] = highlightSingleLine(cache.normalizedLines[lastIndex], cache.lang);\n\tfor (let i = 1; i < segments.length; i++) {\n\t\tcache.normalizedLines.push(segments[i]);\n\t\tcache.highlightedLines.push(highlightSingleLine(segments[i], cache.lang));\n\t}\n\trefreshWriteHighlightPrefix(cache);\n\treturn cache;\n}\n\nfunction trimTrailingEmptyLines(lines: string[]): string[] {\n\tlet end = lines.length;\n\twhile (end > 0 && lines[end - 1] === \"\") {\n\t\tend--;\n\t}\n\treturn lines.slice(0, end);\n}\n\nfunction formatWriteCall(\n\targs: { path?: string; file_path?: string; content?: string } | undefined,\n\toptions: ToolRenderResultOptions,\n\ttheme: Theme,\n\tcache: WriteHighlightCache | undefined,\n\tcwd: string,\n): string {\n\tconst rawPath = str(args?.file_path ?? args?.path);\n\tconst fileContent = str(args?.content);\n\tconst pathDisplay = renderToolPath(rawPath, theme, cwd);\n\tlet text = `${theme.fg(\"toolTitle\", theme.bold(\"write\"))} ${pathDisplay}`;\n\n\tif (fileContent === null) {\n\t\ttext += `\\n\\n${theme.fg(\"error\", \"[invalid content arg - expected string]\")}`;\n\t} else if (fileContent) {\n\t\tconst lang = rawPath ? getLanguageFromPath(rawPath) : undefined;\n\t\tconst renderedLines = lang\n\t\t\t? (cache?.highlightedLines ?? highlightCode(replaceTabs(normalizeDisplayText(fileContent)), lang))\n\t\t\t: normalizeDisplayText(fileContent).split(\"\\n\");\n\t\tconst lines = trimTrailingEmptyLines(renderedLines);\n\t\tconst totalLines = lines.length;\n\t\tconst maxLines = options.expanded ? lines.length : 10;\n\t\tconst displayLines = lines.slice(0, maxLines);\n\t\tconst remaining = lines.length - maxLines;\n\t\ttext += `\\n\\n${displayLines.map((line) => (lang ? line : theme.fg(\"toolOutput\", replaceTabs(line)))).join(\"\\n\")}`;\n\t\tif (remaining > 0) {\n\t\t\ttext += `${theme.fg(\"muted\", `\\n... (${remaining} more lines, ${totalLines} total,`)} ${keyHint(\"app.tools.expand\", \"to expand\")}${theme.fg(\"muted\", \")\")}`;\n\t\t}\n\t}\n\n\treturn text;\n}\n\nfunction formatWriteResult(\n\tresult: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; isError?: boolean },\n\ttheme: Theme,\n): string | undefined {\n\tif (!result.isError) {\n\t\treturn undefined;\n\t}\n\tconst output = result.content\n\t\t.filter((c) => c.type === \"text\")\n\t\t.map((c) => c.text || \"\")\n\t\t.join(\"\\n\");\n\tif (!output) {\n\t\treturn undefined;\n\t}\n\treturn `\\n${theme.fg(\"error\", output)}`;\n}\n\nexport function createWriteToolDefinition(\n\tcwd: string,\n\toptions?: WriteToolOptions,\n): ToolDefinition<typeof writeSchema, WriteToolDetails | undefined> {\n\tconst ops = options?.operations ?? defaultWriteOperations;\n\tconst writeScope = options?.writeScope;\n\tconst coordination = options?.coordination;\n\treturn {\n\t\tname: \"write\",\n\t\tlabel: \"write\",\n\t\tdescription:\n\t\t\t\"Write content to a file. Creates the file if it doesn't exist. Overwriting an existing file requires that you have read it in this session first (or supplied expectedVersion); otherwise the write is rejected so a concurrent change is never silently lost. Automatically creates parent directories.\",\n\t\tpromptSnippet: writeToolSystemPromptContribution.snippet,\n\t\tpromptGuidelines: [...writeToolSystemPromptContribution.guidelines],\n\t\tparameters: writeSchema,\n\t\tconstrainedSampling: { type: \"json_schema\", strict: \"prefer\" },\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ path, content, expectedVersion }: { path: string; content: string; expectedVersion?: string },\n\t\t\tsignal?: AbortSignal,\n\t\t\t_onUpdate?,\n\t\t\tctx?: ToolExecuteContext,\n\t\t) {\n\t\t\tconst absolutePath = resolveToCwd(path, ctx?.cwd || cwd);\n\t\t\tconst dir = dirname(absolutePath);\n\t\t\tconst sessionId = ctx?.sessionManager?.getSessionId() ?? \"\";\n\n\t\t\treturn withFileMutationQueue(absolutePath, async () => {\n\t\t\t\t// Do not reject from an abort event listener here: that would release the\n\t\t\t\t// mutation queue while an in-flight filesystem operation may still finish.\n\t\t\t\t// Checking signal.aborted after each await observes the same aborts while\n\t\t\t\t// keeping the queue locked until the current operation has settled.\n\t\t\t\tconst throwIfAborted = (): void => {\n\t\t\t\t\tif (signal?.aborted) throw new Error(t(\"Operation aborted\"));\n\t\t\t\t};\n\n\t\t\t\tthrowIfAborted();\n\n\t\t\t\tconst lockOptions = {\n\t\t\t\t\t...(sessionId === \"\" ? {} : { sessionId }),\n\t\t\t\t\t...(signal === undefined ? {} : { signal }),\n\t\t\t\t};\n\t\t\t\treturn withFileMutationLock(absolutePath, lockOptions, async (lock) => {\n\t\t\t\t\tassertWithinWriteScope(lock.canonicalPath, ctx?.cwd || cwd, writeScope);\n\t\t\t\t\tconst target = lock.canonicalPath;\n\t\t\t\t\t// Advisory lease check (design §8.8): whole-file for write, inside\n\t\t\t\t\t// the lock, before any state mutation. Own leases are clear.\n\t\t\t\t\tawait checkIntentLease({\n\t\t\t\t\t\tcoordination,\n\t\t\t\t\t\townerSessionId: sessionId === \"\" ? undefined : sessionId,\n\t\t\t\t\t\tcanonicalPath: target,\n\t\t\t\t\t\tlockToken: lock.token,\n\t\t\t\t\t\tdisplayPath: path,\n\t\t\t\t\t});\n\t\t\t\t\tconst atomicTier = hasAtomicTier(ops);\n\t\t\t\t\tconst live = await probeSnapshot(ops, target);\n\t\t\t\t\tconst recorded = sessionId === \"\" ? undefined : getRecordedVersion(sessionId, target);\n\n\t\t\t\t\tlet oldContent: string | undefined;\n\t\t\t\t\tlet created: true | undefined;\n\t\t\t\t\tlet expectedStat = live.stat;\n\t\t\t\t\t// Tier B has no stat: remember the version we validated so the commit can\n\t\t\t\t\t// compare content instead of mtime.\n\t\t\t\t\tlet expectedHash: string | undefined = live.snapshot?.hash;\n\n\t\t\t\t\tif (live.exists === false) {\n\t\t\t\t\t\t// The file is gone. If this session (or the caller) expected it to exist,\n\t\t\t\t\t\t// say so instead of silently recreating it.\n\t\t\t\t\t\tif (expectedVersion !== undefined) {\n\t\t\t\t\t\t\tthrow new FileCoordinationError(\n\t\t\t\t\t\t\t\t\"file_missing\",\n\t\t\t\t\t\t\t\t`${path} no longer exists, but expectedVersion was supplied. Re-read before writing.`,\n\t\t\t\t\t\t\t\t{ path, expectedVersion },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif (recorded !== undefined) {\n\t\t\t\t\t\t\tif (sessionId !== \"\") forgetVersion(sessionId, target);\n\t\t\t\t\t\t\tthrow new FileCoordinationError(\n\t\t\t\t\t\t\t\t\"file_missing\",\n\t\t\t\t\t\t\t\t`${path} was deleted after this session read it. The recorded version was cleared; write again to recreate it.`,\n\t\t\t\t\t\t\t\t{ path },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tcreated = true;\n\t\t\t\t\t\toldContent = \"\";\n\t\t\t\t\t} else if (live.exists === \"unknown\") {\n\t\t\t\t\t\t// No read primitive: existence and version are unknowable, so the\n\t\t\t\t\t\t// read-before-write guarantee cannot be enforced. Fail rather than\n\t\t\t\t\t\t// silently falling back to a blind overwrite.\n\t\t\t\t\t\tthrow new FileCoordinationError(\n\t\t\t\t\t\t\t\"coordination_unavailable\",\n\t\t\t\t\t\t\t`${path}: write operations cannot read the target, so overwrite safety cannot be enforced.`,\n\t\t\t\t\t\t\t{ path, reason: \"operations_cannot_read\" },\n\t\t\t\t\t\t);\n\t\t\t\t\t} else {\n\t\t\t\t\t\t// Existing file: a blind overwrite is exactly the lost-update case this\n\t\t\t\t\t\t// design exists to prevent.\n\t\t\t\t\t\tif (expectedVersion === undefined && recorded === undefined) {\n\t\t\t\t\t\t\tthrow new FileCoordinationError(\n\t\t\t\t\t\t\t\t\"write_read_required\",\n\t\t\t\t\t\t\t\t`${path} already exists and this session has not read it. Call read first, or pass expectedVersion.`,\n\t\t\t\t\t\t\t\t{ path },\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// A read-only target must keep failing: atomic replace would otherwise\n\t\t\t\t\t\t// bypass the permission bit. Only tier A can check this locally; tier B\n\t\t\t\t\t\t// has no access primitive in its operations contract.\n\t\t\t\t\t\tif (atomicTier) await ensureWritable(target, path);\n\n\t\t\t\t\t\tif (expectedVersion !== undefined) {\n\t\t\t\t\t\t\t// Explicit expectation always wins and is never satisfied by the cache.\n\t\t\t\t\t\t\tconst snapshot = await readSnapshot(ops, target);\n\t\t\t\t\t\t\tif (snapshot === undefined) {\n\t\t\t\t\t\t\t\tthrow new FileCoordinationError(\"file_missing\", `${path} disappeared during the write.`, {\n\t\t\t\t\t\t\t\t\tpath,\n\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tif (snapshot.hash !== expectedVersion) {\n\t\t\t\t\t\t\t\tthrow versionConflict(path, snapshot.hash, expectedVersion);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\toldContent = snapshot.content.toString(\"utf-8\");\n\t\t\t\t\t\t\texpectedStat = snapshot.stat;\n\t\t\t\t\t\t\texpectedHash = snapshot.hash;\n\t\t\t\t\t\t} else if (recorded !== undefined) {\n\t\t\t\t\t\t\t// Tier A can skip the re-read when stat is unchanged; tier B must hash.\n\t\t\t\t\t\t\tconst unchanged =\n\t\t\t\t\t\t\t\tatomicTier && live.stat !== undefined && !statLooksChanged(live.stat, recorded.stat);\n\t\t\t\t\t\t\tif (!unchanged) {\n\t\t\t\t\t\t\t\tconst snapshot = await readSnapshot(ops, target);\n\t\t\t\t\t\t\t\tif (snapshot === undefined) {\n\t\t\t\t\t\t\t\t\tthrow new FileCoordinationError(\"file_missing\", `${path} disappeared during the write.`, {\n\t\t\t\t\t\t\t\t\t\tpath,\n\t\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tif (snapshot.hash !== recorded.hash) {\n\t\t\t\t\t\t\t\t\tthrow versionConflict(path, snapshot.hash, recorded.hash);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\toldContent = snapshot.content.toString(\"utf-8\");\n\t\t\t\t\t\t\t\texpectedStat = snapshot.stat;\n\t\t\t\t\t\t\t\texpectedHash = snapshot.hash;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t// stat unchanged: skip the re-read and the hash (same-fd snapshot guarantees\n\t\t\t\t\t\t\t// the recorded hash belongs to this stat). deletedLines stays omitted.\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\n\t\t\t\t\tthrowIfAborted();\n\t\t\t\t\tawait ops.mkdir(dir);\n\t\t\t\t\tthrowIfAborted();\n\n\t\t\t\t\tconst committed = await commitPreparedContent({\n\t\t\t\t\t\tops,\n\t\t\t\t\t\tlock,\n\t\t\t\t\t\ttargetPath: target,\n\t\t\t\t\t\tcontent,\n\t\t\t\t\t\texpectedStat: created === true ? undefined : expectedStat,\n\t\t\t\t\t\texpectedHash: created === true ? undefined : expectedHash,\n\t\t\t\t\t\tmakeMismatchError: () => {\n\t\t\t\t\t\t\tconst current = statVersionSync(target);\n\t\t\t\t\t\t\treturn current === undefined\n\t\t\t\t\t\t\t\t? new FileCoordinationError(\n\t\t\t\t\t\t\t\t\t\t\"file_missing\",\n\t\t\t\t\t\t\t\t\t\t`${path} disappeared while the write was being committed.`,\n\t\t\t\t\t\t\t\t\t\t{ path },\n\t\t\t\t\t\t\t\t\t)\n\t\t\t\t\t\t\t\t: new FileCoordinationError(\n\t\t\t\t\t\t\t\t\t\t\"file_version_conflict\",\n\t\t\t\t\t\t\t\t\t\t`${path} changed while the write was being committed. Re-read the file and retry.`,\n\t\t\t\t\t\t\t\t\t\t{ path, currentVersion: current.mtimeNs, expectedVersion: expectedStat?.mtimeNs ?? \"\" },\n\t\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t},\n\t\t\t\t\t});\n\t\t\t\t\tthrowIfAborted();\n\n\t\t\t\t\tif (sessionId !== \"\") {\n\t\t\t\t\t\tconst after = await probeSnapshot(ops, target);\n\t\t\t\t\t\trecordVersion(sessionId, target, {\n\t\t\t\t\t\t\thash: await sha256Hex(Buffer.from(content, \"utf-8\")),\n\t\t\t\t\t\t\t...(after.stat === undefined ? {} : { stat: after.stat }),\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\n\t\t\t\t\tlet details: WriteToolDetails;\n\t\t\t\t\tif (oldContent !== undefined) {\n\t\t\t\t\t\tconst stats = countDiffLines(oldContent, content);\n\t\t\t\t\t\tdetails = created\n\t\t\t\t\t\t\t? { addedLines: stats.addedLines, deletedLines: 0, created }\n\t\t\t\t\t\t\t: { addedLines: stats.addedLines, deletedLines: stats.deletedLines };\n\t\t\t\t\t} else {\n\t\t\t\t\t\t// Old content unknown: only the new content's line count is known.\n\t\t\t\t\t\tdetails = { addedLines: countDiffLines(\"\", content).addedLines };\n\t\t\t\t\t}\n\t\t\t\t\tif (!committed.atomic) details.coordination = { atomic: false };\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: `Successfully wrote to ${path}` }],\n\t\t\t\t\t\tdetails,\n\t\t\t\t\t};\n\t\t\t\t});\n\t\t\t});\n\t\t},\n\t\tquietSummary(\n\t\t\targs: WriteToolInput,\n\t\t\tcontext: { cwd: string; isError: boolean; isPartial: boolean; details: WriteToolDetails | undefined },\n\t\t): string | undefined {\n\t\t\tconst rawPath = str(args?.path);\n\t\t\tif (!rawPath) return undefined;\n\t\t\tconst pathDisplay = formatPathRelativeToCwdOrAbsolute(rawPath, context.cwd);\n\t\t\tlet text = `write ${pathDisplay}`;\n\t\t\tconst details = context.details;\n\t\t\tif (details && !context.isError) {\n\t\t\t\ttext += ` +${details.addedLines}`;\n\t\t\t\tif (details.deletedLines !== undefined) {\n\t\t\t\t\ttext += ` -${details.deletedLines}`;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn text;\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst renderArgs = args as { path?: string; file_path?: string; content?: string } | undefined;\n\t\t\tconst rawPath = str(renderArgs?.file_path ?? renderArgs?.path);\n\t\t\tconst fileContent = str(renderArgs?.content);\n\t\t\tconst component =\n\t\t\t\t(context.lastComponent as WriteCallRenderComponent | undefined) ?? new WriteCallRenderComponent();\n\t\t\tif (fileContent !== null) {\n\t\t\t\tcomponent.cache = context.argsComplete\n\t\t\t\t\t? rebuildWriteHighlightCacheFull(rawPath, fileContent)\n\t\t\t\t\t: updateWriteHighlightCacheIncremental(component.cache, rawPath, fileContent);\n\t\t\t} else {\n\t\t\t\tcomponent.cache = undefined;\n\t\t\t}\n\t\t\tcomponent.setText(\n\t\t\t\tformatWriteCall(\n\t\t\t\t\trenderArgs,\n\t\t\t\t\t{ expanded: context.expanded, isPartial: context.isPartial },\n\t\t\t\t\ttheme,\n\t\t\t\t\tcomponent.cache,\n\t\t\t\t\tcontext.cwd,\n\t\t\t\t),\n\t\t\t);\n\t\t\treturn component;\n\t\t},\n\t\trenderResult(result, _options, theme, context) {\n\t\t\tconst output = formatWriteResult({ ...result, isError: context.isError }, theme);\n\t\t\tif (!output) {\n\t\t\t\tconst component = (context.lastComponent as Container | undefined) ?? new Container();\n\t\t\t\tcomponent.clear();\n\t\t\t\treturn component;\n\t\t\t}\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(output);\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema> {\n\treturn wrapToolDefinition(createWriteToolDefinition(cwd, options));\n}\n"]}

package/dist/write.js

@@ -1,28 +1,65 @@
 // Migrated from packages/agent-forge/src/core/tools/write (batch 1, copy-then-delete);
 // host modules are imported through supply keys (@agent-forge/host/*).
-import { mkdir as fsMkdir, writeFile as fsWriteFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { constants, renameSync } from "node:fs";
+import { access as fsAccess, mkdir as fsMkdir, readFile as fsReadFile, writeFile as fsWriteFile, } from "node:fs/promises";
 import { dirname } from "node:path";
+import { countDiffLines } from "@agent-forge/host/edit-diff";
+import { FileCoordinationError, sha256Hex, statLooksChanged, statVersionOf, statVersionSync, withFileMutationLock, } from "@agent-forge/host/file-lock";
 import { withFileMutationQueue } from "@agent-forge/host/file-mutation-queue";
 import { t } from "@agent-forge/host/i18n";
 import { keyHint } from "@agent-forge/host/keybinding-hints";
 import { resolveToCwd } from "@agent-forge/host/path-utils";
+import { formatPathRelativeToCwdOrAbsolute } from "@agent-forge/host/paths";
 import { normalizeDisplayText, renderToolPath, replaceTabs, str } from "@agent-forge/host/render-utils";
 import { getLanguageFromPath, highlightCode } from "@agent-forge/host/theme";
 import { Container, Text } from "@agent-forge/tui";
 import { Type } from "typebox";
+import { commitPreparedContent } from "./atomic-ops.js";
+import { checkIntentLease } from "./lease-check.js";
+import { hasAtomicTier, probeSnapshot, readSnapshot } from "./snapshot-ops.js";
 import { wrapToolDefinition } from "./types.js";
+import { forgetVersion, getRecordedVersion, recordVersion } from "./version-registry.js";
+import { assertWithinWriteScope } from "./write-scope.js";
 const writeSchema = Type.Object({
     path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
     content: Type.String({ description: "Content to write to the file" }),
+    expectedVersion: Type.Optional(Type.String({
+        description: "Optional sha256 of the current content. When set, the write fails if the file changed. Programmatic callers use this instead of an in-session read.",
+    })),
 });
 export const writeToolSystemPromptContribution = {
     snippet: "Create or overwrite files",
-    guidelines: ["Use write only for new files or complete rewrites."],
+    guidelines: [
+        "Use write only for new files or complete rewrites.",
+        "Reading the file first is required before overwriting an existing file; without a prior read the write is rejected.",
+    ],
 };
 const defaultWriteOperations = {
+    readFile: (path) => fsReadFile(path),
     writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
     mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => { }),
+    statVersion: (path) => statVersionOf(path),
+    writeTemp: async (path, content) => {
+        const tempPath = `${path}.${randomUUID()}.agent-forge-tmp`;
+        await fsWriteFile(tempPath, content, { encoding: "utf-8", mode: 0o600 });
+        return tempPath;
+    },
+    commitSync: (tempPath, targetPath) => renameSync(tempPath, targetPath),
 };
+function versionConflict(path, currentVersion, expectedVersion) {
+    return new FileCoordinationError("file_version_conflict", `${path} changed on disk since it was read. Re-read the file and retry.`, { path, currentVersion, expectedVersion });
+}
+/** Reject a read-only target so the atomic replace cannot bypass the permission bit. */
+async function ensureWritable(target, displayPath) {
+    try {
+        await fsAccess(target, constants.W_OK);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error && "code" in error ? `Error code: ${error.code}` : String(error);
+        throw new Error(t("Could not write file: {path}. {errorMessage}.", { path: displayPath, errorMessage }));
+    }
+}
 class WriteCallRenderComponent extends Text {
     cache;
     constructor() {
@@ -137,17 +174,20 @@ function formatWriteResult(result, theme) {
 }
 export function createWriteToolDefinition(cwd, options) {
     const ops = options?.operations ?? defaultWriteOperations;
+    const writeScope = options?.writeScope;
+    const coordination = options?.coordination;
     return {
         name: "write",
         label: "write",
-        description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+        description: "Write content to a file. Creates the file if it doesn't exist. Overwriting an existing file requires that you have read it in this session first (or supplied expectedVersion); otherwise the write is rejected so a concurrent change is never silently lost. Automatically creates parent directories.",
         promptSnippet: writeToolSystemPromptContribution.snippet,
         promptGuidelines: [...writeToolSystemPromptContribution.guidelines],
         parameters: writeSchema,
         constrainedSampling: { type: "json_schema", strict: "prefer" },
-        async execute(_toolCallId, { path, content }, signal, _onUpdate, ctx) {
+        async execute(_toolCallId, { path, content, expectedVersion }, signal, _onUpdate, ctx) {
             const absolutePath = resolveToCwd(path, ctx?.cwd || cwd);
             const dir = dirname(absolutePath);
+            const sessionId = ctx?.sessionManager?.getSessionId() ?? "";
             return withFileMutationQueue(absolutePath, async () => {
                 // Do not reject from an abort event listener here: that would release the
                 // mutation queue while an in-flight filesystem operation may still finish.
@@ -158,18 +198,158 @@ export function createWriteToolDefinition(cwd, options) {
                         throw new Error(t("Operation aborted"));
                 };
                 throwIfAborted();
-                // Create parent directories if needed.
-                await ops.mkdir(dir);
-                throwIfAborted();
-                // Write the file contents.
-                await ops.writeFile(absolutePath, content);
-                throwIfAborted();
-                return {
-                    content: [{ type: "text", text: `Successfully wrote to ${path}` }],
-                    details: undefined,
+                const lockOptions = {
+                    ...(sessionId === "" ? {} : { sessionId }),
+                    ...(signal === undefined ? {} : { signal }),
                 };
+                return withFileMutationLock(absolutePath, lockOptions, async (lock) => {
+                    assertWithinWriteScope(lock.canonicalPath, ctx?.cwd || cwd, writeScope);
+                    const target = lock.canonicalPath;
+                    // Advisory lease check (design §8.8): whole-file for write, inside
+                    // the lock, before any state mutation. Own leases are clear.
+                    await checkIntentLease({
+                        coordination,
+                        ownerSessionId: sessionId === "" ? undefined : sessionId,
+                        canonicalPath: target,
+                        lockToken: lock.token,
+                        displayPath: path,
+                    });
+                    const atomicTier = hasAtomicTier(ops);
+                    const live = await probeSnapshot(ops, target);
+                    const recorded = sessionId === "" ? undefined : getRecordedVersion(sessionId, target);
+                    let oldContent;
+                    let created;
+                    let expectedStat = live.stat;
+                    // Tier B has no stat: remember the version we validated so the commit can
+                    // compare content instead of mtime.
+                    let expectedHash = live.snapshot?.hash;
+                    if (live.exists === false) {
+                        // The file is gone. If this session (or the caller) expected it to exist,
+                        // say so instead of silently recreating it.
+                        if (expectedVersion !== undefined) {
+                            throw new FileCoordinationError("file_missing", `${path} no longer exists, but expectedVersion was supplied. Re-read before writing.`, { path, expectedVersion });
+                        }
+                        if (recorded !== undefined) {
+                            if (sessionId !== "")
+                                forgetVersion(sessionId, target);
+                            throw new FileCoordinationError("file_missing", `${path} was deleted after this session read it. The recorded version was cleared; write again to recreate it.`, { path });
+                        }
+                        created = true;
+                        oldContent = "";
+                    }
+                    else if (live.exists === "unknown") {
+                        // No read primitive: existence and version are unknowable, so the
+                        // read-before-write guarantee cannot be enforced. Fail rather than
+                        // silently falling back to a blind overwrite.
+                        throw new FileCoordinationError("coordination_unavailable", `${path}: write operations cannot read the target, so overwrite safety cannot be enforced.`, { path, reason: "operations_cannot_read" });
+                    }
+                    else {
+                        // Existing file: a blind overwrite is exactly the lost-update case this
+                        // design exists to prevent.
+                        if (expectedVersion === undefined && recorded === undefined) {
+                            throw new FileCoordinationError("write_read_required", `${path} already exists and this session has not read it. Call read first, or pass expectedVersion.`, { path });
+                        }
+                        // A read-only target must keep failing: atomic replace would otherwise
+                        // bypass the permission bit. Only tier A can check this locally; tier B
+                        // has no access primitive in its operations contract.
+                        if (atomicTier)
+                            await ensureWritable(target, path);
+                        if (expectedVersion !== undefined) {
+                            // Explicit expectation always wins and is never satisfied by the cache.
+                            const snapshot = await readSnapshot(ops, target);
+                            if (snapshot === undefined) {
+                                throw new FileCoordinationError("file_missing", `${path} disappeared during the write.`, {
+                                    path,
+                                });
+                            }
+                            if (snapshot.hash !== expectedVersion) {
+                                throw versionConflict(path, snapshot.hash, expectedVersion);
+                            }
+                            oldContent = snapshot.content.toString("utf-8");
+                            expectedStat = snapshot.stat;
+                            expectedHash = snapshot.hash;
+                        }
+                        else if (recorded !== undefined) {
+                            // Tier A can skip the re-read when stat is unchanged; tier B must hash.
+                            const unchanged = atomicTier && live.stat !== undefined && !statLooksChanged(live.stat, recorded.stat);
+                            if (!unchanged) {
+                                const snapshot = await readSnapshot(ops, target);
+                                if (snapshot === undefined) {
+                                    throw new FileCoordinationError("file_missing", `${path} disappeared during the write.`, {
+                                        path,
+                                    });
+                                }
+                                if (snapshot.hash !== recorded.hash) {
+                                    throw versionConflict(path, snapshot.hash, recorded.hash);
+                                }
+                                oldContent = snapshot.content.toString("utf-8");
+                                expectedStat = snapshot.stat;
+                                expectedHash = snapshot.hash;
+                            }
+                            // stat unchanged: skip the re-read and the hash (same-fd snapshot guarantees
+                            // the recorded hash belongs to this stat). deletedLines stays omitted.
+                        }
+                    }
+                    throwIfAborted();
+                    await ops.mkdir(dir);
+                    throwIfAborted();
+                    const committed = await commitPreparedContent({
+                        ops,
+                        lock,
+                        targetPath: target,
+                        content,
+                        expectedStat: created === true ? undefined : expectedStat,
+                        expectedHash: created === true ? undefined : expectedHash,
+                        makeMismatchError: () => {
+                            const current = statVersionSync(target);
+                            return current === undefined
+                                ? new FileCoordinationError("file_missing", `${path} disappeared while the write was being committed.`, { path })
+                                : new FileCoordinationError("file_version_conflict", `${path} changed while the write was being committed. Re-read the file and retry.`, { path, currentVersion: current.mtimeNs, expectedVersion: expectedStat?.mtimeNs ?? "" });
+                        },
+                    });
+                    throwIfAborted();
+                    if (sessionId !== "") {
+                        const after = await probeSnapshot(ops, target);
+                        recordVersion(sessionId, target, {
+                            hash: await sha256Hex(Buffer.from(content, "utf-8")),
+                            ...(after.stat === undefined ? {} : { stat: after.stat }),
+                        });
+                    }
+                    let details;
+                    if (oldContent !== undefined) {
+                        const stats = countDiffLines(oldContent, content);
+                        details = created
+                            ? { addedLines: stats.addedLines, deletedLines: 0, created }
+                            : { addedLines: stats.addedLines, deletedLines: stats.deletedLines };
+                    }
+                    else {
+                        // Old content unknown: only the new content's line count is known.
+                        details = { addedLines: countDiffLines("", content).addedLines };
+                    }
+                    if (!committed.atomic)
+                        details.coordination = { atomic: false };
+                    return {
+                        content: [{ type: "text", text: `Successfully wrote to ${path}` }],
+                        details,
+                    };
+                });
             });
         },
+        quietSummary(args, context) {
+            const rawPath = str(args?.path);
+            if (!rawPath)
+                return undefined;
+            const pathDisplay = formatPathRelativeToCwdOrAbsolute(rawPath, context.cwd);
+            let text = `write ${pathDisplay}`;
+            const details = context.details;
+            if (details && !context.isError) {
+                text += ` +${details.addedLines}`;
+                if (details.deletedLines !== undefined) {
+                    text += ` -${details.deletedLines}`;
+                }
+            }
+            return text;
+        },
         renderCall(args, theme, context) {
             const renderArgs = args;
             const rawPath = str(renderArgs?.file_path ?? renderArgs?.path);