fix: use schema-aware normalization for tool call arguments (#12)

This fixes the issue where JSON-formatted string parameters (like the
'content' field in the 'write' tool) were incorrectly parsed into objects,
causing OpenCode validation to fail with 'expected string, received object'.

The fix introduces a tool schema cache that stores parameter type information
during request transformation. When normalizing tool call arguments in
responses, the new normalizeToolCallArgs function:

- Preserves string parameters as-is (only processing escape sequences)
- Parses JSON strings only when the schema expects array/object types
- Falls back to conservative behavior when schema info is unavailable

This affects both Gemini and Claude models.

Fixes #11

Author: 22GNUs

src/plugin/request-helpers.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { getParamType } from "./tool-schema-cache";
 
 const SESSION_ID = `-${Math.floor(Math.random() * 9_000_000_000_000_000)}`;
 
@@ -344,3 +345,69 @@ export function recursivelyParseJsonStrings(value: unknown): unknown {
 
   return value;
 }
+
+/**
+ * Processes a value by only unescaping control characters (like \n, \t).
+ * It does NOT attempt to parse JSON objects from strings.
+ */
+export function processEscapeSequencesOnly(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+
+  const hasControlCharEscapes = value.includes("\\n") || value.includes("\\t");
+  const hasIntentionalEscapes = value.includes('\\"') || value.includes("\\\\");
+
+  if (hasControlCharEscapes && !hasIntentionalEscapes) {
+    try {
+      // Use JSON.parse to correctly handle unescaping control characters
+      const unescaped = JSON.parse(`"${value.replaceAll('"', '\\"')}"`);
+      if (typeof unescaped === "string") {
+        return unescaped;
+      }
+    } catch {
+      // Fall back to original
+    }
+  }
+
+  return value;
+}
+
+/**
+ * Normalizes tool call arguments based on their schema.
+ * - If schema says string: only unescape control characters, don't parse as JSON.
+ * - If schema says array/object: attempt to parse string as JSON.
+ * - If no schema: fallback to processEscapeSequencesOnly.
+ */
+export function normalizeToolCallArgs(args: unknown, toolName: string): unknown {
+  if (!args || typeof args !== "object") {
+    return args;
+  }
+
+  const record = args as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    const expectedType = getParamType(toolName, key);
+
+    if (expectedType === "string") {
+      result[key] = processEscapeSequencesOnly(value);
+    } else if (typeof value === "string" && (expectedType === "array" || expectedType === "object")) {
+      // If we expect an array/object but got a string, try to parse it
+      try {
+        const parsed = JSON.parse(value);
+        result[key] = parsed;
+      } catch {
+        result[key] = processEscapeSequencesOnly(value);
+      }
+    } else if (expectedType === undefined) {
+      // No schema info: be conservative and only unescape control characters
+      result[key] = processEscapeSequencesOnly(value);
+    } else {
+      // For other types, or if it's already an object, just process escapes
+      result[key] = processEscapeSequencesOnly(value);
+    }
+  }
+
+  return result;
+}

src/plugin/request.ts

@@ -8,6 +8,7 @@ import {
   generateRequestId,
   getSessionId,
   parseGeminiApiBody,
+  normalizeToolCallArgs,
   recursivelyParseJsonStrings,
   rewriteGeminiPreviewAccessError,
   rewriteGeminiRateLimitError,
@@ -321,7 +322,7 @@ function normalizeToolArgsInResponse(response: unknown): void {
       const functionCall = (part as any)?.functionCall;
       if (functionCall && "args" in functionCall) {
         const beforeArgs = functionCall.args;
-        const afterArgs = recursivelyParseJsonStrings(beforeArgs);
+        const afterArgs = normalizeToolCallArgs(beforeArgs, functionCall.name);
         functionCall.args = afterArgs;
 
         if (typeof beforeArgs === "string" && beforeArgs !== afterArgs) {

src/plugin/tool-schema-cache.ts

@@ -0,0 +1,94 @@
+
+/**
+ * Info about a tool parameter schema.
+ */
+export type SchemaInfo = {
+  type: string;
+  items?: SchemaInfo;
+  properties?: Record<string, SchemaInfo>;
+};
+
+/**
+ * Cache structure: Map<toolName, Map<paramName, SchemaInfo>>
+ */
+const toolSchemaCache = new Map<string, Map<string, SchemaInfo>>();
+
+/**
+ * Sanitizes tool names for Gemini API compatibility.
+ * This should match the logic in gemini.ts.
+ */
+function sanitizeToolName(name: string): string {
+  if (/^[0-9]/.test(name)) {
+    return `t_${name}`;
+  }
+  return name;
+}
+
+/**
+ * Recursively extracts schema info from a JSON schema object.
+ */
+function extractSchemaInfo(schema: any): SchemaInfo {
+  const type = schema?.type || "unknown";
+  const info: SchemaInfo = { type };
+
+  if (type === "array" && schema.items) {
+    info.items = extractSchemaInfo(schema.items);
+  } else if (type === "object" && schema.properties) {
+    info.properties = {};
+    for (const [key, value] of Object.entries(schema.properties)) {
+      info.properties[key] = extractSchemaInfo(value);
+    }
+  }
+
+  return info;
+}
+
+/**
+ * Caches tool schemas from a request payload.
+ */
+export function cacheToolSchemas(tools: any[] | undefined): void {
+  if (!Array.isArray(tools)) return;
+
+  for (const tool of tools) {
+    const funcDecls = tool.functionDeclarations;
+    if (!Array.isArray(funcDecls)) continue;
+
+    for (const funcDecl of funcDecls) {
+      const originalName = funcDecl.name;
+      if (typeof originalName !== "string") continue;
+
+      const sanitizedName = sanitizeToolName(originalName);
+      const schema = (funcDecl.parametersJsonSchema ?? funcDecl.parameters) as any;
+      
+      if (!schema || typeof schema !== "object") continue;
+
+      const properties = schema.properties;
+      if (!properties || typeof properties !== "object") continue;
+
+      const paramMap = new Map<string, SchemaInfo>();
+      for (const [paramName, paramSchema] of Object.entries(properties)) {
+        paramMap.set(paramName, extractSchemaInfo(paramSchema));
+      }
+      
+      toolSchemaCache.set(sanitizedName, paramMap);
+      // Also cache with original name to be safe
+      if (sanitizedName !== originalName) {
+        toolSchemaCache.set(originalName, paramMap);
+      }
+    }
+  }
+}
+
+/**
+ * Gets the expected type for a tool parameter.
+ */
+export function getParamType(toolName: string, paramName: string): string | undefined {
+  return toolSchemaCache.get(toolName)?.get(paramName)?.type;
+}
+
+/**
+ * Clears the tool schema cache.
+ */
+export function clearToolSchemaCache(): void {
+  toolSchemaCache.clear();
+}

src/plugin/transform/claude.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { cacheSignature, getCachedSignature } from "../cache";
 import { createLogger } from "../logger";
 import { normalizeThinkingConfig } from "../request-helpers";
+import { cacheToolSchemas } from "../tool-schema-cache";
 import type { RequestPayload, TransformContext, TransformResult } from "./types";
 
 const log = createLogger("transform.claude");
@@ -187,6 +188,9 @@ export function transformClaudeRequest(
     delete requestPayload.model;
   }
 
+  // Cache tool schemas for response normalization
+  cacheToolSchemas(requestPayload.tools as any[]);
+
   const tools = requestPayload.tools as Array<Record<string, unknown>> | undefined;
   if (Array.isArray(tools)) {
     for (const tool of tools) {

src/plugin/transform/gemini.ts

@@ -1,6 +1,7 @@
 import { getCachedSignature } from "../cache";
 import { createLogger } from "../logger";
 import { normalizeThinkingConfig } from "../request-helpers";
+import { cacheToolSchemas } from "../tool-schema-cache";
 import type { RequestPayload, TransformContext, TransformResult } from "./types";
 
 const log = createLogger("transform.gemini");
@@ -516,6 +517,9 @@ export function transformGeminiRequest(
   // Sanitize tool names to ensure Gemini API compatibility
   sanitizeToolNames(requestPayload);
 
+  // Cache tool schemas for response normalization
+  cacheToolSchemas(requestPayload.tools as any[]);
+
   augmentToolDescriptionsWithStrictParams(requestPayload);
   injectSystemInstructionIfNeeded(requestPayload);
   scrubConversationArtifactsFromModelHistory(requestPayload);

src/plugin/transform/signature.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from "bun:test";
 
 import { cacheSignature } from "../cache";
-import { recursivelyParseJsonStrings } from "../request-helpers";
+import { normalizeToolCallArgs, recursivelyParseJsonStrings } from "../request-helpers";
+import { cacheToolSchemas, clearToolSchemaCache } from "../tool-schema-cache";
 import { transformClaudeRequest } from "./claude";
 import { transformGeminiRequest } from "./gemini";
 import type { ModelFamily, RequestPayload, TransformContext } from "./types";
@@ -205,6 +206,101 @@ describe("thoughtSignature handling", () => {
     });
   });
 
+  describe("normalizeToolCallArgs (Schema-Aware)", () => {
+    it("preserves JSON string when schema says string", () => {
+      clearToolSchemaCache();
+      cacheToolSchemas([
+        {
+          functionDeclarations: [
+            {
+              name: "write",
+              parameters: {
+                type: "object",
+                properties: {
+                  content: { type: "string" },
+                  filePath: { type: "string" }
+                }
+              }
+            }
+          ]
+        }
+      ]);
+
+      const args = {
+        content: '{"name": "test", "version": "1.0.0"}',
+        filePath: "test.json"
+      };
+
+      const normalized = normalizeToolCallArgs(args, "write") as any;
+      expect(typeof normalized.content).toBe("string");
+      expect(normalized.content).toBe('{"name": "test", "version": "1.0.0"}');
+    });
+
+    it("parses JSON string when schema says array", () => {
+      clearToolSchemaCache();
+      cacheToolSchemas([
+        {
+          functionDeclarations: [
+            {
+              name: "read",
+              parameters: {
+                type: "object",
+                properties: {
+                  files: { type: "array" }
+                }
+              }
+            }
+          ]
+        }
+      ]);
+
+      const args = {
+        files: '[{"path": "a.txt"}]'
+      };
+
+      const normalized = normalizeToolCallArgs(args, "read") as any;
+      expect(Array.isArray(normalized.files)).toBe(true);
+      expect(normalized.files[0].path).toBe("a.txt");
+    });
+
+    it("handles sanitized tool names correctly", () => {
+      clearToolSchemaCache();
+      // Tool name starting with number
+      cacheToolSchemas([
+        {
+          functionDeclarations: [
+            {
+              name: "21st-dev-magic",
+              parameters: {
+                type: "object",
+                properties: {
+                  code: { type: "string" }
+                }
+              }
+            }
+          ]
+        }
+      ]);
+
+      const args = {
+        code: '{"foo": "bar"}'
+      };
+
+      // Try with sanitized name
+      const normalized = normalizeToolCallArgs(args, "t_21st-dev-magic") as any;
+      expect(typeof normalized.code).toBe("string");
+      expect(normalized.code).toBe('{"foo": "bar"}');
+    });
+
+    it("unescapes control characters in strings", () => {
+      const args = {
+        text: "line1\\nline2"
+      };
+      const normalized = normalizeToolCallArgs(args, "any") as any;
+      expect(normalized.text).toBe("line1\nline2");
+    });
+  });
+
   describe("claude transformer", () => {
     it("keeps thinking blocks with valid signatures (length > 50)", () => {
       const payload: RequestPayload = {