fix: improve write/tool schema compatibility

Author: Nomadcxx

src/provider/runtime-interception.ts

@@ -102,7 +102,7 @@ export async function handleToolLoopEventLegacy(
     event,
     toolLoopMode,
     allowedToolNames,
-    toolSchemaMap: _toolSchemaMap,
+    toolSchemaMap,
     toolLoopGuard,
     toolMapper,
     toolSessionId,
@@ -121,11 +121,60 @@ export async function handleToolLoopEventLegacy(
       ? extractOpenAiToolCall(event as any, allowedToolNames)
       : null;
   if (interceptedToolCall) {
-    const termination = evaluateToolLoopGuard(toolLoopGuard, interceptedToolCall);
+    const compat = applyToolSchemaCompat(interceptedToolCall, toolSchemaMap);
+    let normalizedToolCall = compat.toolCall;
+    log.debug("Applied tool schema compatibility (legacy)", {
+      tool: normalizedToolCall.function.name,
+      originalArgKeys: compat.originalArgKeys,
+      normalizedArgKeys: compat.normalizedArgKeys,
+      collisionKeys: compat.collisionKeys,
+      validationOk: compat.validation.ok,
+    });
+
+    if (compat.validation.hasSchema && !compat.validation.ok) {
+      const validationTermination = evaluateSchemaValidationLoopGuard(
+        toolLoopGuard,
+        normalizedToolCall,
+        compat.validation,
+      );
+      if (validationTermination) {
+        return { intercepted: false, skipConverter: true, terminate: validationTermination };
+      }
+
+      const reroutedWrite = tryRerouteEditToWrite(
+        normalizedToolCall,
+        compat.normalizedArgs,
+        allowedToolNames,
+        toolSchemaMap,
+      );
+      if (reroutedWrite) {
+        log.info("Rerouting malformed edit call to write (legacy)", {
+          path: reroutedWrite.path,
+          missing: compat.validation.missing,
+          typeErrors: compat.validation.typeErrors,
+        });
+        normalizedToolCall = reroutedWrite.toolCall;
+      } else if (shouldEmitNonFatalSchemaValidationHint(normalizedToolCall, compat.validation)) {
+        const hintChunk = createNonFatalSchemaValidationHintChunk(
+          responseMeta,
+          normalizedToolCall,
+          compat.validation,
+        );
+        log.debug("Emitting non-fatal schema validation hint in legacy and skipping malformed tool execution", {
+          tool: normalizedToolCall.function.name,
+          missing: compat.validation.missing,
+          typeErrors: compat.validation.typeErrors,
+        });
+        await onToolResult(hintChunk);
+        return { intercepted: false, skipConverter: true };
+      }
+    }
+
+    const termination = evaluateToolLoopGuard(toolLoopGuard, normalizedToolCall);
     if (termination) {
       return { intercepted: false, skipConverter: true, terminate: termination };
     }
-    await onInterceptedToolCall(interceptedToolCall);
+    await onInterceptedToolCall(normalizedToolCall);
     return { intercepted: true, skipConverter: true };
   }
 

src/provider/tool-schema-compat.ts

@@ -28,6 +28,9 @@ const ARG_KEY_ALIASES = new Map<string, string>([
   ["terminalcommand", "command"],
   ["contents", "content"],
   ["text", "content"],
+  ["body", "content"],
+  ["data", "content"],
+  ["payload", "content"],
   ["streamcontent", "content"],
   ["recursive", "force"],
   ["oldstring", "old_string"],
@@ -212,6 +215,29 @@ function normalizeToolSpecificArgs(toolName: string, args: JsonRecord): JsonReco
     };
   }
 
+  if (normalizedToolName === "write") {
+    const normalized: JsonRecord = { ...args };
+
+    // Some model variants confuse write/edit and send edit-style payload keys.
+    // Map them into canonical write arguments before schema validation/sanitization.
+    if (normalized.content === undefined && normalized.new_string !== undefined) {
+      const coerced = coerceToString(normalized.new_string);
+      if (coerced !== null) {
+        normalized.content = coerced;
+      }
+      delete normalized.new_string;
+    }
+
+    if (normalized.content !== undefined && typeof normalized.content !== "string") {
+      const coerced = coerceToString(normalized.content);
+      if (coerced !== null) {
+        normalized.content = coerced;
+      }
+    }
+
+    return normalized;
+  }
+
   if (normalizedToolName !== "edit" || !EDIT_COMPAT_REPAIR_ENABLED) {
     return args;
   }

src/proxy/prompt-builder.ts

@@ -18,7 +18,8 @@ export function buildPromptFromMessages(messages: Array<any>, tools: Array<any>)
       })
       .join("\n");
     lines.push(
-      `SYSTEM: You have access to the following tools. When you need to use one, respond with a tool_call in the standard OpenAI format.\n\nAvailable tools:\n${toolDescs}`,
+      `SYSTEM: You have access to the following tools. When you need to use one, respond with a tool_call in the standard OpenAI format.\n` +
+        `Tool guidance: prefer write/edit for file changes; use bash mainly to run commands/tests.\n\nAvailable tools:\n${toolDescs}`,
     );
   }
 

src/tools/defaults.ts

@@ -8,7 +8,7 @@ export function registerDefaultTools(registry: ToolRegistry): void {
   registry.register({
     id: "bash",
     name: "bash",
-    description: "Execute a shell command in a safe environment",
+    description: "Execute a shell command. Use this to run programs/tests; prefer write/edit for creating or modifying files.",
     parameters: {
       type: "object",
       properties: {
@@ -99,7 +99,7 @@ export function registerDefaultTools(registry: ToolRegistry): void {
   registry.register({
     id: "write",
     name: "write",
-    description: "Write content to a file (creates or overwrites)",
+    description: "Write content to a file (creates or overwrites). Prefer this over using bash redirection/heredocs for file creation.",
     parameters: {
       type: "object",
       properties: {
@@ -138,7 +138,7 @@ export function registerDefaultTools(registry: ToolRegistry): void {
   registry.register({
     id: "edit",
     name: "edit",
-    description: "Edit a file by replacing old text with new text",
+    description: "Edit a file by replacing old text with new text. Use for targeted replacements; use write to overwrite an entire file.",
     parameters: {
       type: "object",
       properties: {

tests/unit/provider-runtime-interception.test.ts

@@ -240,6 +240,44 @@ describe("provider runtime interception fallback", () => {
     expect(interceptedArgs).toContain("\"content\":\"hello\"");
   });
 
+  it("normalizes legacy arguments using schema compatibility before intercept", async () => {
+    let interceptedArgs = "";
+    const result = await handleToolLoopEventLegacy(
+      createBaseOptions({
+        event: {
+          type: "tool_call",
+          call_id: "c3-legacy",
+          tool_call: {
+            writeToolCall: {
+              args: { filePath: "foo.txt", contents: "hello" },
+            },
+          },
+        } as any,
+        allowedToolNames: new Set(["write"]),
+        toolSchemaMap: new Map([
+          [
+            "write",
+            {
+              type: "object",
+              properties: {
+                path: { type: "string" },
+                content: { type: "string" },
+              },
+              required: ["path", "content"],
+            },
+          ],
+        ]),
+        onInterceptedToolCall: async (toolCall) => {
+          interceptedArgs = toolCall.function.arguments;
+        },
+      }),
+    );
+
+    expect(result).toEqual({ intercepted: true, skipConverter: true });
+    expect(interceptedArgs).toContain("\"path\":\"foo.txt\"");
+    expect(interceptedArgs).toContain("\"content\":\"hello\"");
+  });
+
   it("repairs edit content payloads into canonical edit arguments in v1", async () => {
     let interceptedArgs = "";
     const toolResults: any[] = [];

tests/unit/provider-tool-schema-compat.test.ts

@@ -603,4 +603,75 @@ describe("tool schema compatibility", () => {
     expect(map.has("read")).toBe(true);
     expect(map.has("todowrite")).toBe(true);
   });
+
+  it("coerces non-string write content into a string", () => {
+    const result = applyToolSchemaCompat(
+      {
+        id: "w1",
+        type: "function",
+        function: {
+          name: "write",
+          arguments: JSON.stringify({
+            path: "/tmp/a.txt",
+            content: [{ text: "hello" }, { text: " world" }],
+          }),
+        },
+      },
+      new Map([
+        [
+          "write",
+          {
+            type: "object",
+            properties: {
+              path: { type: "string" },
+              content: { type: "string" },
+            },
+            required: ["path", "content"],
+            additionalProperties: false,
+          },
+        ],
+      ]),
+    );
+
+    const args = JSON.parse(result.toolCall.function.arguments);
+    expect(args.path).toBe("/tmp/a.txt");
+    expect(args.content).toBe("hello world");
+    expect(result.validation.ok).toBe(true);
+  });
+
+  it("repairs write new_string into content", () => {
+    const result = applyToolSchemaCompat(
+      {
+        id: "w2",
+        type: "function",
+        function: {
+          name: "write",
+          arguments: JSON.stringify({
+            path: "/tmp/b.txt",
+            new_string: "hello",
+          }),
+        },
+      },
+      new Map([
+        [
+          "write",
+          {
+            type: "object",
+            properties: {
+              path: { type: "string" },
+              content: { type: "string" },
+            },
+            required: ["path", "content"],
+            additionalProperties: false,
+          },
+        ],
+      ]),
+    );
+
+    const args = JSON.parse(result.toolCall.function.arguments);
+    expect(args.path).toBe("/tmp/b.txt");
+    expect(args.content).toBe("hello");
+    expect(args.new_string).toBeUndefined();
+    expect(result.validation.ok).toBe(true);
+  });
 });