feat(ai-anthropic): server-side refusal fallback, and refusals finish with content_filter

.changeset/anthropic-refusal-fallback.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-anthropic': minor
+---
+
+Add the `fallbacks` model option for Anthropic server-side refusal fallback. Set `modelOptions: { fallbacks: 'default' }` on `claude-fable-5`, `claude-fable-5-1`, `claude-opus-5`, `claude-opus-5-5` or `claude-sonnet-5-5`. When a safety classifier declines the request, the API answers with another model in the same call. The adapter sends the `server-side-fallback-2026-07-01` beta header for you.
+
+A response with `stop_reason: "refusal"` now finishes with `finishReason: 'content_filter'`. Before, it finished with `'stop'`. The refusal `stop_details` (`category`, `explanation`) is on the `RUN_FINISHED` event as `rawEvent`.

docs/adapters/anthropic.md

@@ -270,6 +270,88 @@ Newest first. The package exports the full list as `ANTHROPIC_MODELS`.
 
 `adapter.inputModalities` lists the input kinds of the selected model. See [Check what a model accepts](../advanced/extend-adapter#check-what-a-model-accepts).
 
+
+### Refusal fallback
+
+Did Claude return an empty answer to a life-science or security question? A safety classifier on the newer models can decline a request. Set `fallbacks`, and the Claude API sends a declined request to another Claude model in the same call:
+
+```typescript
+import { chat, toServerSentEventsResponse } from "@tanstack/ai";
+import { anthropicText } from "@tanstack/ai-anthropic";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  const stream = chat({
+    adapter: anthropicText("claude-opus-5-5"),
+    messages,
+    threadId: "thread-1",
+    modelOptions: { fallbacks: "default" },
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+What this does:
+
+- `"default"` uses the model that Anthropic recommends for the refusal category. A list, such as `[{ model: "claude-opus-4-8" }]`, names up to three models to try in order.
+- The adapter adds the `server-side-fallback-2026-07-01` beta header for you.
+- The fallback answer streams like any other answer. When text has already started, events before the `fallback` block name the model that declined. That includes `RUN_STARTED` and that first text segment. Events after the block name `to.model`.
+- When the classifier declines before any output, `message_start` already names the fallback model. `RUN_STARTED` uses that name too.
+- The types accept `fallbacks` on `claude-fable-5`, `claude-fable-5-1`, `claude-opus-5`, `claude-opus-5-5`, and `claude-sonnet-5-5`.
+
+Some refusals still stand. For example, a category can have no recommended model, or the fallback model can be busy. Then the run ends with `finishReason: "content_filter"`, not with an error. The `rawEvent` of that `RUN_FINISHED` holds the Anthropic `stop_details`, with `category` and `explanation`.
+
+Show the reason in the UI with `onChunk`:
+
+```tsx
+import { useState } from "react";
+import { fetchServerSentEvents, useChat } from "@tanstack/ai-react";
+
+export function Chat() {
+  const [refusal, setRefusal] = useState<string | null>(null);
+
+  const { messages, sendMessage } = useChat({
+    connection: fetchServerSentEvents("/api/chat"),
+    threadId: "support-chat",
+    onChunk: (chunk) => {
+      if (chunk.type === "RUN_FINISHED" && chunk.finishReason === "content_filter") {
+        const details = chunk.rawEvent;
+        const category =
+          details &&
+          typeof details === "object" &&
+          "category" in details &&
+          typeof details.category === "string"
+            ? details.category
+            : "unknown";
+        setRefusal(`Claude declined this request (category: ${category}).`);
+      }
+    },
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <p key={message.id}>
+          {message.parts.map((part) => (part.type === "text" ? part.content : null))}
+        </p>
+      ))}
+      {refusal && <p role="alert">{refusal}</p>}
+      <button onClick={() => sendMessage("Describe how CRISPR edits a gene.")}>Send</button>
+    </div>
+  );
+}
+```
+
+Limits:
+
+- Fallback works only on the Claude API. Claude on Vertex does not have it.
+- `claude-haiku-5-5` has no fallback model, so its refusals always stand.
+- The adapter does not send the `fallback` content block back on the next turn. A refusal before any output is not affected.
+
+Now a declined request gets an answer from a fallback model. When no model can answer, your UI tells the user why.
+
 ## Advanced
 
 These topics are on [Anthropic: Advanced](./anthropic-advanced):

packages/ai-anthropic/src/adapters/text.ts

@@ -236,7 +236,8 @@ const COMPUTER_USE_BETAS = {
  *   computer toolset needs none),
  * - `context-management-2025-06-27` when `context_management` is set,
  * - `files-api-2025-04-14` when a message references an uploaded file handle,
- * - `mid-conversation-tool-changes-2026-07-01` in mid-conversation tool mode.
+ * - `mid-conversation-tool-changes-2026-07-01` in mid-conversation tool mode,
+ * - `server-side-fallback-2026-07-01` when `modelOptions.fallbacks` is set.
  * Returns `undefined` when none apply (so the call site omits `betas`).
  */
 export function computeAnthropicBetas(
@@ -248,6 +249,7 @@ export function computeAnthropicBetas(
           budget_tokens?: number
         }
         context_management?: unknown | null
+        fallbacks?: unknown
         mcp_servers?: ReadonlyArray<unknown>
       }
     | undefined,
@@ -273,6 +275,11 @@ export function computeAnthropicBetas(
     betas.add('context-management-2025-06-27')
   }
 
+  // Server-side refusal fallback: the API rejects `fallbacks` without it.
+  if (modelOptions?.fallbacks != null) {
+    betas.add('server-side-fallback-2026-07-01')
+  }
+
   // The MCP connector needs its beta header as well (same shape as #1074);
   // an empty array is a typed "unset" — do not enable the beta.
   // ponytail: 2025-04-04 matches the `mcp_servers` shape we type
@@ -850,6 +857,7 @@ export class AnthropicTextAdapter<
         'cache_control',
         'container',
         'context_management',
+        'fallbacks',
         'mcp_servers',
         'service_tier',
         'stop_sequences',
@@ -1641,7 +1649,25 @@ export class AnthropicTextAdapter<
           messageStartUsage = event.message.usage
         } else if (event.type === 'content_block_start') {
           currentBlockType = event.content_block.type
-          if (event.content_block.type === 'tool_use') {
+          if (currentBlockType === 'fallback') {
+            // Server-side fallback handoff. The rest of the stream comes from
+            // `to.model`. message_start names the declining model only after
+            // output has started. Before any output, message_start already
+            // names the fallback model.
+            const block: unknown = event.content_block
+            const to =
+              block && typeof block === 'object' && 'to' in block
+                ? block.to
+                : undefined
+            if (
+              to &&
+              typeof to === 'object' &&
+              'model' in to &&
+              typeof to.model === 'string'
+            ) {
+              model = to.model
+            }
+          } else if (event.content_block.type === 'tool_use') {
             currentToolIndex++
             // A computer toolset call names its action. It runs as one
             // `computer` call with the action in `input.action`.
@@ -2033,6 +2059,10 @@ export class AnthropicTextAdapter<
           ) {
             // The model already consumed the result; error variants were
             // already surfaced at content_block_start.
+          } else if (currentBlockType === 'fallback') {
+            // Server-side fallback handoff: the declining model's text block
+            // already closed. The fallback model's text starts a fresh segment.
+            hasEmittedTextMessageStart = false
           } else {
             // Emit TEXT_MESSAGE_END only for text blocks (not tool_use blocks)
             if (hasEmittedTextMessageStart && accumulatedContent) {
@@ -2165,10 +2195,28 @@ export class AnthropicTextAdapter<
                 }
                 break
               }
+              case 'refusal': {
+                // A safety classifier declined and no server-side fallback
+                // served the request. Not an error: the run ends like a
+                // filtered completion, and `rawEvent` says why.
+                yield {
+                  type: EventType.RUN_FINISHED,
+                  ...(responseId !== undefined && { responseId }),
+                  runId,
+                  threadId,
+                  model,
+                  timestamp: Date.now(),
+                  finishReason: 'content_filter',
+                  ...(event.delta.stop_details && {
+                    rawEvent: event.delta.stop_details,
+                  }),
+                  usage,
+                }
+                break
+              }
               case 'stop_sequence':
               case 'end_turn':
               case 'pause_turn':
-              case 'refusal':
               case 'compaction':
               default: {
                 // All remaining Anthropic stop_reason variants map to the

packages/ai-anthropic/src/model-meta.ts

@@ -8,6 +8,7 @@ import type {
   AnthropicCacheControlOptions,
   AnthropicContainerOptions,
   AnthropicContextManagementOptions,
+  AnthropicFallbackOptions,
   AnthropicMCPOptions,
   AnthropicMaxTokensOptions,
   AnthropicSamplingOptions,
@@ -525,6 +526,7 @@ const CLAUDE_FABLE_5 = {
   AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -621,6 +623,7 @@ const CLAUDE_OPUS_5 = {
 } as const satisfies ModelMeta<
   AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -692,6 +695,7 @@ const CLAUDE_FABLE_5_1 = {
   AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -734,6 +738,7 @@ const CLAUDE_OPUS_5_5 = {
   AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -782,6 +787,7 @@ const CLAUDE_SONNET_5_5 = {
   AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -1083,6 +1089,7 @@ export type AnthropicChatModelProviderOptionsByName = {
   [CLAUDE_FABLE_5.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -1101,6 +1108,7 @@ export type AnthropicChatModelProviderOptionsByName = {
     AnthropicMaxTokensOptions
   [CLAUDE_OPUS_5.id]: AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -1116,6 +1124,7 @@ export type AnthropicChatModelProviderOptionsByName = {
   [CLAUDE_FABLE_5_1.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -1124,6 +1133,7 @@ export type AnthropicChatModelProviderOptionsByName = {
   [CLAUDE_OPUS_5_5.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &
@@ -1134,6 +1144,7 @@ export type AnthropicChatModelProviderOptionsByName = {
   [CLAUDE_SONNET_5_5.id]: AnthropicCacheControlOptions &
     AnthropicContainerOptions &
     AnthropicContextManagementOptions &
+    AnthropicFallbackOptions &
     AnthropicMCPOptions &
     AnthropicServiceTierOptions &
     AnthropicStopSequencesOptions &

packages/ai-anthropic/src/text/text-provider-options.ts

@@ -1,6 +1,7 @@
 import type { AnthropicThinkingFields } from './reasoning'
 import type {
   BetaContextManagementConfig,
+  BetaFallbacksParam,
   BetaMessageParam,
   BetaTool,
   BetaToolChoiceAny,
@@ -76,6 +77,17 @@ This allows you to control how Claude manages context across multiple requests,
   context_management?: BetaContextManagementConfig | null
 }
 
+export interface AnthropicFallbackOptions {
+  /**
+   * Server-side refusal fallback (beta, Claude API only). When a safety
+   * classifier declines the request, the API retries it on another model in
+   * the same call. `'default'` uses the model Anthropic recommends for the
+   * refusal category. A list names up to three models to try in order.
+   * The adapter adds the `server-side-fallback-2026-07-01` beta header.
+   */
+  fallbacks?: BetaFallbacksParam | null
+}
+
 export interface AnthropicMCPOptions {
   /**
    * MCP servers to be utilized in this request
@@ -153,6 +165,7 @@ Required range: x >= 0
 export type ExternalTextProviderOptions = AnthropicCacheControlOptions &
   AnthropicContainerOptions &
   AnthropicContextManagementOptions &
+  AnthropicFallbackOptions &
   AnthropicMCPOptions &
   AnthropicServiceTierOptions &
   AnthropicStopSequencesOptions &

packages/ai-anthropic/tests/chat-per-model-type-safety.test.ts

@@ -322,6 +322,32 @@ describe('Anthropic per-model chat reasoning gating', () => {
 })
 
 describe('Anthropic provider options shape assertions', () => {
+  describe('fallbacks', () => {
+    it('is accepted on the five Claude 5 models that support it', () => {
+      expectTypeOf<
+        AnthropicChatModelProviderOptionsByName['claude-fable-5']
+      >().toHaveProperty('fallbacks')
+      expectTypeOf<
+        AnthropicChatModelProviderOptionsByName['claude-fable-5-1']
+      >().toHaveProperty('fallbacks')
+      expectTypeOf<
+        AnthropicChatModelProviderOptionsByName['claude-opus-5']
+      >().toHaveProperty('fallbacks')
+      expectTypeOf<
+        AnthropicChatModelProviderOptionsByName['claude-opus-5-5']
+      >().toHaveProperty('fallbacks')
+      expectTypeOf<
+        AnthropicChatModelProviderOptionsByName['claude-sonnet-5-5']
+      >().toHaveProperty('fallbacks')
+    })
+
+    it('is rejected on claude-haiku-5-5', () => {
+      expectTypeOf<
+        AnthropicChatModelProviderOptionsByName['claude-haiku-5-5']
+      >().not.toHaveProperty('fallbacks')
+    })
+  })
+
   describe('claude-opus-4-6 — full feature set', () => {
     type Options = AnthropicChatModelProviderOptionsByName['claude-opus-4-6']