fix: guard synthetic placeholder fallback

wangwllu · wangwllu · commit b8128bebd244 · 2026-07-03T08:43:52.000+08:00
diff --git a/src/agents/embedded-agent-runner/result-fallback-classifier.test.ts b/src/agents/embedded-agent-runner/result-fallback-classifier.test.ts
@@ -481,6 +481,85 @@ describe("classifyEmbeddedAgentRunResultForModelFallback", () => {
     });
   });
 
+  it("keeps a synthetic-placeholder marker with visible final text out of fallback", () => {
+    const result = classifyEmbeddedAgentRunResultForModelFallback({
+      provider: "claude-cli",
+      model: "Claude-Opus-4.7",
+      result: {
+        meta: {
+          durationMs: 42,
+          terminalReplyKind: "synthetic-placeholder",
+          finalAssistantVisibleText: "Here is the requested answer.",
+        },
+      },
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("keeps a synthetic-placeholder marker with a visible payload out of fallback", () => {
+    const result = classifyEmbeddedAgentRunResultForModelFallback({
+      provider: "claude-cli",
+      model: "Claude-Opus-4.7",
+      result: {
+        payloads: [{ text: "Here is the requested answer." }],
+        meta: {
+          durationMs: 42,
+          terminalReplyKind: "synthetic-placeholder",
+        },
+      },
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("preserves hook block results with a synthetic-placeholder marker", () => {
+    const result = classifyEmbeddedAgentRunResultForModelFallback({
+      provider: "claude-cli",
+      model: "Claude-Opus-4.7",
+      result: {
+        meta: {
+          durationMs: 42,
+          terminalReplyKind: "synthetic-placeholder",
+          error: {
+            kind: "hook_block",
+            message: "Blocked by hook",
+          },
+        },
+      },
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("keeps fallback-safe incomplete turns ahead of synthetic-placeholder classification", () => {
+    const result = classifyEmbeddedAgentRunResultForModelFallback({
+      provider: "claude-cli",
+      model: "Claude-Opus-4.7",
+      result: {
+        payloads: [{ isError: true, text: "Agent couldn't generate a response." }],
+        meta: {
+          durationMs: 42,
+          terminalReplyKind: "synthetic-placeholder",
+          error: {
+            kind: "incomplete_turn",
+            message: "Agent couldn't generate a response.",
+            fallbackSafe: true,
+            terminalPresentation: true,
+          },
+        },
+      },
+    });
+
+    expect(result).toEqual({
+      message: "Agent couldn't generate a response.",
+      reason: "format",
+      code: "incomplete_result",
+      preserveResultOnExhaustion: true,
+      preserveResultPriority: 1,
+    });
+  });
+
   it("keeps explicit silent terminal replies out of fallback", () => {
     const result = classifyEmbeddedAgentRunResultForModelFallback({
       provider: "openai",
diff --git a/src/agents/embedded-agent-runner/result-fallback-classifier.ts b/src/agents/embedded-agent-runner/result-fallback-classifier.ts
@@ -94,6 +94,29 @@ function hasNonTextVisiblePayloadContent(
   );
 }
 
+/**
+ * True when the run surfaced user-facing assistant output (non-silent final text or a visible
+ * payload) that should be delivered instead of retried on a fallback model.
+ *
+ * Shared by the synthetic-placeholder guard and the generic visible-output guard so a
+ * marked-but-visible turn (e.g. a `<synthetic>` placeholder followed by a real non-empty Claude
+ * result) is never misclassified as an empty result and retried.
+ */
+function hasVisibleUserFacingReply(result: EmbeddedAgentRunResult): boolean {
+  const finalVisibleText = result.meta.finalAssistantVisibleText;
+  if (
+    typeof finalVisibleText === "string" &&
+    finalVisibleText.trim().length > 0 &&
+    !isSilentReplyPayloadText(finalVisibleText)
+  ) {
+    return true;
+  }
+  return hasVisibleAgentPayload(result, {
+    includeErrorPayloads: false,
+    includeReasoningPayloads: false,
+  });
+}
+
 function classifyGenericExternalRunFailurePayload(params: {
   provider: string;
   model: string;
@@ -201,13 +224,6 @@ export function classifyEmbeddedAgentRunResultForModelFallback(params: {
   if (hasCommittedOutboundDeliveryEvidence(params.result)) {
     return null;
   }
-  if (params.result.meta.terminalReplyKind === "synthetic-placeholder") {
-    return {
-      message: `${params.provider}/${params.model} ended with a synthetic placeholder and no visible assistant reply`,
-      reason: "format",
-      code: "empty_result",
-    };
-  }
   if (params.result.meta.error?.kind === "hook_block") {
     // Hook blocks intentionally suppress normal agent output. Retrying on another model would
     // bypass a policy decision rather than recover a malformed model result.
@@ -222,19 +238,7 @@ export function classifyEmbeddedAgentRunResultForModelFallback(params: {
   if (genericExternalFailureClassification) {
     return genericExternalFailureClassification;
   }
-  if (
-    typeof params.result.meta.finalAssistantVisibleText === "string" &&
-    params.result.meta.finalAssistantVisibleText.trim().length > 0 &&
-    !isSilentReplyPayloadText(params.result.meta.finalAssistantVisibleText)
-  ) {
-    return null;
-  }
-  if (
-    hasVisibleAgentPayload(params.result, {
-      includeErrorPayloads: false,
-      includeReasoningPayloads: false,
-    })
-  ) {
+  if (hasVisibleUserFacingReply(params.result)) {
     return null;
   }
 
@@ -252,6 +256,16 @@ export function classifyEmbeddedAgentRunResultForModelFallback(params: {
       preserveResultPriority: params.result.meta.error?.terminalPresentation === true ? 1 : 0,
     };
   }
+  if (
+    params.result.meta.terminalReplyKind === "synthetic-placeholder" &&
+    !hasVisibleUserFacingReply(params.result)
+  ) {
+    return {
+      message: `${params.provider}/${params.model} ended with a synthetic placeholder and no visible assistant reply`,
+      reason: "format",
+      code: "empty_result",
+    };
+  }
   const harnessClassification = classifyHarnessResult({
     provider: params.provider,
     model: params.model,
