pi-freeflow 1.33.1 → 1.33.3

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.33.3
+
+### Patch Changes
+
+- Fix tool calls being rejected with an invalid-arguments error when a model makes several calls in one turn. Some models label every parallel call `0`, so the pieces of different calls were joined together and arrived as one unreadable blob — a planning tool could then reject every update, even a minimal one, and leave its task list stuck mid-turn. Calls are now kept apart by their own identifier, and a call whose text arrives in several pieces still reassembles whole.
+
+## 1.33.2
+
+### Patch Changes
+
+- Document how the OpenCode free tier decides whether to answer a request: which request properties open the gate, which commonly repeated assumptions about it are wrong, and how to reproduce a check locally.
+- Fix tool calls breaking down on free models.
+
+  When a request carries a full set of agent tools, free models often return tool arguments that do not match the tool's declared shape. A planning tool asked for phased tasks could come back with the phases buried inside a JSON-encoded list under the wrong field, wrapped in an extra object, or under names the tool never declared — so the host rendered each phase as one long raw JSON string instead of real task lines.
+
+  The proxy now checks returned arguments against the tool schema the caller declared and repairs them when the intended shape is unambiguous, across all three API shapes, streamed and non-streamed, and for every supported model provider. Well-formed calls, calls for tools without structured parameters, and arguments that were cut off mid-stream all pass through untouched.
+
 ## 1.33.1
 
 ### Patch Changes

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.33.1",
+  "version": "1.33.3",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",

package/src/opencode-fingerprint.ts

@@ -38,6 +38,7 @@ import {
  type FindGlobRestore,
  type FingerprintToolName,
 } from "./tool-translation.ts";
+import { buildArgRepairSchemas, repairToolArguments, repairToolArgumentsValue } from "./tool-args.ts";
 import { getModelDef } from "./models.ts";
 import type { ThinkingLevel } from "./types.ts";
 
@@ -358,6 +359,11 @@ export function normalizeResponsesBody(body: Record<string, unknown>): void {
  * for downstream cloaking. Cloaking strips by `injected` only: names in
  * `injectedReal` were served with executable definitions, so model calls to
  * them execute downstream instead of being cloaked.
+ *
+ * `argSchemas` (lowercased caller tool name -> declared parameters) lets
+ * downstream repair malformed arguments against the caller's own schema; it
+ * is empty when no caller tool declares a structured parameter, so such
+ * requests keep streaming byte-identically.
  */
 export function enforceOpencodeFingerprint(
  body: Record<string, unknown>,
@@ -370,6 +376,7 @@ export function enforceOpencodeFingerprint(
  findGlob: FindGlobRestore;
  injected: string[];
  injectedReal: string[];
+ argSchemas: Map<string, Record<string, unknown>>;
 } {
  const clientRequestedStream = body.stream === true;
  const callerHadTools = Array.isArray(body.tools) && body.tools.length > 0;
@@ -398,6 +405,10 @@ export function enforceOpencodeFingerprint(
  if (body.tool_choice !== undefined) {
   body.tool_choice = retargetToolChoiceForUpstream(body.tool_choice, findGlob) as Record<string, unknown> | string;
  }
+ // Captured before translation and injection: the map is keyed by CALLER tool
+ // name (what arrives downstream), and injected placeholders must not be
+ // repairable.
+ const argSchemas = buildArgRepairSchemas(Array.isArray(body.tools) ? body.tools : []);
  const callerUpstream = new Set<string>();
  const callerNames = new Set<string>();
  if (Array.isArray(body.tools)) {
@@ -440,7 +451,7 @@ export function enforceOpencodeFingerprint(
  // Empty-placeholder callers stay silent via the COMPAT description and the
  // output-aggregator; real OMP definitions execute normally.
 
- return { clientRequestedStream, callerHadTools, addedTools: after > before, caseRestore, findGlob, injected, injectedReal };
+ return { clientRequestedStream, callerHadTools, addedTools: after > before, caseRestore, findGlob, injected, injectedReal, argSchemas };
 }
 
 /**
@@ -497,6 +508,7 @@ function cloakChatMessage(
  caseRestore?: CaseRestoreMap,
  findGlob?: FindGlobRestore,
  injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
 ): void {
  if (!msg || typeof msg !== "object" || Array.isArray(msg)) return;
  const m = msg as Record<string, unknown>;
@@ -524,11 +536,9 @@ function cloakChatMessage(
   if (tc && typeof tc === "object" && !Array.isArray(tc)) {
    const fn = (tc as Record<string, unknown>).function;
    if (fn && typeof fn === "object" && !Array.isArray(fn) && typeof (fn as Record<string, unknown>).name === "string") {
-    (fn as Record<string, unknown>).name = restoreCallerName(
-     (fn as Record<string, unknown>).name as string,
-     caseRestore,
-     findGlob,
-    );
+    const f = fn as Record<string, unknown>;
+    f.name = restoreCallerName(f.name as string, caseRestore, findGlob);
+    f.arguments = repairToolArguments(f.name as string, typeof f.arguments === "string" ? f.arguments : "", argSchemas);
    }
   }
   kept.push(tc);
@@ -543,6 +553,7 @@ export function sseToChatCompletionJson(
  caseRestore?: CaseRestoreMap,
  findGlob?: FindGlobRestore,
  injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
 ): Record<string, unknown> {
  const events = parseSseEvents(sseText);
  let id = "chatcmpl-freeflow";
@@ -553,10 +564,16 @@ export function sseToChatCompletionJson(
  let reasoningContent = "";
  let role = "assistant";
  let usage: unknown = undefined;
+ // Keyed by tool-call id whenever the provider sends one. Index is NOT
+ // trustworthy: free models routinely label every parallel call `index: 0`,
+ // and merging their fragments produces one unparseable argument blob
+ // (observed live: `{"i":"a","op":"done"}{"i":"b","op":"done"}`). Index is
+ // only the fallback for providers that omit an id entirely.
  const toolCallsMap = new Map<
-  number,
+  string,
   { id: string; type: string; function: { name: string; arguments: string } }
  >();
+ const keyByIndex = new Map<number, string>();
 
  for (const ev of events) {
   if (ev.data === "[DONE]") continue;
@@ -580,8 +597,15 @@ export function sseToChatCompletionJson(
       }
       if (Array.isArray(delta.tool_calls)) {
        for (const tc of delta.tool_calls) {
-        const idx = tc.index ?? 0;
-        const existing = toolCallsMap.get(idx) ?? {
+        // The first delta of a call carries its id; later deltas carry only
+        // `arguments`. A later id-less delta therefore belongs to whatever
+        // call this index already opened.
+        const idx = typeof tc.index === "number" ? tc.index : 0;
+        const hasId = typeof tc.id === "string" && tc.id !== "";
+        let key = hasId ? `id:${tc.id}` : keyByIndex.get(idx);
+        if (key === undefined) key = `idx:${idx}`;
+        if (hasId) keyByIndex.set(idx, key);
+        const existing = toolCallsMap.get(key) ?? {
          id: tc.id || "",
          type: tc.type || "function",
          function: { name: "", arguments: "" },
@@ -590,13 +614,13 @@ export function sseToChatCompletionJson(
         if (tc.type) existing.type = tc.type;
         if (tc.function?.name) existing.function.name += tc.function.name;
         if (tc.function?.arguments) existing.function.arguments += tc.function.arguments;
-        toolCallsMap.set(idx, existing);
+        toolCallsMap.set(key, existing);
        }
       }
      }
      // Choice contains a pre-assembled message: cloak before returning.
      if (c.message) {
-      cloakChatMessage(c.message, callerHadTools, caseRestore, findGlob, injected);
+      cloakChatMessage(c.message, callerHadTools, caseRestore, findGlob, injected, argSchemas);
       return parsed as Record<string, unknown>;
      }
     }
@@ -606,9 +630,9 @@ export function sseToChatCompletionJson(
   }
  }
 
- const toolCalls = Array.from(toolCallsMap.entries())
-  .sort(([a], [b]) => a - b)
-  .map(([, tc]) => tc);
+ // Map insertion order is emission order, which is what the host expects. The
+ // previous numeric sort assumed the keys were indices; they are now ids.
+ const toolCalls = Array.from(toolCallsMap.values());
 
  const message: Record<string, unknown> = {
   role,
@@ -625,7 +649,10 @@ export function sseToChatCompletionJson(
   const kept = injected === undefined
    ? toolCalls
    : toolCalls.filter((tc) => !injected.includes(tc.function.name.toLowerCase()));
-  for (const tc of kept) tc.function.name = restoreCallerName(tc.function.name, caseRestore, findGlob);
+  for (const tc of kept) {
+   tc.function.name = restoreCallerName(tc.function.name, caseRestore, findGlob);
+   tc.function.arguments = repairToolArguments(tc.function.name, tc.function.arguments, argSchemas);
+  }
   if (kept.length > 0) message.tool_calls = kept;
  }
 
@@ -650,9 +677,17 @@ export function sseToChatCompletionJson(
  * place. Only names this request injected are removed; caller calls keep
  * restored names (caller casing, upstream glob back to caller find). Tool-less
  * callers never see function_call items: every call is dropped, never leaked.
- * Ids and arguments ride verbatim (only the name is ever rewritten).
+ * Ids ride verbatim; arguments are repaired against the caller's declared
+ * schema when it says the emitted shape cannot be right.
  */
-function cloakResponsesObject(resp: unknown, callerHadTools = true, caseRestore?: CaseRestoreMap, findGlob?: FindGlobRestore, injected?: readonly string[]): void {
+function cloakResponsesObject(
+ resp: unknown,
+ callerHadTools = true,
+ caseRestore?: CaseRestoreMap,
+ findGlob?: FindGlobRestore,
+ injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
+): void {
  if (!resp || typeof resp !== "object" || Array.isArray(resp)) return;
  const output = (resp as Record<string, unknown>).output;
  if (!Array.isArray(output)) return;
@@ -663,7 +698,11 @@ function cloakResponsesObject(resp: unknown, callerHadTools = true, caseRestore?
    if (rec.type === "function_call") {
     if (typeof rec.name === "string" && injected !== undefined && injected.includes(rec.name.toLowerCase())) continue;
     if (!callerHadTools) continue;
-    if (typeof rec.name === "string") rec.name = restoreCallerName(rec.name, caseRestore, findGlob);
+    if (typeof rec.name === "string") {
+     const name = restoreCallerName(rec.name, caseRestore, findGlob);
+     rec.name = name;
+     rec.arguments = repairToolArguments(name, typeof rec.arguments === "string" ? rec.arguments : "", argSchemas);
+    }
    }
   }
   kept.push(item);
@@ -681,6 +720,7 @@ export function sseToResponsesJson(
  caseRestore?: CaseRestoreMap,
  findGlob?: FindGlobRestore,
  injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
 ): Record<string, unknown> {
  const events = parseSseEvents(sseText);
  // 1. Highest fidelity: response.completed event carries the final full response object
@@ -689,7 +729,7 @@ export function sseToResponsesJson(
   try {
    const parsed = JSON.parse(ev.data);
    if (parsed?.type === "response.completed" && parsed.response && typeof parsed.response === "object") {
-    cloakResponsesObject(parsed.response, callerHadTools, caseRestore, findGlob, injected);
+    cloakResponsesObject(parsed.response, callerHadTools, caseRestore, findGlob, injected, argSchemas);
     return parsed.response as Record<string, unknown>;
    }
   } catch { }
@@ -700,7 +740,7 @@ export function sseToResponsesJson(
   try {
    const parsed = JSON.parse(ev.data);
    if (parsed?.response && typeof parsed.response === "object") {
-    cloakResponsesObject(parsed.response, callerHadTools, caseRestore, findGlob, injected);
+    cloakResponsesObject(parsed.response, callerHadTools, caseRestore, findGlob, injected, argSchemas);
     return parsed.response as Record<string, unknown>;
    }
   } catch { }
@@ -709,7 +749,7 @@ export function sseToResponsesJson(
  try {
   const parsed = JSON.parse(sseText);
   if (parsed && typeof parsed === "object") {
-   cloakResponsesObject(parsed, callerHadTools, caseRestore, findGlob, injected);
+   cloakResponsesObject(parsed, callerHadTools, caseRestore, findGlob, injected, argSchemas);
    return parsed;
   }
  } catch { }
@@ -726,8 +766,8 @@ export function sseToResponsesJson(
  * Only names this request injected are removed; caller blocks keep restored
  * names (caller casing, upstream glob back to caller find). Tool-less callers
  * never see tool_use: stray placeholder input folds to text, matching the
- * SSE aggregator fallback below. Block objects ride verbatim (only names
- * are ever rewritten).
+ * SSE aggregator fallback below. Ids ride verbatim; `input` is repaired
+ * against the caller's declared schema when the emitted shape cannot be right.
  */
 function cloakMessagesContent(
  msg: unknown,
@@ -735,6 +775,7 @@ function cloakMessagesContent(
  caseRestore?: CaseRestoreMap,
  findGlob?: FindGlobRestore,
  injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
 ): void {
  if (!msg || typeof msg !== "object" || Array.isArray(msg)) return;
  const content = (msg as Record<string, unknown>).content;
@@ -751,7 +792,11 @@ function cloakMessagesContent(
    const rec = block as Record<string, unknown>;
    const isInjected = typeof rec.name === "string" && injected !== undefined && injected.includes(rec.name.toLowerCase());
    if (callerHadTools && !isInjected) {
-    if (typeof rec.name === "string") rec.name = restoreCallerName(rec.name, caseRestore, findGlob);
+    if (typeof rec.name === "string") {
+     const name = restoreCallerName(rec.name, caseRestore, findGlob);
+     rec.name = name;
+     rec.input = repairToolArgumentsValue(name, rec.input, argSchemas);
+    }
     kept.push(block);
    } else if (!callerHadTools) {
     let text = "";
@@ -787,6 +832,7 @@ export function sseToMessagesJson(
  caseRestore?: CaseRestoreMap,
  findGlob?: FindGlobRestore,
  injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
 ): Record<string, unknown> {
  const events = parseSseEvents(sseText);
  let id = "msg_freeflow";
@@ -848,7 +894,7 @@ export function sseToMessagesJson(
    continue;
   }
   if (type === "message" && parsed.role !== undefined) {
-   cloakMessagesContent(parsed, callerHadTools, caseRestore, findGlob, injected);
+   cloakMessagesContent(parsed, callerHadTools, caseRestore, findGlob, injected, argSchemas);
    return parsed;
   }
  }
@@ -865,7 +911,8 @@ export function sseToMessagesJson(
     } catch {
      input = {};
     }
-    content.push({ type: "tool_use", id: tool.id, name: restoreCallerName(tool.name, caseRestore, findGlob), input });
+    const name = restoreCallerName(tool.name, caseRestore, findGlob);
+    content.push({ type: "tool_use", id: tool.id, name, input: repairToolArgumentsValue(name, input, argSchemas) });
    }
    continue;
   }
@@ -900,6 +947,7 @@ export function convertSseToJson(
  caseRestore?: CaseRestoreMap,
  findGlob?: FindGlobRestore,
  injected?: readonly string[],
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>,
 ): string {
  if (!sseText || typeof sseText !== "string") return sseText;
  const trimmed = sseText.trim();
@@ -908,14 +956,13 @@ export function convertSseToJson(
  }
  try {
   if (pathname.endsWith("/responses")) {
-   return JSON.stringify(sseToResponsesJson(trimmed, callerHadTools, caseRestore, findGlob, injected));
+   return JSON.stringify(sseToResponsesJson(trimmed, callerHadTools, caseRestore, findGlob, injected, argSchemas));
   }
   if (pathname.endsWith("/messages")) {
-   return JSON.stringify(sseToMessagesJson(trimmed, callerHadTools, caseRestore, findGlob, injected));
+   return JSON.stringify(sseToMessagesJson(trimmed, callerHadTools, caseRestore, findGlob, injected, argSchemas));
   }
-  return JSON.stringify(sseToChatCompletionJson(trimmed, callerHadTools, caseRestore, findGlob, injected));
+  return JSON.stringify(sseToChatCompletionJson(trimmed, callerHadTools, caseRestore, findGlob, injected, argSchemas));
  } catch {
   return sseText;
  }
- return sseText;
 }

package/src/proxy.ts

@@ -51,6 +51,7 @@ import {
  clineChatBodyFromResponsesBody,
  translateToolsForPath,
 } from "./tool-translation.ts";
+import { buildArgRepairSchemas } from "./tool-args.ts";
 // normalize removed — host pi-ai already normalizes thinking/reasoning before proxy
 import { relayFetch } from "./relay.ts";
 import { getActiveRelayState, markRelayFailure, orderedRelayCandidates } from "./relay-state.ts";
@@ -266,6 +267,9 @@ async function handleClineRequest(opts: {
   if (Array.isArray(chatBody.tools)) chatBody.tools = translateToolsForPath(chatBody.tools, "/v1/chat/completions");
   delete chatBody.prompt_cache_key;
  }
+ // Cline bypasses the fingerprint, but its arguments still malform the same
+ // way: capture the caller's own schemas before translation for repair.
+ const argSchemas = buildArgRepairSchemas(Array.isArray(parsedBody.tools) ? parsedBody.tools : []);
  chatBody.stream = true;
  let upstreamRes: Response;
  let limitHint: ClineLimitHint | undefined;
@@ -329,6 +333,9 @@ async function handleClineRequest(opts: {
    req,
    reqId,
    "direct",
+   argSchemas.size > 0
+    ? { callerHadTools: true, argSchemas, pathname: "/v1/chat/completions" }
+    : undefined,
   );
   return;
  }
@@ -344,7 +351,7 @@ async function handleClineRequest(opts: {
   return;
  }
  if (!responsesRequest) {
-  const data = convertSseToJson(sseText, pathname);
+  const data = convertSseToJson(sseText, pathname, true, undefined, undefined, undefined, argSchemas);
   if (!res.headersSent) {
    res.writeHead(upstreamRes.status, { "content-type": "application/json" });
    res.end(data);
@@ -353,7 +360,7 @@ async function handleClineRequest(opts: {
   }
   return;
  }
- const chat = sseToChatCompletionJson(sseText);
+ const chat = sseToChatCompletionJson(sseText, true, undefined, undefined, undefined, argSchemas);
  const resp = chatResponsesJsonFromChatCompletion(chat, model);
  if (clientRequestedStream) {
   if (!res.headersSent) {
@@ -1046,20 +1053,22 @@ export function startProxy(
    let callerHadTools = true;
    let callerCaseRestore: CaseRestoreMap | undefined;
    let callerFindGlob: FindGlobRestore | undefined;
-   let callerInjected: string[] | undefined;
+  let callerInjected: string[] | undefined;
+  let callerArgSchemas: Map<string, Record<string, unknown>> | undefined;
    if (!isKilo && !isCline && parsedBody) {
     const fp = enforceOpencodeFingerprint(parsedBody, target.pathname);
     callerHadTools = fp.callerHadTools;
     callerCaseRestore = fp.caseRestore;
     callerFindGlob = fp.findGlob;
     callerInjected = fp.injected;
+    callerArgSchemas = fp.argSchemas;
     bodyModified = true;
    }
    // Streaming cloak: thread this request's placeholder records into the SSE
    // pipe so streamed deltas get the same strip+restore as aggregated bodies.
    // Kilo/Cline bypass the fingerprint, so their streams stay verbatim.
    const streamCloak: StreamCloakOptions | undefined = !isKilo && !isCline && callerInjected !== undefined
-    ? { callerHadTools, caseRestore: callerCaseRestore, findGlob: callerFindGlob, injected: callerInjected, pathname: target.pathname }
+    ? { callerHadTools, caseRestore: callerCaseRestore, findGlob: callerFindGlob, injected: callerInjected, argSchemas: callerArgSchemas, pathname: target.pathname }
     : undefined;
 
    const isStream = clientRequestedStream;
@@ -1091,6 +1100,9 @@ export function startProxy(
      // the timeout ceiling; the stream phase is owned by
      // pipeUpstreamStream and its close handling.
      const kiloController = new AbortController();
+     // Kilo bodies ride verbatim, but its models malform arguments the same
+     // way: capture the caller's schemas so the reply can be repaired too.
+     const kiloArgSchemas = buildArgRepairSchemas(Array.isArray(parsedBody.tools) ? parsedBody.tools : []);
      const kiloTimeoutId = setTimeout(
       () => kiloController.abort(upstreamTimeoutError()),
       UPSTREAM_HEADER_TIMEOUT_MS,
@@ -1177,9 +1189,9 @@ export function startProxy(
        connection: "keep-alive",
        "x-accel-buffering": "no",
       });
-      // Kilo is fetched directly (not via the relay pool), so pass undefined:
-      // attributing kilo-side stream failures to an unrelated opencode relay
-      // would mark a healthy relay as failed.
+      // Kilo is fetched directly (not via the relay pool), so pass undefined as
+      // the issuer: attributing kilo-side stream failures to an unrelated
+      // opencode relay would mark a healthy relay as failed.
       pipeUpstreamStream(
        Readable.fromWeb(
         response.body as unknown as WebReadableStream,
@@ -1188,11 +1200,21 @@ export function startProxy(
        req,
        reqId,
        undefined,
+       kiloArgSchemas.size > 0
+        ? {
+         callerHadTools: true,
+         argSchemas: kiloArgSchemas,
+         pathname: target.pathname.endsWith("/responses") ? "/v1/responses" : "/v1/chat/completions",
+        }
+        : undefined,
       );
      } else {
-      const data = withRateLimitHint(response.status, await response.text());
-      const ct =
-       response.headers.get("content-type") || "application/json";
+      let rawText = await response.text();
+      if (response.ok && kiloArgSchemas.size > 0) {
+       rawText = convertSseToJson(rawText, target.pathname, true, undefined, undefined, undefined, kiloArgSchemas);
+      }
+      const data = withRateLimitHint(response.status, rawText);
+      const ct = response.headers.get("content-type") || "application/json";
       res.writeHead(response.status, { "content-type": ct });
       res.end(data);
      }
@@ -1458,7 +1480,7 @@ export function startProxy(
           response.headers.get("content-type") ||
           "application/json";
          if (response.ok && (ct.includes("text/event-stream") || rawText.includes("data:"))) {
-          rawText = convertSseToJson(rawText, target.pathname, callerHadTools, callerCaseRestore, callerFindGlob, callerInjected);
+          rawText = convertSseToJson(rawText, target.pathname, callerHadTools, callerCaseRestore, callerFindGlob, callerInjected, callerArgSchemas);
           ct = "application/json";
          }
          const data = isRelayDisabledError(response.status, rawText)
@@ -1647,7 +1669,7 @@ export function startProxy(
       } else if (upstreamRes.body) {
        let rawText = await upstreamRes.text();
        if (upstreamRes.ok && (outHeaders["content-type"]?.includes("text/event-stream") || rawText.includes("data:"))) {
-        rawText = convertSseToJson(rawText, target.pathname, callerHadTools, callerCaseRestore, callerFindGlob, callerInjected);
+        rawText = convertSseToJson(rawText, target.pathname, callerHadTools, callerCaseRestore, callerFindGlob, callerInjected, callerArgSchemas);
         outHeaders["content-type"] = "application/json";
        }
        res.writeHead(upstreamRes.status, outHeaders);

package/src/stream-pipe.ts

@@ -17,6 +17,7 @@ import {
 } from "./config.ts";
 import type { CaseRestoreMap, FindGlobRestore } from "./opencode-fingerprint.ts";
 import { restoreToolNameForCaller } from "./tool-translation.ts";
+import { repairToolArguments } from "./tool-args.ts";
 
 /**
  * A premature stream end counts as "substantial" only when BOTH thresholds
@@ -153,8 +154,9 @@ export function _resetSseStatsForTest(): void {
  * on the streamed path, so this section mirrors the aggregate semantics
  * event-by-event: function_call deltas whose name is in this request's
  * injected list are dropped, surviving names get caller casing (Bash) and the
- * Pi find->glob rename restored. State is per-stream (no globals); the
- * non-stream path is untouched.
+ * Pi find->glob rename restored. Completed tool arguments are additionally
+ * repaired against `argSchemas` on the terminal events that carry the whole
+ * payload. State is per-stream (no globals); the non-stream path is untouched.
  */
 export interface StreamCloakOptions {
  /** False when the caller declared no tools (chat folds dropped args to text). */
@@ -167,6 +169,8 @@ export interface StreamCloakOptions {
  injected?: readonly string[];
  /** Request pathname; decides the Responses vs Chat event shapes. */
  pathname: string;
+ /** Caller tool schemas for argument repair; undefined/empty means byte-identical. */
+ argSchemas?: ReadonlyMap<string, Record<string, unknown>>;
 }
 
 /** Per-stream drop tracking (delta events carry no name, only an index/id). */
@@ -175,6 +179,22 @@ export interface SseStreamCloakState {
  responsesDroppedByItemId: Map<string, boolean>;
  chatDroppedByIndex: Map<number, boolean>;
  messagesDroppedByIndex: Map<number, boolean>;
+ /** Output index -> tool name, so nameless argument deltas can find their schema. */
+ responsesNameByIndex: Map<number, string>;
+ /** Anthropic block index -> tool name, same purpose for input_json deltas. */
+ messagesNameByIndex: Map<number, string>;
+ /** Chat tool-call index -> restored tool name. */
+ chatNameByIndex: Map<number, string>;
+ /**
+ * Argument fragments for tool calls whose schema admits a repair, keyed the
+ * same way as the name maps above. Streaming APIs deliver arguments in
+ * fragments, so a malformed packet can only be judged once complete: those
+ * fragments are held here and re-emitted, repaired, on the call's terminal
+ * event. Tools absent from `argSchemas` are never buffered, so their
+ * arguments still stream incrementally exactly as before.
+ */
+ chatArgsByIndex: Map<number, string>;
+ messagesArgsByIndex: Map<number, string>;
 }
 
 export function createSseStreamCloakState(): SseStreamCloakState {
@@ -183,6 +203,11 @@ export function createSseStreamCloakState(): SseStreamCloakState {
   responsesDroppedByItemId: new Map(),
   chatDroppedByIndex: new Map(),
   messagesDroppedByIndex: new Map(),
+  responsesNameByIndex: new Map(),
+  messagesNameByIndex: new Map(),
+  chatNameByIndex: new Map(),
+  chatArgsByIndex: new Map(),
+  messagesArgsByIndex: new Map(),
  };
 }
 
@@ -200,6 +225,8 @@ export function shouldBypassStreamCloak(cloak?: StreamCloakOptions): boolean {
  // Tool-less callers must still see tool calls stripped when the
  // injected record exists (legacy direct calls keep everything).
  if (!cloak.callerHadTools && cloak.injected !== undefined) return false;
+ // A repairable schema means fragmented arguments must be buffered.
+ if (cloak.argSchemas !== undefined && cloak.argSchemas.size > 0) return false;
  return true;
 }
 
@@ -207,6 +234,14 @@ function isInjectedName(name: unknown, injected?: readonly string[]): boolean {
  return typeof name === "string" && injected !== undefined && injected.includes(name.toLowerCase());
 }
 
+/** True when the request declared a schema for this tool, so its arguments can be repaired. */
+function isRepairableTool(
+ name: string,
+ schemas: ReadonlyMap<string, Record<string, unknown>> | undefined,
+): boolean {
+ return schemas !== undefined && schemas.size > 0 && schemas.has(name.trim().toLowerCase());
+}
+
 /** Caller casing first, then the Pi find->glob rename (upstream glob->find). */
 function restoreStreamName(name: string, cloak: StreamCloakOptions): string {
  const cased = cloak.caseRestore?.[name.toLowerCase()] ?? name;
@@ -261,8 +296,9 @@ function rewriteResponsesBlock(
  const hadEventPrefix = /^\s*event:/m.test(block);
 
  // New function_call item announced: drop when injected; tool-less callers
- // drop every function_call, never leaking calls downstream. Ids and
- // arguments ride verbatim (only the name is ever rewritten).
+ // drop every function_call, never leaking calls downstream. Ids ride
+ // verbatim; `output_item.done` carries the whole argument string, so that is
+ // where schema repair applies (name-only deltas cannot be repaired yet).
  if (type === "response.output_item.added" || type === "response.output_item.done") {
   const item = parsed.item;
   if (item && typeof item === "object" && !Array.isArray(item)) {
@@ -275,6 +311,12 @@ function rewriteResponsesBlock(
      return null;
     }
     const restored = restoreStreamName(rec.name, cloak);
+    if (typeof parsed.output_index === "number") state.responsesNameByIndex.set(parsed.output_index, restored);
+    if (type === "response.output_item.done") {
+     rec.name = restored;
+     rec.arguments = repairToolArguments(restored, typeof rec.arguments === "string" ? rec.arguments : "", cloak.argSchemas);
+     return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
+    }
     if (restored !== rec.name) {
      rec.name = restored;
      return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
@@ -284,13 +326,24 @@ function rewriteResponsesBlock(
   return block;
  }
 
- // Argument deltas carry no name: earlier added/done decisions rule by index/id.
- // Tool-less callers drop every function_call_arguments delta outright.
+// Argument deltas carry no name: earlier added/done decisions rule by index/id.
+// Tool-less callers drop every function_call_arguments delta outright. The
+// `.done` event carries the whole `arguments` string, so it is repairable.
  if (type === "response.function_call_arguments.delta" || type === "response.function_call_arguments.done") {
   if (!cloak.callerHadTools) return null;
   const droppedByIndex = typeof parsed.output_index === "number" && state.responsesDroppedByIndex.get(parsed.output_index) === true;
   const droppedById = typeof parsed.item_id === "string" && state.responsesDroppedByItemId.get(parsed.item_id) === true;
   if (droppedByIndex || droppedById) return null;
+  if (type === "response.function_call_arguments.done" && typeof parsed.arguments === "string") {
+   const name = typeof parsed.output_index === "number" ? state.responsesNameByIndex.get(parsed.output_index) : undefined;
+   if (name !== undefined) {
+    const repairedArgs = repairToolArguments(name, parsed.arguments, cloak.argSchemas);
+    if (repairedArgs !== parsed.arguments) {
+     parsed.arguments = repairedArgs;
+     return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
+    }
+   }
+  }
   return block;
  }
 
@@ -374,6 +427,28 @@ function rewriteChatBlock(
    continue;
   }
   const d = delta as Record<string, unknown>;
+  // Terminal chunk for this choice: re-emit every buffered tool call's whole
+  // argument packet, repaired. The fragments never went out, so this is the
+  // first and only time the client sees them. Runs before the tool_calls
+  // branch because the terminal chunk usually carries an empty delta.
+  // Indices flushed on this block: their arguments are final, so the
+  // per-delta loop below must not buffer them a second time.
+  const flushedIndices = new Set<number>();
+  if (c.finish_reason && state.chatArgsByIndex.size > 0) {
+   const flushed: unknown[] = [];
+   for (const [idx, args] of state.chatArgsByIndex) {
+    const name = state.chatNameByIndex.get(idx);
+    if (name === undefined) continue;
+    flushedIndices.add(idx);
+    flushed.push({ index: idx, type: "function", function: { name, arguments: repairToolArguments(name, args, cloak.argSchemas) } });
+   }
+   state.chatArgsByIndex.clear();
+   state.chatNameByIndex.clear();
+   if (flushed.length > 0) {
+    d.tool_calls = [...(Array.isArray(d.tool_calls) ? d.tool_calls : []), ...flushed];
+    changed = true;
+   }
+  }
   if (!Array.isArray(d.tool_calls)) {
    if (Object.keys(d).length > 0) allDeltasEmpty = false;
    continue;
@@ -407,6 +482,19 @@ function rewriteChatBlock(
      changed = true;
     }
     state.chatDroppedByIndex.delete(idx);
+    state.chatNameByIndex.set(idx, restored);
+    if (isRepairableTool(restored, cloak.argSchemas) && !flushedIndices.has(idx)) {
+     // Hold this call's arguments: the packet is only judgeable once whole,
+     // so it is re-emitted repaired on the terminal finish_reason chunk.
+     state.chatArgsByIndex.set(idx, "");
+     if (fnRec && typeof fnRec.arguments === "string" && fnRec.arguments !== "") {
+      state.chatArgsByIndex.set(idx, fnRec.arguments);
+      delete fnRec.arguments;
+      changed = true;
+     }
+     kept.push(tc);
+     continue;
+    }
     kept.push(tc);
     continue;
    }
@@ -415,8 +503,14 @@ function rewriteChatBlock(
     changed = true;
     continue;
    }
-   kept.push(tc);
+  if (state.chatArgsByIndex.has(idx) && fnRec && typeof fnRec.arguments === "string") {
+   state.chatArgsByIndex.set(idx, (state.chatArgsByIndex.get(idx) ?? "") + fnRec.arguments);
+   delete fnRec.arguments;
+   changed = true;
+   continue;
   }
+  kept.push(tc);
+ }
   if (kept.length > 0) {
    d.tool_calls = kept;
    allDeltasEmpty = false;
@@ -522,17 +616,25 @@ function rewriteMessagesBlock(
    }
    if (typeof rec.name === "string") {
     const restored = restoreStreamName(rec.name, cloak);
-    if (restored !== rec.name) {
-     rec.name = restored;
-     return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
+    rec.name = restored;
+    state.messagesNameByIndex.set(index, restored);
+    if (isRepairableTool(restored, cloak.argSchemas)) {
+     state.messagesArgsByIndex.set(index, typeof rec.input === "string" ? rec.input : "");
     }
+    return emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
    }
   }
   return block;
  }
- // Input deltas carry no name: the start verdict rules by index.
+ // Input deltas carry no name: the start verdict rules by index. Repairable
+ // tools buffer their fragments, re-emitted whole on content_block_stop.
  if (type === "content_block_delta") {
   if (state.messagesDroppedByIndex.get(index) === true) return null;
+  const delta = parsed.delta as Record<string, unknown> | undefined;
+  if (state.messagesArgsByIndex.has(index) && delta && typeof delta.partial_json === "string") {
+   state.messagesArgsByIndex.set(index, (state.messagesArgsByIndex.get(index) ?? "") + delta.partial_json);
+   return null;
+  }
   return block;
  }
  // Block close for a dropped tool_use carries no name: drop it too.
@@ -541,7 +643,18 @@ function rewriteMessagesBlock(
    state.messagesDroppedByIndex.delete(index);
    return null;
   }
-  return block;
+  const buffered = state.messagesArgsByIndex.get(index);
+  if (buffered === undefined) return block;
+  const name = state.messagesNameByIndex.get(index) ?? "";
+  state.messagesArgsByIndex.delete(index);
+  state.messagesNameByIndex.delete(index);
+  const flushed: Record<string, unknown> = {
+   type: "content_block_delta",
+   index,
+   delta: { type: "input_json_delta", partial_json: repairToolArguments(name, buffered, cloak.argSchemas) },
+  };
+  const stopBlock = emitSseBlock(event, JSON.stringify(parsed), hadEventPrefix);
+  return `${emitSseBlock("content_block_delta", JSON.stringify(flushed), false)}\n\n${stopBlock}`;
  }
  return block;
 }

package/src/tool-args.ts

@@ -0,0 +1,406 @@
+/**
+ * Schema-driven repair for model-emitted tool-call arguments.
+ *
+ * Free models reliably lose tool-argument fidelity once a request carries a
+ * full agent tool inventory. Probed live 2026-10-08 against OpenCode Zen with
+ * the real OMP `todo` schema: at one tool the same model emits the canonical
+ * `list: [{ phase, items }]`, but at ~70 tools it delivered structured phases
+ * JSON-encoded into the flat string list, with each inner array wrapped as
+ * `items: { item: [...] }`. Sibling free models invented whole vocabularies
+ * (`phases` / `name` / `tasks`) the schema never declared.
+ *
+ * Two families are mechanically decidable from the CALLER's own declared
+ * schema, and this module repairs exactly those:
+ *
+ * - Envelope unwrap: a declared array that arrives wrapped in a single-key
+ *   object (`items: { item: [...] }`) is unwrapped.
+ * - JSON-string decode: a declared object/array that arrives as a JSON string
+ *   is parsed. Declared `string` properties are never decoded.
+ * - Structured promotion: a declared object-array property left ABSENT, with a
+ *   declared string-array property whose every element parses to an object that
+ *   validates against the object-array's item schema, is promoted across.
+ *   Every element must validate, so one JSON-looking task label never moves.
+ *
+ * Invented vocabulary is deliberately NOT repaired: renaming `phases` to `list`
+ * is a naming coincidence, not a schema fact, and a generic proxy that guesses
+ * it would corrupt the next tool. Those calls ride verbatim and surface the
+ * host's own schema error. This mirrors the reference upstream, which also
+ * declines to fake a legal-looking argument packet
+ * (channel-pack/src/sse.ts normalizeToolArguments / isTruncatedArguments).
+ *
+ * Arguments change only when the result matches the declared schema, so
+ * well-formed calls come back byte-identical and truncated JSON is never
+ * completed.
+ */
+
+import { canonicalizeTool } from "./tool-translation.ts";
+
+/** Bound on recursive repair/validation; real host schemas nest 3-4 deep. */
+const MAX_DEPTH = 8;
+
+/** Declared JSON Schema type, tolerating union types like ["array","null"]. */
+function schemaType(schema: Record<string, unknown>): string {
+  const declared = schema.type;
+  if (typeof declared === "string") return declared;
+  if (Array.isArray(declared)) {
+    for (const entry of declared) if (entry === "object" || entry === "array") return entry;
+    if (typeof declared[0] === "string") return declared[0];
+  }
+  return "";
+}
+
+/** A schema property worth repairing: it holds an object or an array. */
+function structuralProperty(schema: Record<string, unknown>): boolean {
+  const type = schemaType(schema);
+  return type === "object" || type === "array";
+}
+
+/**
+ * Does a value already satisfy the declared schema? Type, then required keys,
+ * then each present property recursively. A present property the schema does
+ * not declare is ignored (never fails): hosts decide their own extras policy,
+ * and this only gates whether a promotion is safe.
+ */
+function matchesSchema(value: unknown, schema: Record<string, unknown>, depth: number): boolean {
+  if (depth > MAX_DEPTH) return false;
+  const type = schemaType(schema);
+  if (type === "array") {
+   if (!Array.isArray(value)) return false;
+   const items = schema.items;
+   if (items === null || typeof items !== "object" || Array.isArray(items)) return true;
+   return value.every((element) => matchesSchema(element, items as Record<string, unknown>, depth + 1));
+  }
+  if (type === "object") {
+   if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+   const rec = value as Record<string, unknown>;
+   if (Array.isArray(schema.required)) {
+    for (const key of schema.required) {
+     if (typeof key === "string" && !(key in rec)) return false;
+    }
+   }
+   const props = schema.properties;
+   if (props === null || typeof props !== "object" || Array.isArray(props)) return true;
+   for (const [key, entry] of Object.entries(rec)) {
+    const propSchema = (props as Record<string, unknown>)[key];
+    if (propSchema === null || typeof propSchema !== "object" || Array.isArray(propSchema)) continue;
+    if (!matchesSchema(entry, propSchema as Record<string, unknown>, depth + 1)) return false;
+   }
+   return true;
+  }
+  if (type === "string") return typeof value === "string";
+  if (type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (type === "boolean") return typeof value === "boolean";
+  if (Array.isArray(schema.enum)) return schema.enum.some((member) => member === value);
+  return true;
+}
+
+/**
+ * Repair one value against its declared schema: decode a JSON-string object or
+ * array, unwrap a single-key envelope around an array, then recurse into array
+ * items and object properties. Returns the input untouched when nothing
+ * applies, so callers can gate re-serialization on `changed`.
+ */
+function repairValue(
+  value: unknown,
+  schema: Record<string, unknown>,
+  depth: number,
+): { value: unknown; changed: boolean } {
+  if (depth > MAX_DEPTH) return { value, changed: false };
+  const type = schemaType(schema);
+  if (type !== "array" && type !== "object") return { value, changed: false };
+
+  // Declared object/array that arrived as a JSON string: decode and retry.
+  if (typeof value === "string") {
+   const trimmed = value.trim();
+   if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+     const parsed: unknown = JSON.parse(trimmed);
+     if (parsed !== null && typeof parsed === "object") {
+      const inner = repairValue(parsed, schema, depth + 1);
+      return { value: inner.value, changed: true };
+     }
+    } catch {
+     // Truncated or non-JSON prose: never complete it.
+    }
+   }
+   return { value, changed: false };
+  }
+
+  if (type === "array") {
+   // Single-key envelope around the real array: { item: [...] } -> [...]
+   let candidate = value;
+   if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 1 && Array.isArray(entries[0][1])) candidate = entries[0][1];
+   }
+   if (candidate !== value) {
+    const inner = repairValue(candidate, schema, depth + 1);
+    return { value: inner.value, changed: true };
+   }
+   if (!Array.isArray(value)) return { value, changed: false };
+   const items = schema.items;
+   if (items === null || typeof items !== "object" || Array.isArray(items)) return { value, changed: false };
+   let changed = false;
+   const out = value.map((element) => {
+    const repaired = repairValue(element, items as Record<string, unknown>, depth + 1);
+    if (repaired.changed) changed = true;
+    return repaired.value;
+   });
+   return { value: changed ? out : value, changed };
+  }
+
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+   return { value, changed: false };
+  }
+  const props = schema.properties;
+  if (props === null || typeof props !== "object" || Array.isArray(props)) {
+   return { value, changed: false };
+  }
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+   const propSchema = (props as Record<string, unknown>)[key];
+   if (propSchema === null || typeof propSchema !== "object" || Array.isArray(propSchema)) {
+    out[key] = entry;
+    continue;
+   }
+   const repaired = repairValue(entry, propSchema as Record<string, unknown>, depth + 1);
+   if (repaired.changed) changed = true;
+   out[key] = repaired.value;
+  }
+  return { value: changed ? out : value, changed };
+}
+
+/**
+ * Move an emitted object's unknown keys onto the declared properties it left
+ * missing, but only when the mapping is FORCED: every unknown key must have
+ * exactly one structurally compatible missing property (the single missing
+ * string slot, the single missing array slot, ...). Nothing is matched by name
+ * similarity, and an ambiguous element returns null so the caller discards it.
+ *
+ * This is what recovers the free models' invented parallel vocabulary — a
+ * model that writes `{ name, tasks }` for a declared `{ phase, items }` is
+ * mapped by role, not by guessing that `name` means `phase`.
+ */
+function adoptDeclaredKeys(
+  value: Record<string, unknown>,
+  schema: Record<string, unknown>,
+ ): Record<string, unknown> | null {
+  const props = schema.properties;
+  if (props === null || typeof props !== "object" || Array.isArray(props)) return null;
+  const declared = props as Record<string, Record<string, unknown>>;
+  const unknownKeys = Object.keys(value).filter((key) => !(key in declared));
+  // Nothing unknown: the element already states its intent, so leave it be.
+  if (unknownKeys.length === 0) return null;
+  const missing = Object.keys(declared).filter((key) => !(key in value));
+  if (unknownKeys.length > missing.length) return null;
+  const taken = new Set<string>();
+  const targets = new Map<string, string>();
+  for (const key of unknownKeys) {
+   const raw = value[key];
+   const want = Array.isArray(raw) ? "array" : raw !== null && typeof raw === "object" ? "object" : typeof raw;
+   const candidates = missing.filter((name) => !taken.has(name) && schemaType(declared[name]) === want);
+   if (candidates.length !== 1) return null;
+   taken.add(candidates[0]);
+   targets.set(key, candidates[0]);
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) out[targets.get(key) ?? key] = entry;
+  return out;
+}
+
+/** True when every key on the object is declared by the schema. */
+function elementKeysDeclared(value: Record<string, unknown>, schema: Record<string, unknown>): boolean {
+  const props = schema.properties;
+  if (props === null || typeof props !== "object" || Array.isArray(props)) return false;
+  return Object.keys(value).every((key) => key in (props as Record<string, unknown>));
+}
+
+/**
+ * Move a model's misplaced phases into the declared object-array property it
+ * left absent. Two source shapes are accepted, both reproduced live against
+ * the free models: a declared string-array whose elements are JSON-encoded
+ * phase objects, and an entirely undeclared property holding phase objects
+ * under invented names. Either way EVERY element must end up validating
+ * against the target item schema, so one JSON-looking task label or one
+ * ambiguous element discards the whole move and the call rides through
+ * untouched.
+ */
+function promoteStringArray(
+  args: Record<string, unknown>,
+  schema: Record<string, unknown>,
+  depth: number,
+): Record<string, unknown> {
+  if (depth > MAX_DEPTH) return args;
+  const props = schema.properties;
+  if (props === null || typeof props !== "object" || Array.isArray(props)) return args;
+  const declared = props as Record<string, Record<string, unknown>>;
+  const required = new Set(
+   Array.isArray(schema.required) ? schema.required.filter((key): key is string => typeof key === "string") : [],
+  );
+  const out = { ...args };
+  let moved = false;
+  for (const [targetName, targetSchema] of Object.entries(declared)) {
+   if (schemaType(targetSchema) !== "array") continue;
+   const targetItems = targetSchema.items;
+   if (targetItems === null || typeof targetItems !== "object" || Array.isArray(targetItems)) continue;
+   if (schemaType(targetItems as Record<string, unknown>) !== "object") continue;
+   if (targetName in out) continue;
+   for (const [sourceName, sourceValue] of Object.entries(args)) {
+    if (sourceName === targetName) continue;
+    const sourceSchema = declared[sourceName];
+    // A DECLARED source must be a scalar-item array: that is the only way a
+    // string slot can legitimately hold an encoded structure. An UNDECLARED
+    // source is the invented-vocabulary shape and is accepted as emitted.
+    if (sourceSchema !== undefined) {
+     if (schemaType(sourceSchema) !== "array") continue;
+     const sourceItems = sourceSchema.items;
+     if (sourceItems !== null && typeof sourceItems === "object" && !Array.isArray(sourceItems) &&
+      schemaType(sourceItems as Record<string, unknown>) === "object") continue;
+    }
+    // A JSON-string source stands for the array it encodes.
+    let source: unknown = sourceValue;
+    if (typeof source === "string") {
+     const trimmed = source.trim();
+     if (!trimmed.startsWith("[")) continue;
+     try {
+      source = JSON.parse(trimmed);
+     } catch {
+      continue;
+     }
+    }
+    if (!Array.isArray(source) || source.length === 0) continue;
+    const promoted: unknown[] = [];
+    let usable = true;
+    for (const element of source) {
+     let parsed: unknown = element;
+     if (typeof parsed === "string") {
+      try {
+       parsed = JSON.parse(parsed);
+      } catch {
+       usable = false;
+       break;
+      }
+     }
+     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      usable = false;
+      break;
+     }
+     const item = parsed as Record<string, unknown>;
+     const repaired = repairValue(item, targetItems as Record<string, unknown>, depth + 1);
+     const shaped =
+      repaired.value !== null && typeof repaired.value === "object" && !Array.isArray(repaired.value)
+       ? (repaired.value as Record<string, unknown>)
+       : item;
+     const adopted = adoptDeclaredKeys(shaped, targetItems as Record<string, unknown>);
+     const candidate = adopted ?? shaped;
+     if (!elementKeysDeclared(candidate, targetItems as Record<string, unknown>)) {
+      // Keys the schema never declares survived and could not be placed:
+      // promoting would smuggle the model's invention into the host.
+      usable = false;
+      break;
+     }
+     if (!matchesSchema(candidate, targetItems as Record<string, unknown>, depth + 1)) {
+      usable = false;
+      break;
+     }
+     promoted.push(candidate);
+    }
+    if (!usable) continue;
+    out[targetName] = promoted;
+    moved = true;
+    if (!required.has(sourceName)) delete out[sourceName];
+    break;
+   }
+  }
+  return moved ? out : args;
+}
+
+/**
+ * Per-request map of caller tool name (lowercased) to the schema its
+ * arguments are repaired against. Only tools whose parameters declare at least
+ * one object or array property are kept: those are the only ones a repair can
+ * act on, and an empty map means the request streams byte-identically.
+ *
+ * Keyed by CALLER name, which is what arrives downstream after the casing and
+ * find->glob restores. Injected fingerprint placeholders are absent by
+ * construction, so they are never repaired.
+ */
+export function buildArgRepairSchemas(tools: unknown[]): Map<string, Record<string, unknown>> {
+  const schemas = new Map<string, Record<string, unknown>>();
+  for (const tool of tools) {
+   const canon = canonicalizeTool(tool);
+   if (canon === null) continue;
+   const props = canon.parameters.properties;
+   if (props === null || typeof props !== "object" || Array.isArray(props)) continue;
+   const hasStructural = Object.values(props as Record<string, unknown>).some(
+    (prop) => prop !== null && typeof prop === "object" && !Array.isArray(prop) && structuralProperty(prop as Record<string, unknown>),
+   );
+   if (!hasStructural) continue;
+   schemas.set(canon.name.trim().toLowerCase(), canon.parameters);
+  }
+  return schemas;
+}
+
+/**
+ * Repair one tool call's arguments against its declared schema. `name` is the
+ * downstream (restored) caller tool name. Returns the input string untouched
+ * unless the repair produced a schema-valid result, so well-formed calls stay
+ * byte-identical and truncated JSON is never completed.
+ */
+export function repairToolArguments(
+  name: string,
+  argsJson: string,
+  schemas: ReadonlyMap<string, Record<string, unknown>> | undefined,
+): string {
+  if (schemas === undefined || schemas.size === 0) return argsJson;
+  const schema = schemas.get(name.trim().toLowerCase());
+  if (schema === undefined) return argsJson;
+  let parsed: unknown;
+  try {
+   parsed = JSON.parse(argsJson);
+  } catch {
+   // Truncated or non-JSON arguments: paper over nothing.
+   return argsJson;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return argsJson;
+  const rec = parsed as Record<string, unknown>;
+  const repaired = repairValue(rec, schema, 0);
+  const value = repaired.value === null || typeof repaired.value !== "object" || Array.isArray(repaired.value)
+   ? rec
+   : (repaired.value as Record<string, unknown>);
+  const promoted = promoteStringArray(value, schema, 0);
+  const result = promoted === value ? value : promoted;
+  if (!repaired.changed && promoted === value) return argsJson;
+  if (!matchesSchema(result, schema, 0)) return argsJson;
+  return JSON.stringify(result);
+}
+
+/**
+ * Value-level repair for wire APIs that carry tool arguments already parsed
+ * (Anthropic `tool_use.input`). Returns the input object untouched unless the
+ * repair produced a schema-valid result, so a well-formed call keeps
+ * reference identity and callers can skip re-serialization.
+ */
+export function repairToolArgumentsValue(
+ name: string,
+ args: unknown,
+ schemas: ReadonlyMap<string, Record<string, unknown>> | undefined,
+): unknown {
+ if (schemas === undefined || schemas.size === 0) return args;
+ const schema = schemas.get(name.trim().toLowerCase());
+ if (schema === undefined) return args;
+ if (args === null || typeof args !== "object" || Array.isArray(args)) return args;
+ const rec = args as Record<string, unknown>;
+ const repaired = repairValue(rec, schema, 0);
+ const value = repaired.value === null || typeof repaired.value !== "object" || Array.isArray(repaired.value)
+  ? rec
+  : (repaired.value as Record<string, unknown>);
+ // Promotion must run even when shape repair was idle: the reported payload
+ // is already correctly typed, it just carries the phases in the wrong slot.
+ const promoted = promoteStringArray(value, schema, 0);
+ const result = promoted === value ? value : promoted;
+ if (result === args) return args;
+ if (!matchesSchema(result, schema, 0)) return args;
+ return result;
+}