🤖 feat: allow guardless file_edit_insert on empty files

src/common/utils/tools/toolDefinitions.ts

@@ -1271,7 +1271,7 @@ export const TOOL_DEFINITIONS = {
     description:
       "Insert content into a file using substring guards. " +
       "Provide exactly one of insert_before or insert_after to anchor the operation when editing an existing file. " +
-      "When the file does not exist, it is created automatically without guards. " +
+      "When the file does not exist or is empty, it is populated automatically without guards. " +
       "Optional before/after substrings must uniquely match surrounding content. " +
       "Avoid short guards like `}` or `}\\n` that match multiple locations — " +
       `use longer patterns like full function signatures or unique comments. ${TOOL_EDIT_WARNING}`,

src/node/services/tools/file_edit_insert.test.ts

@@ -142,6 +142,20 @@ describe("file_edit_insert tool", () => {
     expect(await fs.readFile(newFile, "utf-8")).toBe("Hello world!\n");
   });
 
+  it("populates an empty existing file without requiring guards", async () => {
+    const emptyFile = path.join(testDir, "empty.txt");
+    await fs.writeFile(emptyFile, "");
+    const tool = createTestTool(testDir);
+    const args: FileEditInsertToolArgs = {
+      path: path.relative(testDir, emptyFile),
+      content: "Hello empty!\n",
+    };
+
+    const result = (await tool.execute!(args, mockToolCallOptions)) as FileEditInsertToolResult;
+    expect(result.success).toBe(true);
+    expect(await fs.readFile(emptyFile, "utf-8")).toBe("Hello empty!\n");
+  });
+
   it("fails when no guards are provided", async () => {
     const tool = createTestTool(testDir);
     const args: FileEditInsertToolArgs = {

src/node/services/tools/file_edit_insert.ts

@@ -149,6 +149,15 @@ function insertContent(
   }
 
   if (insert_before == null && insert_after == null) {
+    // Empty existing files have no anchors to match against, so allow guardless
+    // inserts that simply populate the file (mirrors the create-on-missing path).
+    if (originalContent.length === 0) {
+      return {
+        success: true,
+        newContent: contentToInsert,
+        metadata: {},
+      };
+    }
     return guardFailure(
       "Provide either insert_before or insert_after guard when editing existing files."
     );