fix(agents): prevent missing_tool_result from triggering cross-provider model fallback (#95474)

Pandah97 · Pandah97 · commit 7df207eb4897 · 2026-06-21T13:27:34.000+08:00
When a Codex bash call hangs, the event-projector synthesizes a
missing_tool_result error. This is a local tool-execution failure, not a
provider/model failure — switching providers cannot fix it. Previously,
the error was unclassified and consumed model fallback candidates.

Add isLocalToolExecutionError to detect the sentinel error text and abort
the outer fallback chain instead of trying the next candidate.
diff --git a/src/agents/failover-error.test.ts b/src/agents/failover-error.test.ts
@@ -10,6 +10,7 @@ import {
   coerceToFailoverError,
   describeFailoverError,
   FailoverError,
+  isLocalToolExecutionError,
   isNonProviderRuntimeCoordinationError,
   isSignalTimeoutReason,
   isTimeoutError,
@@ -1306,6 +1307,35 @@ describe("failover-error", () => {
       expect(isNonProviderRuntimeCoordinationError(undefined)).toBe(false);
     });
   });
+
+  describe("isLocalToolExecutionError", () => {
+    const MISSING_TOOL_RESULT_MESSAGE =
+      "OpenClaw recorded a native Codex tool.call without a matching tool.result before the turn completed.";
+
+    it("returns true for exact missing_tool_result error message", () => {
+      expect(isLocalToolExecutionError(MISSING_TOOL_RESULT_MESSAGE)).toBe(true);
+    });
+
+    it("returns true when the missing_tool_result message is wrapped as an Error", () => {
+      expect(isLocalToolExecutionError(new Error(MISSING_TOOL_RESULT_MESSAGE))).toBe(true);
+    });
+
+    it("returns false for provider errors (rate limit, auth, timeout)", () => {
+      expect(isLocalToolExecutionError(OPENAI_RATE_LIMIT_MESSAGE)).toBe(false);
+      expect(isLocalToolExecutionError(ANTHROPIC_OVERLOADED_PAYLOAD)).toBe(false);
+      expect(isLocalToolExecutionError(BEDROCK_THROTTLING_EXCEPTION_MESSAGE)).toBe(false);
+    });
+
+    it("returns false for null, undefined, and empty string", () => {
+      expect(isLocalToolExecutionError(null)).toBe(false);
+      expect(isLocalToolExecutionError(undefined)).toBe(false);
+      expect(isLocalToolExecutionError("")).toBe(false);
+    });
+
+    it("returns false for non-Error objects without the sentinel text", () => {
+      expect(isLocalToolExecutionError({ status: 500, message: "internal error" })).toBe(false);
+    });
+  });
 });
 
 describe("buildFailoverRemediationHint", () => {
diff --git a/src/agents/failover-error.ts b/src/agents/failover-error.ts
@@ -364,6 +364,30 @@ export function isNonProviderRuntimeCoordinationError(err: unknown): boolean {
   return resolveFailoverClassificationFromError(err) === null;
 }
 
+/**
+ * The sentinel text that Codex app-server (event-projector.ts) stores when a
+ * native tool.call finished without a matching tool.result. The model fallback
+ * chain must not consume candidates on this — no other provider can fix a local
+ * command that hung or was reaped. See #95474.
+ */
+const MISSING_TOOL_RESULT_MESSAGE_PREFIX =
+  "OpenClaw recorded a native Codex tool.call without a matching tool.result";
+
+/**
+ * True when the error is a local tool-execution failure (synthetic
+ * missing_tool_result from a hung native Codex tool.call) rather than a true
+ * provider/model failure. The model fallback chain must abort on these instead
+ * of consuming candidate slots — switching providers cannot fix a local command.
+ * See #95474.
+ */
+export function isLocalToolExecutionError(err: unknown): boolean {
+  if (!err) {
+    return false;
+  }
+  const message = typeof err === "string" ? err : err instanceof Error ? err.message : null;
+  return typeof message === "string" && message.includes(MISSING_TOOL_RESULT_MESSAGE_PREFIX);
+}
+
 function hasTimeoutHint(err: unknown): boolean {
   if (!err) {
     return false;
diff --git a/src/agents/model-fallback.test.ts b/src/agents/model-fallback.test.ts
@@ -1271,6 +1271,33 @@ describe("runWithModelFallback", () => {
     expect(run).toHaveBeenCalledTimes(1);
   });
 
+  it("aborts the fallback chain on missing_tool_result instead of trying every model (#95474)", async () => {
+    const cfg = makeCfg({
+      agents: {
+        defaults: {
+          model: {
+            primary: "openai/gpt-5.4",
+            fallbacks: ["anthropic/claude-sonnet-4-6", "openai/gpt-4.1-mini"],
+          },
+        },
+      },
+    });
+    const missingToolResultError = new Error(
+      "OpenClaw recorded a native Codex tool.call without a matching tool.result before the turn completed.",
+    );
+    const run = vi.fn().mockRejectedValue(missingToolResultError);
+
+    await expect(
+      runWithModelFallback({
+        cfg,
+        provider: "openai",
+        model: "gpt-5.4",
+        run,
+      }),
+    ).rejects.toBe(missingToolResultError);
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+
   it("keeps provider failover metadata authoritative over nested session locks", async () => {
     const cfg = makeCfg({
       agents: {
diff --git a/src/agents/model-fallback.ts b/src/agents/model-fallback.ts
@@ -38,6 +38,7 @@ import {
   coerceToFailoverError,
   describeFailoverError,
   isFailoverError,
+  isLocalToolExecutionError,
   isNonProviderRuntimeCoordinationError,
   isTimeoutError,
 } from "./failover-error.js";
@@ -1734,6 +1735,13 @@ async function runWithModelFallbackInternal<T>(
       if (isMissingAgentHarnessError(err)) {
         throw err;
       }
+      // Local tool-execution failures (synthetic missing_tool_result from a
+      // hung native Codex tool.call) are not provider/model failures. Throwing
+      // here prevents the fallback chain from switching providers for a local
+      // command that no other provider can fix. See #95474.
+      if (isLocalToolExecutionError(err)) {
+        throw err;
+      }
       const normalized =
         coerceToFailoverError(err, {
           provider: candidate.provider,
