@bubblebrain-ai/bubble 0.0.5 → 0.0.6

package/dist/provider.js

@@ -4,9 +4,25 @@
  * Works with OpenRouter, OpenAI, DeepSeek, Google, Groq, Together, and local OpenAI-compatible endpoints.
  */
 import OpenAI from "openai";
+import { appendFileSync } from "node:fs";
 import { createOpenAICodexProvider, isOpenAICodexBaseUrl } from "./provider-openai-codex.js";
 import { createProviderProtocolArtifactFilter } from "./provider-artifacts.js";
 import { resolveProviderRequestConfig } from "./provider-transform.js";
+// Diagnostic logger for tool-args byte-loss investigation. Activate with
+//   BUBBLE_DEBUG_TOOL_ARGS=/path/to/log.jsonl   (any writable path)
+// Each line is a JSON record describing a transition. When debugging is off,
+// the function is a no-op and free.
+const TOOL_ARGS_DEBUG_PATH = process.env.BUBBLE_DEBUG_TOOL_ARGS?.trim();
+function debugToolArgs(event) {
+    if (!TOOL_ARGS_DEBUG_PATH)
+        return;
+    try {
+        appendFileSync(TOOL_ARGS_DEBUG_PATH, JSON.stringify({ t: Date.now(), ...event }) + "\n", "utf-8");
+    }
+    catch {
+        // Diagnostic failures must not affect the model session.
+    }
+}
 export function toChatCompletionsMessage(message, options = {}) {
     const reasoningContentEcho = options.reasoningContentEcho ?? "tool_calls";
     if (message.role === "assistant") {
@@ -91,7 +107,9 @@ export function createProviderInstance(options) {
         const stream = (await client.chat.completions.create(body, {
             signal: chatOptions.abortSignal,
         }));
-        yield* translateOpenAIStream(stream);
+        yield* translateOpenAIStream(stream, {
+            toolArgsMergeMode: resolveToolArgsMergeMode(options.providerId || "", options.baseURL),
+        });
         yield { type: "done" };
     }
     async function complete(messages, chatOptions) {
@@ -118,19 +136,16 @@ export function createProviderInstance(options) {
     }
     return { streamChat, complete };
 }
-// Some providers (notably Fireworks-hosted Kimi) stream tool-call arguments
-// as repeated full snapshots in each delta instead of incremental chunks, so
-// a naive `+=` produces `{"x":1}{"x":1}` — not valid JSON. Parse the raw
-// stream; if it doesn't parse but contains a balanced `{…}` prefix or suffix
-// that does, use that. Empty or unsalvageable input becomes `"{}"` so the
-// downstream echo to the model is always valid JSON.
-export function normalizeToolArgs(raw) {
+export function normalizeToolArgsDetailed(raw) {
     const s = (raw ?? "").trim();
-    if (!s)
-        return "{}";
+    if (!s) {
+        debugToolArgs({ stage: "normalize", input: raw, output: "{}", reason: "empty" });
+        return { args: "{}", corrupt: false };
+    }
     try {
         JSON.parse(s);
-        return s;
+        debugToolArgs({ stage: "normalize", input: raw, output: s, reason: "passthrough" });
+        return { args: s, corrupt: false };
     }
     catch { }
     const firstBrace = extractBalancedJson(s, 0);
@@ -139,21 +154,39 @@ export function normalizeToolArgs(raw) {
             JSON.parse(firstBrace);
         }
         catch {
-            return "{}";
+            debugToolArgs({ stage: "normalize", input: raw, output: "{}", reason: "first-brace-unparseable", firstBrace });
+            return { args: "{}", corrupt: true };
         }
         // If the content after the first balanced object is another valid object
         // with the same parse, we've got a snapshot duplication — keep one copy.
         const rest = s.slice(firstBrace.length).trim();
-        if (!rest)
-            return firstBrace;
+        if (!rest) {
+            debugToolArgs({ stage: "normalize", input: raw, output: firstBrace, reason: "single-brace" });
+            return { args: firstBrace, corrupt: false };
+        }
         try {
             JSON.parse(rest);
-            return firstBrace;
+            debugToolArgs({ stage: "normalize", input: raw, output: firstBrace, reason: "snapshot-dedup", rest });
+            return { args: firstBrace, corrupt: false };
         }
         catch { }
-        return firstBrace;
+        debugToolArgs({ stage: "normalize", input: raw, output: firstBrace, reason: "trailing-junk-dropped", rest });
+        return { args: firstBrace, corrupt: false };
     }
-    return "{}";
+    debugToolArgs({ stage: "normalize", input: raw, output: "{}", reason: "no-balanced-json" });
+    return { args: "{}", corrupt: true };
+}
+export function normalizeToolArgs(raw) {
+    return normalizeToolArgsDetailed(raw).args;
+}
+function resolveToolArgsMergeMode(providerId, baseURL) {
+    const id = providerId.toLowerCase();
+    const url = baseURL.toLowerCase();
+    // Fireworks-hosted Kimi has been observed to stream cumulative snapshots
+    // rather than OpenAI-style argument deltas.
+    if (id === "fireworks" || url.includes("fireworks.ai"))
+        return "snapshot";
+    return "delta";
 }
 function extractBalancedJson(s, start) {
     if (s[start] !== "{")
@@ -195,9 +228,16 @@ function extractBalancedJson(s, start) {
  * partial write previews before the tool executes. End events are still flushed
  * in index order to keep multi-call turns deterministic.
  */
-export async function* translateOpenAIStream(stream) {
+export async function* translateOpenAIStream(stream, options = {}) {
     const toolCalls = new Map();
     const textFilter = createProviderProtocolArtifactFilter();
+    const toolArgsMergeMode = options.toolArgsMergeMode ?? "delta";
+    // DeepSeek (and some inference re-hosts) sometimes deliver reasoning twice:
+    // once via a dedicated `reasoning_content` / `thinking` field, and again
+    // embedded as `<think>...</think>` inside `delta.content`. Track whether we
+    // have seen the dedicated channel; if yes, strip <think> blocks from text
+    // silently instead of yielding a second reasoning_delta.
+    let hasDedicatedReasoningChannel = false;
     function* flushToolCalls() {
         if (toolCalls.size === 0)
             return;
@@ -212,12 +252,15 @@ export async function* translateOpenAIStream(stream) {
                     yield { type: "tool_call", id: entry.id, name: entry.name, arguments: entry.args, isStart: false, isEnd: false };
                 }
             }
+            const normalized = normalizeToolArgsDetailed(entry.args);
+            debugToolArgs({ stage: "flush-end", id: entry.id, name: entry.name, entryArgs: entry.args, finalArgs: normalized.args, corrupt: normalized.corrupt });
             yield {
                 type: "tool_call",
                 id: entry.id,
                 name: entry.name,
                 arguments: "",
-                argumentsFull: normalizeToolArgs(entry.args),
+                argumentsFull: normalized.args,
+                argumentsCorrupt: normalized.corrupt || undefined,
                 isStart: false,
                 isEnd: true,
             };
@@ -253,12 +296,13 @@ export async function* translateOpenAIStream(stream) {
         }
         const reasoning = delta?.reasoning ?? delta?.thinking ?? delta?.reasoning_content;
         if (reasoning) {
+            hasDedicatedReasoningChannel = true;
             yield { type: "reasoning_delta", content: reasoning };
         }
         if (delta?.content) {
             const thinkMatch = delta.content.match(/<think>([\s\S]*?)<\/think>/);
             if (thinkMatch) {
-                if (thinkMatch[1]) {
+                if (thinkMatch[1] && !hasDedicatedReasoningChannel) {
                     yield { type: "reasoning_delta", content: thinkMatch[1] };
                 }
                 const remaining = delta.content.replace(/<think>[\s\S]*?<\/think>/, "");
@@ -288,7 +332,8 @@ export async function* translateOpenAIStream(stream) {
                     entry.name = tc.function.name;
                 yield* startToolCallIfReady(entry);
                 if (typeof tc.function?.arguments === "string" && tc.function.arguments) {
-                    const merged = mergeToolArgumentDelta(entry.args, tc.function.arguments);
+                    debugToolArgs({ stage: "raw-chunk", id: entry.id, name: entry.name, idx, raw: tc.function.arguments });
+                    const merged = mergeToolArgumentDelta(entry.args, tc.function.arguments, toolArgsMergeMode);
                     entry.args = merged.args;
                     if (entry.started && merged.delta) {
                         yield {
@@ -314,22 +359,30 @@ export async function* translateOpenAIStream(stream) {
     }
     yield* flushToolCalls();
 }
-function mergeToolArgumentDelta(current, incoming) {
-    if (!current)
+function mergeToolArgumentDelta(current, incoming, mode) {
+    if (!current) {
+        debugToolArgs({ stage: "merge", branch: "empty-current", current, incoming, args: incoming, delta: incoming });
         return { args: incoming, delta: incoming };
-    if (!incoming)
-        return { args: current, delta: "" };
-    // Standard OpenAI-compatible streams send incremental argument deltas. Some
-    // providers send cumulative snapshots instead. If the incoming chunk already
-    // contains what we have, emit only the new suffix so downstream state remains
-    // append-only.
-    if (incoming.startsWith(current)) {
-        return { args: incoming, delta: incoming.slice(current.length) };
     }
-    // Repeated identical snapshots should not duplicate the TUI preview or final
-    // JSON arguments.
-    if (incoming === current || current.endsWith(incoming)) {
+    if (!incoming) {
+        debugToolArgs({ stage: "merge", branch: "empty-incoming", current, incoming, args: current, delta: "" });
         return { args: current, delta: "" };
     }
+    if (mode === "snapshot") {
+        // Snapshot streams repeat the current full argument buffer. Only treat a
+        // chunk as duplicate when it is exactly equal, or as growth when it carries
+        // the current buffer as a prefix. A suffix match is not enough: the next
+        // legitimate delta can be a single trailing character like "0".
+        if (incoming === current) {
+            debugToolArgs({ stage: "merge", branch: "snapshot-dup", current, incoming, args: current, delta: "" });
+            return { args: current, delta: "" };
+        }
+        if (incoming.startsWith(current)) {
+            const delta = incoming.slice(current.length);
+            debugToolArgs({ stage: "merge", branch: "snapshot-grow", current, incoming, args: incoming, delta });
+            return { args: incoming, delta };
+        }
+    }
+    debugToolArgs({ stage: "merge", branch: mode === "delta" ? "delta-append" : "snapshot-fallback-concat", current, incoming, args: current + incoming, delta: incoming });
     return { args: current + incoming, delta: incoming };
 }

package/dist/tools/bash.d.ts

@@ -3,4 +3,5 @@
  */
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
-export declare function createBashTool(cwd: string, approval?: ApprovalController): ToolRegistryEntry;
+import type { FileStateTracker } from "./file-state.js";
+export declare function createBashTool(cwd: string, approval?: ApprovalController, _fileState?: FileStateTracker): ToolRegistryEntry;

package/dist/tools/bash.js

@@ -8,7 +8,7 @@ import { gateToolAction } from "../approval/tool-helper.js";
 import { parseReadBashCommand, parseSearchBashCommand } from "../agent/tool-intent.js";
 import { referencesSensitivePath } from "./sensitive-paths.js";
 const MAX_OUTPUT = 50 * 1024;
-export function createBashTool(cwd, approval) {
+export function createBashTool(cwd, approval, _fileState) {
     return {
         name: "bash",
         effect: "unknown",

package/dist/tools/edit-apply.js

@@ -118,15 +118,32 @@ function matchEdit(content, edit, index, total) {
     if (edit.oldText.length === 0) {
         throw new EditApplyError(total === 1 ? "Error: oldText must not be empty." : `Error: edits[${index}].oldText must not be empty.`);
     }
+    if (edit.oldText === edit.newText) {
+        const header = total === 1
+            ? "Error: This edit is a no-op because oldText and newText are byte-identical."
+            : `Error: edits[${index}] is a no-op because oldText and newText are byte-identical.`;
+        throw new EditApplyError([
+            header,
+            "",
+            "Common causes and how to escape:",
+            "- Your tokenizer may be folding repeated characters into a single token (hex colors like '#ec489' vs '#ec4899', repeated digits, etc.). The two strings feel different in your head but serialize to identical bytes.",
+            "- Use the write tool with overwrite=true and the full new content for full-file replacements that hinge on a single repeated character or trailing digit.",
+            "- Or re-read the file with the read tool, then copy the exact bytes you want to replace before retrying.",
+        ].join("\n"));
+    }
     const oldText = normalizeToLF(edit.oldText);
     const exact = findAllOccurrences(content, oldText);
     if (exact.length === 1) {
         return { editIndex: index, mode: "exact", start: exact[0], end: exact[0] + oldText.length };
     }
     if (exact.length > 1) {
+        const recovery = [
+            "",
+            "Extend oldText with more surrounding context (the lines immediately before/after) until it uniquely identifies the intended span.",
+        ].join("\n");
         throw new EditApplyError(total === 1
-            ? `Error: oldText appears ${exact.length} times in file. Must be unique: "${summarizeOldText(oldText)}"`
-            : `Error: edits[${index}].oldText appears ${exact.length} times in file. Must be unique: "${summarizeOldText(oldText)}"`);
+            ? `Error: oldText appears ${exact.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`
+            : `Error: edits[${index}].oldText appears ${exact.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`);
     }
     const normalizedLineMatches = findNormalizedLineMatches(content, oldText);
     if (normalizedLineMatches.length === 1) {
@@ -143,10 +160,17 @@ function matchEdit(content, edit, index, total) {
             : `Error: edits[${index}].oldText matched ${normalizedLineMatches.length} normalized line blocks in file. Provide more surrounding context.`);
     }
     const hint = findBestLineHint(content, oldText);
-    const suffix = hint ? `\n${hint}` : "";
+    const hintSuffix = hint ? `\n${hint}` : "";
+    const recovery = [
+        "",
+        "How to recover:",
+        "- Re-read the file with the read tool to see its current bytes; the file may have been changed by a prior edit this turn.",
+        "- Shorten oldText to a smaller unique anchor and try again. Long multi-line anchors are fragile to whitespace and indentation.",
+        "- If many lines need to change, use the write tool with overwrite=true and the full new content instead of stacking edits.",
+    ].join("\n");
     throw new EditApplyError(total === 1
-        ? `Error: oldText not found in file: "${summarizeOldText(oldText)}"${suffix}`
-        : `Error: edits[${index}].oldText not found in file: "${summarizeOldText(oldText)}"${suffix}`);
+        ? `Error: oldText not found in file: "${summarizeOldText(oldText)}"${hintSuffix}${recovery}`
+        : `Error: edits[${index}].oldText not found in file: "${summarizeOldText(oldText)}"${hintSuffix}${recovery}`);
 }
 function assertNoOverlaps(matches) {
     const sorted = [...matches].sort((a, b) => a.start - b.start);
@@ -178,7 +202,14 @@ export function applyEditsToContent(rawContent, edits) {
         normalizedNext = normalizedNext.slice(0, match.start) + edit.newText + normalizedNext.slice(match.end);
     }
     if (normalizedNext === normalizedOriginal) {
-        throw new EditApplyError("Error: No changes made. The replacement produced identical content.");
+        throw new EditApplyError([
+            "Error: No changes made. The replacement produced identical content.",
+            "",
+            "Common causes and how to escape:",
+            "- oldText and newText are byte-identical. Verify newText actually contains the intended change (a missing trailing char like turning '#ec489' into '#ec4899' is a frequent culprit).",
+            "- The file already contains newText. Re-read the file to confirm the current state before editing again.",
+            "- For wholesale rewrites, use the write tool with overwrite=true and the full new content instead.",
+        ].join("\n"));
     }
     return {
         content: bom + restoreLineEndings(normalizedNext, lineEnding),

package/dist/tools/edit.d.ts

@@ -6,6 +6,7 @@
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
 import { type LspService } from "../lsp/index.js";
+import { type FileStateTracker } from "./file-state.js";
 export interface EditArgs {
     path: string;
     edits: Array<{
@@ -13,4 +14,4 @@ export interface EditArgs {
         newText: string;
     }>;
 }
-export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;
+export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;

package/dist/tools/edit.js

@@ -5,17 +5,14 @@
  */
 import { constants } from "node:fs";
 import { access, readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, relative, resolve } from "node:path";
+import { resolve } from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { formatDiagnosticBlocks } from "../lsp/index.js";
 import { applyEditsToContent, EditApplyError, formatEditMatchNotes } from "./edit-apply.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
-function isWithinWorkspace(cwd, filePath) {
-    const rel = relative(resolve(cwd), filePath);
-    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-}
-export function createEditTool(cwd, approval, lsp) {
+import { isWithinWorkspace } from "./file-state.js";
+export function createEditTool(cwd, approval, lsp, fileState) {
     return {
         name: "edit",
         effect: "write_direct",
@@ -82,7 +79,22 @@ export function createEditTool(cwd, approval, lsp) {
                 });
                 if (!gate.approved)
                     return gate.result;
+                const latest = await readFile(filePath, "utf-8");
+                if (latest !== original) {
+                    return {
+                        content: `Error: Cannot safely edit ${filePath} because it changed while approval was pending.\n\n`
+                            + "Re-read the file and retry the edit against the latest content.",
+                        isError: true,
+                        status: "blocked",
+                        metadata: {
+                            kind: "security",
+                            path: filePath,
+                            reason: "changed",
+                        },
+                    };
+                }
                 await writeFile(filePath, applied.content, "utf-8");
+                await fileState?.observe(filePath, "edit", applied.content).catch(() => undefined);
                 let output = `Edited ${filePath}${formatEditMatchNotes(applied.matches)}\n\nDiff:\n${diff}`;
                 if (lsp) {
                     try {

package/dist/tools/file-state.d.ts

@@ -0,0 +1,25 @@
+export type FileObservationSource = "read" | "write" | "edit";
+export interface FileVersion {
+    hash: string;
+    mtimeMs: number;
+    size: number;
+}
+export type FileFreshnessResult = {
+    ok: true;
+    version: FileVersion;
+} | {
+    ok: false;
+    reason: "unobserved" | "missing" | "changed";
+    observed?: FileVersion;
+    current?: FileVersion;
+};
+export declare class FileStateTracker {
+    private readonly cwd;
+    private readonly observed;
+    constructor(cwd: string);
+    observe(filePath: string, source: FileObservationSource, content?: string): Promise<FileVersion>;
+    checkFresh(filePath: string): Promise<FileFreshnessResult>;
+    private resolvePath;
+    private computeVersion;
+}
+export declare function isWithinWorkspace(cwd: string, filePath: string): boolean;

package/dist/tools/file-state.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { stat, readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+export class FileStateTracker {
+    cwd;
+    observed = new Map();
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    async observe(filePath, source, content) {
+        const absolute = this.resolvePath(filePath);
+        const version = await this.computeVersion(absolute, content);
+        this.observed.set(absolute, { ...version, source, observedAt: Date.now() });
+        return version;
+    }
+    async checkFresh(filePath) {
+        const absolute = this.resolvePath(filePath);
+        const observed = this.observed.get(absolute);
+        if (!observed) {
+            return { ok: false, reason: "unobserved" };
+        }
+        let current;
+        try {
+            current = await this.computeVersion(absolute);
+        }
+        catch {
+            return { ok: false, reason: "missing", observed };
+        }
+        if (current.hash === observed.hash && current.size === observed.size) {
+            return { ok: true, version: current };
+        }
+        return { ok: false, reason: "changed", observed, current };
+    }
+    resolvePath(filePath) {
+        return resolve(this.cwd, filePath);
+    }
+    async computeVersion(filePath, content) {
+        const [stats, bytes] = await Promise.all([
+            stat(filePath),
+            content === undefined ? readFile(filePath) : Promise.resolve(Buffer.from(content, "utf-8")),
+        ]);
+        return {
+            hash: createHash("sha256").update(bytes).digest("hex"),
+            mtimeMs: stats.mtimeMs,
+            size: stats.size,
+        };
+    }
+}
+export function isWithinWorkspace(cwd, filePath) {
+    const rel = relative(resolve(cwd), filePath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}

package/dist/tools/index.d.ts

@@ -25,6 +25,7 @@ import { type LspService } from "../lsp/index.js";
 import { type TodoStore } from "./todo.js";
 import { type ToolSearchController } from "./tool-search.js";
 import type { QuestionController } from "../question/index.js";
+import { FileStateTracker } from "./file-state.js";
 export interface CreateAllToolsOptions {
     todoStore?: TodoStore;
     planController?: PlanController;
@@ -32,5 +33,6 @@ export interface CreateAllToolsOptions {
     questionController?: QuestionController;
     toolSearchController?: ToolSearchController;
     lspService?: LspService;
+    fileStateTracker?: FileStateTracker;
 }
 export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -34,14 +34,16 @@ import { createWebSearchTool } from "./web-search.js";
 import { createWriteTool } from "./write.js";
 import { createQuestionTool } from "./question.js";
 import { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+import { FileStateTracker } from "./file-state.js";
 export function createAllTools(cwd, skillRegistry, options = {}) {
     const approval = options.approvalController;
     const lsp = options.lspService ?? getLspService(cwd);
+    const fileState = options.fileStateTracker ?? new FileStateTracker(cwd);
     return [
-        createReadTool(cwd, approval, lsp),
-        createBashTool(cwd, approval),
-        createWriteTool(cwd, { refuseOverwrite: true }, approval, lsp),
-        createEditTool(cwd, approval, lsp),
+        createReadTool(cwd, approval, lsp, fileState),
+        createBashTool(cwd, approval, fileState),
+        createWriteTool(cwd, { refuseOverwrite: true }, approval, lsp, fileState),
+        createEditTool(cwd, approval, lsp, fileState),
         createGlobTool(cwd),
         createGrepTool(cwd),
         createLspTool(cwd, lsp, approval),

package/dist/tools/read.d.ts

@@ -4,4 +4,5 @@
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
 import type { LspService } from "../lsp/index.js";
-export declare function createReadTool(cwd: string, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;
+import type { FileStateTracker } from "./file-state.js";
+export declare function createReadTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;

package/dist/tools/read.js

@@ -7,7 +7,7 @@ import { resolve } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
 const MAX_LINES = 250;
 const MAX_BYTES = 100 * 1024;
-export function createReadTool(cwd, approval, lsp) {
+export function createReadTool(cwd, approval, lsp, fileState) {
     return {
         name: "read",
         readOnly: true,
@@ -70,6 +70,10 @@ export function createReadTool(cwd, approval, lsp) {
             if (truncated) {
                 result += `\n[Output truncated: exceeded ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB limit]`;
             }
+            const isFullRead = offset === 0 && !truncated && offset + limit >= lines.length;
+            if (isFullRead) {
+                await fileState?.observe(filePath, "read", content).catch(() => undefined);
+            }
             void lsp?.touchFile(filePath).catch(() => undefined);
             return {
                 content: result,

package/dist/tools/write.d.ts

@@ -1,11 +1,12 @@
 /**
- * Write tool - create or overwrite files.
+ * Write tool - create files or safely replace full file contents.
  */
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
 import { type LspService } from "../lsp/index.js";
+import { type FileStateTracker } from "./file-state.js";
 export interface WriteToolOptions {
-    /** If true, refuse to overwrite existing files */
+    /** If true, existing files require overwrite=true plus a fresh agent-observed version. */
     refuseOverwrite?: boolean;
 }
-export declare function createWriteTool(cwd: string, options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;
+export declare function createWriteTool(cwd: string, options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;