fix(anthropic): default max_tokens to the model's output ceiling (#849)

Anthropic's Messages API requires `max_tokens`, so the text adapter must
always send a value. It previously hard-coded `?? 1024` when the caller
didn't pass one, silently truncating any non-trivial generation mid-stream
with `stop_reason: "max_tokens"`.

Now default to the resolved model's real `max_output_tokens` from model-meta
(e.g. 64K Sonnet, 128K Opus), falling back to 64K for unrecognized ids.
`max_tokens` is a ceiling, not a reservation, so this costs nothing extra.
Also log a warning when a response is truncated while using the defaulted
cap, so it isn't silently read as the model "doing nothing"; callers that set
`max_tokens` explicitly are unaffected.

The new id -> max_output_tokens map is kept in lockstep with ANTHROPIC_MODELS
by `scripts/sync-provider-models.ts`, so a freshly-synced model resolves to
its real ceiling rather than the fallback.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tombeckenham

.changeset/anthropic-max-tokens-default.md

@@ -0,0 +1,15 @@
+---
+'@tanstack/ai-anthropic': patch
+---
+
+Default Anthropic `max_tokens` to the selected model's real output ceiling
+(`max_output_tokens` from model metadata — e.g. 64K for Sonnet, 128K for Opus)
+when the caller doesn't pass one, instead of a hard-coded `1024` that silently
+truncated long responses with `stop_reason: "max_tokens"` (#849). Unknown
+models fall back to a safe constant. `max_tokens` is a ceiling, not a
+reservation, so this costs nothing unless the model genuinely produces more.
+
+The adapter also now logs a warning when a response is truncated while using the
+defaulted (caller-unspecified) cap, so the truncation isn't silently attributed
+to the model "doing nothing". Callers that set `modelOptions.max_tokens`
+explicitly are unaffected.

docs/adapters/anthropic.md

@@ -136,6 +136,10 @@ const stream = chat({
 
 > If you previously passed `temperature` / `topP` / `maxTokens` at the root of `chat()`, see [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options).
 
+#### `max_tokens` default
+
+Anthropic's Messages API _requires_ `max_tokens` on every request, so the adapter always sends a value. When you don't set `modelOptions.max_tokens`, it defaults to the selected model's full output ceiling (`max_output_tokens` from the model metadata — e.g. 64K for Sonnet, 128K for Opus), falling back to a safe constant for unrecognized models. `max_tokens` is a ceiling, not a reservation — billing is on tokens actually generated — so this default costs nothing extra and avoids the silent mid-response truncation (`stop_reason: "max_tokens"`) that a low default would cause. Set `max_tokens` explicitly only when you want to _cap_ output below the model ceiling. If a response is truncated while using the default cap, the adapter logs a warning (visible with [debug logging](../advanced/debug-logging) enabled).
+
 ### Thinking (Extended Thinking)
 
 Enable extended thinking with a token budget. This allows Claude to show its reasoning process, which is streamed as `thinking` chunks:

docs/config.json

@@ -431,7 +431,8 @@
         {
           "label": "Anthropic",
           "to": "adapters/anthropic",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-06-26"
         },
         {
           "label": "Google Gemini",

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

@@ -10,7 +10,10 @@ import {
   generateId,
   getAnthropicApiKeyFromEnv,
 } from '../utils'
-import { ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS } from '../model-meta'
+import {
+  ANTHROPIC_COMBINED_TOOLS_AND_SCHEMA_MODELS,
+  getAnthropicDefaultMaxTokens,
+} from '../model-meta'
 import type {
   ANTHROPIC_MODELS,
   AnthropicChatModelProviderOptionsByName,
@@ -420,7 +423,14 @@ export class AnthropicTextAdapter<
       validProviderOptions.thinking?.type === 'enabled'
         ? validProviderOptions.thinking.budget_tokens
         : undefined
-    const defaultMaxTokens = modelOptions?.max_tokens ?? 1024
+    // Anthropic's Messages API *requires* `max_tokens`, so we must always send a
+    // value. When the caller doesn't specify one, default to the resolved
+    // model's real output ceiling (from model-meta) rather than a low constant
+    // that silently truncates long responses with `stop_reason: "max_tokens"`
+    // (issue #849). `max_tokens` is a ceiling, not a reservation — billing is on
+    // tokens actually generated, so a higher default costs nothing extra.
+    const defaultMaxTokens =
+      modelOptions?.max_tokens ?? getAnthropicDefaultMaxTokens(this.model)
     const maxTokens =
       thinkingBudget && thinkingBudget >= defaultMaxTokens
         ? thinkingBudget + 1
@@ -1181,6 +1191,22 @@ export class AnthropicTextAdapter<
                 break
               }
               case 'max_tokens': {
+                // Surface a warning when the truncating cap was the
+                // adapter-supplied default (caller didn't pass `max_tokens`), so
+                // the truncation isn't silently attributed to the model "doing
+                // nothing" (issue #849). When the caller set `max_tokens`
+                // themselves, hitting it is their own deliberate ceiling.
+                if (options.modelOptions?.max_tokens == null) {
+                  const defaultedMaxTokens = getAnthropicDefaultMaxTokens(model)
+                  logger.warn(
+                    `anthropic response truncated at the default max_tokens (${defaultedMaxTokens}) for model=${model}; pass maxTokens (or modelOptions.max_tokens) to raise the output ceiling`,
+                    {
+                      source: 'anthropic.processAnthropicStream',
+                      model,
+                      defaultedMaxTokens,
+                    },
+                  )
+                }
                 yield {
                   type: EventType.RUN_ERROR,
                   model,

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

@@ -733,6 +733,61 @@ export const ANTHROPIC_MODELS = [
   CLAUDE_OPUS_4_8_FAST.id,
 ] as const
 
+/**
+ * Fallback `max_tokens` ceiling for a model whose metadata carries no
+ * `max_output_tokens` (e.g. an unrecognized model id). Anthropic's Messages
+ * API *requires* `max_tokens`, so the adapter must always send a value. 64K is
+ * the output ceiling of the current mainstream Claude tier (Sonnet/Haiku 4.5),
+ * so it's a sane default for an unknown — almost certainly modern — model and
+ * avoids silently truncating long generations (issue #849). Recognized models
+ * use their exact `max_output_tokens` from {@link ANTHROPIC_MODEL_MAX_OUTPUT_TOKENS}
+ * (e.g. 128K for Opus), so this fallback only ever applies to ids not in the
+ * map.
+ */
+export const ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS = 64_000
+
+/**
+ * Runtime lookup of each model's maximum output-token ceiling, keyed by model
+ * id. Lets the text adapter default the required `max_tokens` request field to
+ * the model's real ceiling when the caller doesn't specify one, rather than a
+ * low constant that truncates responses mid-stream (issue #849).
+ *
+ * Kept in sync with {@link ANTHROPIC_MODELS} by `scripts/sync-provider-models.ts`
+ * — when that script adds a model it also inserts the model's `max_output_tokens`
+ * here, so a freshly-synced model resolves to its real ceiling rather than the
+ * fallback above.
+ */
+const ANTHROPIC_MODEL_MAX_OUTPUT_TOKENS: Record<string, number> = {
+  [CLAUDE_OPUS_4_6.id]: CLAUDE_OPUS_4_6.max_output_tokens,
+  [CLAUDE_OPUS_4_5.id]: CLAUDE_OPUS_4_5.max_output_tokens,
+  [CLAUDE_SONNET_4_6.id]: CLAUDE_SONNET_4_6.max_output_tokens,
+  [CLAUDE_SONNET_4_5.id]: CLAUDE_SONNET_4_5.max_output_tokens,
+  [CLAUDE_HAIKU_4_5.id]: CLAUDE_HAIKU_4_5.max_output_tokens,
+  [CLAUDE_OPUS_4_1.id]: CLAUDE_OPUS_4_1.max_output_tokens,
+  [CLAUDE_SONNET_4.id]: CLAUDE_SONNET_4.max_output_tokens,
+  [CLAUDE_SONNET_3_7.id]: CLAUDE_SONNET_3_7.max_output_tokens,
+  [CLAUDE_OPUS_4.id]: CLAUDE_OPUS_4.max_output_tokens,
+  [CLAUDE_HAIKU_3_5.id]: CLAUDE_HAIKU_3_5.max_output_tokens,
+  [CLAUDE_HAIKU_3.id]: CLAUDE_HAIKU_3.max_output_tokens,
+  [CLAUDE_OPUS_4_6_FAST.id]: CLAUDE_OPUS_4_6_FAST.max_output_tokens,
+  [CLAUDE_OPUS_4_7.id]: CLAUDE_OPUS_4_7.max_output_tokens,
+  [CLAUDE_OPUS_4_7_FAST.id]: CLAUDE_OPUS_4_7_FAST.max_output_tokens,
+  [CLAUDE_OPUS_4_8.id]: CLAUDE_OPUS_4_8.max_output_tokens,
+  [CLAUDE_OPUS_4_8_FAST.id]: CLAUDE_OPUS_4_8_FAST.max_output_tokens,
+}
+
+/**
+ * Resolve the default `max_tokens` for a model: its known `max_output_tokens`
+ * ceiling, or {@link ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS} for unknown models.
+ * Callers that pass an explicit `max_tokens` bypass this entirely.
+ */
+export function getAnthropicDefaultMaxTokens(model: string): number {
+  return (
+    ANTHROPIC_MODEL_MAX_OUTPUT_TOKENS[model] ??
+    ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+  )
+}
+
 /**
  * Anthropic models that support combining `tools` + JSON-Schema-constrained
  * output in a single streaming Messages request (per issue #605). GA'd

packages/ai-anthropic/tests/anthropic-adapter.test.ts

@@ -444,7 +444,7 @@ describe('Anthropic adapter option mapping', () => {
     expect(payload.top_p).toBe(0.7)
   })
 
-  it('defaults max_tokens to 1024 when not provided via modelOptions', async () => {
+  it("defaults max_tokens to the model's max_output_tokens when not provided via modelOptions (#849)", async () => {
     mocks.betaMessagesCreate.mockResolvedValueOnce(createTextStream('ok'))
 
     const adapter = createAdapter('claude-3-7-sonnet')
@@ -457,7 +457,90 @@ describe('Anthropic adapter option mapping', () => {
     }
 
     const [payload] = mocks.betaMessagesCreate.mock.calls[0]!
-    expect(payload.max_tokens).toBe(1024)
+    // claude-3-7-sonnet's model-meta max_output_tokens is 64_000 — not the old
+    // hard-coded 1024 floor that silently truncated long responses.
+    expect(payload.max_tokens).toBe(64_000)
+  })
+
+  it('warns when the default max_tokens cap truncates the response (#849)', async () => {
+    // Stream that ends with stop_reason: "max_tokens" — the model hit the cap.
+    const truncatedStream = (async function* () {
+      yield {
+        type: 'content_block_start',
+        index: 0,
+        content_block: { type: 'text', text: '' },
+      }
+      yield {
+        type: 'content_block_delta',
+        index: 0,
+        delta: { type: 'text_delta', text: 'partial output' },
+      }
+      yield { type: 'content_block_stop', index: 0 }
+      yield {
+        type: 'message_delta',
+        delta: { stop_reason: 'max_tokens' },
+        usage: { output_tokens: 64_000 },
+      }
+      yield { type: 'message_stop' }
+    })()
+    mocks.betaMessagesCreate.mockResolvedValueOnce(truncatedStream)
+
+    const adapter = createAdapter('claude-3-7-sonnet')
+
+    const logger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    }
+
+    for await (const _ of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Write a long essay' }],
+      debug: { logger, errors: true },
+    })) {
+      // consume stream
+    }
+
+    const truncationWarning = logger.warn.mock.calls.find((call) =>
+      String(call[0]).includes('truncated at the default max_tokens'),
+    )
+    expect(truncationWarning).toBeDefined()
+  })
+
+  it('does not warn about truncation when the caller set max_tokens explicitly (#849)', async () => {
+    const truncatedStream = (async function* () {
+      yield {
+        type: 'message_delta',
+        delta: { stop_reason: 'max_tokens' },
+        usage: { output_tokens: 100 },
+      }
+      yield { type: 'message_stop' }
+    })()
+    mocks.betaMessagesCreate.mockResolvedValueOnce(truncatedStream)
+
+    const adapter = createAdapter('claude-3-7-sonnet')
+
+    const logger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    }
+
+    for await (const _ of chat({
+      adapter,
+      messages: [{ role: 'user', content: 'Hi' }],
+      modelOptions: { max_tokens: 100 } satisfies AnthropicTextProviderOptions,
+      debug: { logger, errors: true },
+    })) {
+      // consume stream
+    }
+
+    const truncationWarning = logger.warn.mock.calls.find((call) =>
+      String(call[0]).includes('truncated at the default max_tokens'),
+    )
+    expect(truncationWarning).toBeUndefined()
   })
 
   it('native combined mode (#605): wires outputSchema into output_format alongside tools on Claude 4.5+', async () => {

packages/ai-anthropic/tests/model-meta.test.ts

@@ -1,4 +1,8 @@
-import { describe, expectTypeOf, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import {
+  ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+  getAnthropicDefaultMaxTokens,
+} from '../src/model-meta'
 import type {
   AnthropicChatModelProviderOptionsByName,
   AnthropicModelInputModalitiesByName,
@@ -780,3 +784,26 @@ describe('Anthropic Model Input Modality Type Assertions', () => {
     })
   })
 })
+
+describe('getAnthropicDefaultMaxTokens (#849)', () => {
+  it("returns the model's max_output_tokens for known models", () => {
+    expect(getAnthropicDefaultMaxTokens('claude-opus-4.8')).toBe(128_000)
+    expect(getAnthropicDefaultMaxTokens('claude-opus-4-6')).toBe(128_000)
+    expect(getAnthropicDefaultMaxTokens('claude-sonnet-4-6')).toBe(64_000)
+    expect(getAnthropicDefaultMaxTokens('claude-3-7-sonnet')).toBe(64_000)
+    expect(getAnthropicDefaultMaxTokens('claude-3-haiku')).toBe(4_000)
+  })
+
+  it('falls back to the safe constant for unknown models', () => {
+    expect(ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS).toBe(64_000)
+    expect(getAnthropicDefaultMaxTokens('some-future-claude-model')).toBe(
+      ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+    )
+  })
+
+  it('never returns the old hard-coded 1024 floor for a known model', () => {
+    expect(getAnthropicDefaultMaxTokens('claude-opus-4.8')).toBeGreaterThan(
+      1024,
+    )
+  })
+})

packages/ai/skills/ai-core/adapter-configuration/SKILL.md

@@ -285,6 +285,16 @@ Per-provider sampling keys (all live inside `modelOptions`):
 some sampling options use provider-native names. Ollama nests all sampling under
 `modelOptions.options`.
 
+> **Anthropic `max_tokens` default:** Anthropic's API _requires_ `max_tokens`,
+> so the adapter always sends one. When you omit `modelOptions.max_tokens`, it
+> defaults to the selected model's full output ceiling (its `max_output_tokens`
+> from model metadata — e.g. 64K for Sonnet, 128K for Opus), not a low constant.
+> `max_tokens` is a ceiling, not a reservation (billing is per token generated),
+> so leaving it unset is the right default for codegen / agentic / long-form
+> output and avoids silent `stop_reason: "max_tokens"` truncation. Set it only to
+> cap output below the model ceiling. Other providers treat token limits as
+> optional and don't apply this flooring.
+
 ### 6. Capability Flag: `supportsCombinedToolsAndSchema`
 
 Adapters can declare an optional capability method:

scripts/sync-provider-models.ts

@@ -43,6 +43,13 @@ interface ProviderConfig {
   providerOptionsTypeName: string
   /** Name of the input modalities type map */
   inputModalitiesTypeName: string
+  /**
+   * Name of the runtime `Record<string, number>` mapping model id →
+   * `max_output_tokens`, if the provider maintains one. Anthropic uses this to
+   * default the required `max_tokens` request field to the model's real ceiling
+   * (issue #849); other providers treat token limits as optional and omit it.
+   */
+  maxOutputTokensMapName?: string
   /** The supports block template (minus input modalities, which come from OpenRouter) */
   referenceSupportsBody: string
   /** Valid input modality types for this provider's ModelMeta interface */
@@ -95,6 +102,7 @@ const PROVIDER_MAP: Record<string, ProviderConfig> = {
     chatArrayName: 'ANTHROPIC_MODELS',
     providerOptionsTypeName: 'AnthropicChatModelProviderOptionsByName',
     inputModalitiesTypeName: 'AnthropicModelInputModalitiesByName',
+    maxOutputTokensMapName: 'ANTHROPIC_MODEL_MAX_OUTPUT_TOKENS',
     validInputModalities: ['text', 'image', 'audio', 'video', 'document'],
     referenceSupportsBody: `    extended_thinking: true,
     priority_tier: true,
@@ -497,6 +505,34 @@ function addToTypeMap(
   return content.replace(pattern, () => `${match[1]}\n${newEntries}${match[2]}`)
 }
 
+/**
+ * Add entries to a runtime object literal like:
+ *   const MAP_NAME: Record<string, number> = {
+ *     ...existing entries...
+ *   }
+ * Used for the Anthropic id → max_output_tokens map (issue #849), which is a
+ * value declaration rather than a `type` alias.
+ */
+function addToObjectMap(
+  content: string,
+  mapName: string,
+  entries: Array<string>,
+): string {
+  // Match: const MAP_NAME: Record<string, number> = { ... \n}
+  const pattern = new RegExp(
+    `(const ${mapName}: Record<string, number> = \\{[\\s\\S]*?)(\\n\\})`,
+  )
+  const match = pattern.exec(content)
+  if (!match) {
+    console.warn(`  Warning: Could not find object map '${mapName}' in file`)
+    return content
+  }
+
+  const newEntries = entries.join('\n')
+  // Use replacer function to prevent $-character interpretation in replacement string
+  return content.replace(pattern, () => `${match[1]}\n${newEntries}${match[2]}`)
+}
+
 // ---------------------------------------------------------------------------
 // Git-based change detection
 // ---------------------------------------------------------------------------
@@ -693,6 +729,28 @@ async function main() {
       )
     }
 
+    // Add to the id → max_output_tokens runtime map (Anthropic only). Only
+    // models whose generated constant actually carries `max_output_tokens`
+    // (i.e. OpenRouter reported a `max_completion_tokens`) get an entry; the
+    // rest correctly fall through to the map's constant default. Keeps the map
+    // in lockstep with the chat-model array so a synced model resolves to its
+    // real ceiling instead of the fallback (issue #849).
+    if (config.maxOutputTokensMapName) {
+      const maxOutputEntries = chatModels
+        .filter(({ model }) => model.top_provider.max_completion_tokens)
+        .map(
+          ({ constName }) =>
+            `  [${constName}${config.arrayRef}]: ${constName}.max_output_tokens,`,
+        )
+      if (maxOutputEntries.length > 0) {
+        content = addToObjectMap(
+          content,
+          config.maxOutputTokensMapName,
+          maxOutputEntries,
+        )
+      }
+    }
+
     // Write the modified file
     await writeFile(config.metaFile, content, 'utf-8')
     console.log(`  Wrote updated file: ${config.metaFile}`)