@anthropic-ai/sdk 0.114.0 → 0.115.0

package/src/lib/BetaMessageStream.ts

@@ -610,6 +610,10 @@ export class BetaMessageStream<ParsedT = null> implements AsyncIterable<BetaMess
           snapshot.usage.iterations = event.usage.iterations;
         }
 
+        if (event.usage.fallback_credit != null) {
+          snapshot.usage.fallback_credit = event.usage.fallback_credit;
+        }
+
         return snapshot;
       case 'content_block_start':
         snapshot.content.push(event.content_block);

package/src/lib/middleware.ts

@@ -10,6 +10,7 @@ import type { AnthropicBeta } from '../resources/beta/beta';
 import type {
   BetaContentBlockParam,
   BetaFallbackBlock,
+  BetaFallbackCreditTokenParam,
   BetaFallbackMessageIterationUsage,
   BetaFallbackParam,
   BetaMessage,
@@ -31,7 +32,7 @@ export { BetaFallbackState } from '../internal/request-options';
 const encoder = new TextEncoder();
 
 /** Betas sent by default; override with {@link BetaRefusalFallbackOptions.betas}. */
-const DEFAULT_BETAS: readonly AnthropicBeta[] = ['fallback-credit-2026-06-01'];
+const DEFAULT_BETAS: readonly AnthropicBeta[] = ['fallback-credit-2026-07-01'];
 
 /**
  * Remove `fallback` blocks replayed in history. They only parse under the
@@ -50,6 +51,42 @@ function stripFallbackBlocks(body: MessageCreateParams): MessageCreateParams {
   return { ...body, messages };
 }
 
+/**
+ * Apply one chain entry to the original request params as a patch: a field
+ * set to a value overrides the original, a field explicitly `null` removes
+ * the field from the retried request, and an absent (or `undefined`) field
+ * keeps the original value. `output_config` patches one level deep — its
+ * subfields follow the same set/`null`/absent rules against the original
+ * `output_config` (created if the entry sets any subfield). Every hop patches
+ * the original params — never a previous hop's patched body — and `body` is
+ * never mutated.
+ */
+function applyFallbackPatch(body: MessageCreateParams, entry: BetaFallbackParam): MessageCreateParams {
+  const patched = { ...body } as Record<string, unknown>;
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === 'output_config' && value != null) {
+      const merged = { ...((patched[key] as Record<string, unknown> | undefined) ?? {}) };
+      for (const [subKey, subValue] of Object.entries(value)) {
+        patchField(merged, subKey, subValue);
+      }
+      patchField(patched, key, Object.keys(merged).length ? merged : null);
+    } else {
+      patchField(patched, key, value);
+    }
+  }
+  return patched as unknown as MessageCreateParams;
+}
+
+/** Set/`null`-unset/absent-keep one field on `target` (mutated). */
+function patchField(target: Record<string, unknown>, key: string, value: unknown): void {
+  if (value === undefined) return;
+  if (value === null) {
+    delete target[key];
+  } else {
+    target[key] = value;
+  }
+}
+
 /** Why {@link BetaRefusalFallbackOptions.onError} fired. */
 export type BetaRefusalFallbackError =
   | {
@@ -83,7 +120,7 @@ export interface BetaRefusalFallbackOptions {
    * Betas added to the `anthropic-beta` header of every `/v1/messages`
    * request this middleware handles — the original request included, since
    * refusals only carry a `fallback_credit_token` when the beta is enabled.
-   * Defaults to `['fallback-credit-2026-06-01']`; pass `[]` to send none.
+   * Defaults to `['fallback-credit-2026-07-01']`; pass `[]` to send none.
    */
   betas?: readonly AnthropicBeta[] | undefined;
 
@@ -100,8 +137,10 @@ export interface BetaRefusalFallbackOptions {
  * Middleware that retries refused `/v1/messages` requests down a fallback chain.
  *
  * Non-streaming: when a response comes back with `stop_reason: 'refusal'`, the
- * request is retried with each entry of `fallbacks` merged over the original
- * params — passing along the refusal's `fallback_credit_token` — until a model
+ * request is retried with each entry of `fallbacks` applied as a patch to the
+ * original params (a set field overrides, an explicit `null` unsets, an absent
+ * field keeps the original value; entries never patch each other's requests)
+ * — passing along the refusal's `fallback_credit_token` — until a model
  * accepts or the chain is exhausted. A message served by a fallback carries a
  * `fallback` content block prepended at each model boundary — the same seam
  * block shape the server-side `fallbacks` param places in `content`, though
@@ -171,7 +210,7 @@ export function betaRefusalFallbackMiddleware(
     if ((ctx.options.body as MessageCreateParams).fallbacks != null) {
       throw new AnthropicError(
         'Sending the `fallbacks:` request param is not supported when using the `betaRefusalFallbackMiddleware`. ' +
-          'You should either remove the middleware and send `fallbacks:` with the `server-side-fallback-2026-06-01` beta header to let the API handle refusal fallbacks, ' +
+          'You should either remove the middleware and send `fallbacks:` with the `server-side-fallback-2026-07-01` beta header to let the API handle refusal fallbacks, ' +
           "or omit the `fallbacks:` param if you'd like `betaRefusalFallbackMiddleware` to handle fallbacks on the client side.",
       );
     }
@@ -208,15 +247,12 @@ export function betaRefusalFallbackMiddleware(
       }
     };
 
+    const initialBody = startIndex === -1 ? body : applyFallbackPatch(body, fallbacks[startIndex]!);
+
     // a non-string body can't be respliced or redeemed against — leave the
     // request untouched (the streaming path stands down on it below too)
     const initialRequest =
-      typeof request.body !== 'string' ?
-        request
-      : {
-          ...request,
-          body: JSON.stringify(startIndex === -1 ? body : { ...body, ...fallbacks[startIndex] }),
-        };
+      typeof request.body !== 'string' ? request : { ...request, body: JSON.stringify(initialBody) };
 
     const response = await next(initialRequest);
     if (!response.ok) {
@@ -248,7 +284,7 @@ export function betaRefusalFallbackMiddleware(
     let res = response;
     // The model the current hop was requested as — the caller's spelling, not
     // the server's `message.model` echo; the seam block's `from` carries it.
-    let requestedModel = (startIndex === -1 ? body : { ...body, ...fallbacks[startIndex] }).model;
+    let requestedModel = initialBody.model;
     const fallbackBlocks: BetaFallbackBlock[] = [];
     while (index < fallbacks.length - 1) {
       const message = await ctx.parse<BetaMessage | null>(res);
@@ -274,10 +310,9 @@ export function betaRefusalFallbackMiddleware(
       res = await next({
         ...request,
         body: JSON.stringify({
-          ...body,
-          ...entry,
+          ...applyFallbackPatch(body, entry),
           ...(message.stop_details?.fallback_credit_token ?
-            { fallback_credit_token: message.stop_details.fallback_credit_token }
+            { fallback_credit_token: creditTokenParam(message.stop_details.fallback_credit_token) }
           : undefined),
         }),
       });
@@ -759,6 +794,16 @@ class BlockTracker {
 
 // --- fallback request construction (appended-assistant continuation) -------
 
+/**
+ * Object form of the redeemed credit token. `best_effort` keeps the retry
+ * served if the token layer rejects it — the retry then proceeds at normal
+ * price and the outcome lands on `usage.fallback_credit` — where the
+ * bare-string (`strict`) form would 400 the whole request.
+ */
+function creditTokenParam(token: string): BetaFallbackCreditTokenParam {
+  return { token, mode: 'best_effort' };
+}
+
 function buildFallbackRequest(
   orig: APIRequest,
   {
@@ -775,7 +820,7 @@ function buildFallbackRequest(
   const body = JSON.parse(orig.body as string);
 
   body.model = model;
-  body.fallback_credit_token = creditToken;
+  body.fallback_credit_token = creditTokenParam(creditToken);
 
   // Append the continuation (decided by the chain loop) as a trailing
   // assistant turn; everything else must stay identical to the refused

package/src/lib/tools/BetaToolRunner.ts

@@ -2,7 +2,18 @@ import { BetaRunnableTool } from './BetaRunnableTool';
 import { ToolError } from './ToolError';
 import { Anthropic } from '../..';
 import { AnthropicError } from '../../core/error';
-import { BetaMessage, BetaMessageParam, BetaToolUnion, MessageCreateParams } from '../../resources/beta';
+import {
+  BetaContentBlockParam,
+  BetaMessage,
+  BetaMessageParam,
+  BetaRequestToolAdditionBlock,
+  BetaRequestToolRemovalBlock,
+  BetaToolChangeMCPToolReference,
+  BetaToolChangeMCPToolsetReference,
+  BetaToolChangeToolReference,
+  BetaToolUnion,
+  MessageCreateParams,
+} from '../../resources/beta';
 import { BetaMessageStream } from '../BetaMessageStream';
 import { RequestOptions } from '../../internal/request-options';
 import { buildHeaders } from '../../internal/headers';
@@ -467,16 +478,14 @@ async function generateToolResponse(
     return null;
   }
 
+  const available = availableToolNames(params);
   const toolResults = await Promise.all(
     toolUseBlocks.map(async (toolUse) => {
       const tool = params.tools.find((t) => ('name' in t ? t.name : t.mcp_server_name) === toolUse.name);
-      if (!tool || !('run' in tool)) {
-        return {
-          type: 'tool_result' as const,
-          tool_use_id: toolUse.id,
-          content: `Error: Tool '${toolUse.name}' not found`,
-          is_error: true,
-        };
+      // A `tool_removal` is only a hint to the model, which may still emit a tool_use for a
+      // withdrawn tool — treat those exactly like a tool that was never defined.
+      if (!tool || !('run' in tool) || !available.has(toolUse.name)) {
+        return toolNotFoundResult(toolUse);
       }
 
       try {
@@ -515,6 +524,90 @@ async function generateToolResponse(
   };
 }
 
+function toolNotFoundResult(toolUse: { id: string; name: string }) {
+  return {
+    type: 'tool_result' as const,
+    tool_use_id: toolUse.id,
+    content: `Error: Tool '${toolUse.name}' not found`,
+    is_error: true,
+  };
+}
+
+/**
+ * Computes the names of locally runnable tools that are still available for the assistant
+ * turn being answered, by folding `tool_removal` / `tool_addition` blocks from the
+ * `role: "system"` messages over the runnable tools. The assistant turn being answered is
+ * terminal-or-absent and only `system` messages are inspected, so folding the whole current
+ * history is exactly folding the messages preceding that turn — call this before appending
+ * anything after it. MCP references are ignored — those tools are executed server-side and
+ * never dispatched by this runner.
+ */
+function availableToolNames(params: BetaToolRunnerParams): Set<string> {
+  const available = new Set<string>();
+  for (const tool of params.tools) {
+    if ('run' in tool) {
+      available.add(tool.name);
+    }
+  }
+
+  for (const message of params.messages) {
+    if (message.role !== 'system' || typeof message.content === 'string') {
+      continue;
+    }
+    for (const block of message.content) {
+      applyToolChange(block, available);
+    }
+  }
+  return available;
+}
+
+function applyToolChange(block: BetaContentBlockParam, available: Set<string>): void {
+  switch (block.type) {
+    case 'tool_removal':
+    case 'tool_addition':
+      applyToolReference(block, available);
+      break;
+    case 'mid_conv_system':
+      // A `mid_conv_system` block's content is limited by the API schema to
+      // text / tool_addition / tool_removal, so we walk exactly one level — no recursion.
+      for (const inner of block.content) {
+        if (inner.type === 'tool_removal' || inner.type === 'tool_addition') {
+          applyToolReference(inner, available);
+        }
+      }
+      break;
+    default:
+      // Other and unknown/newer block types leave the set untouched (forward compatibility).
+      break;
+  }
+}
+
+function applyToolReference(
+  block: BetaRequestToolAdditionBlock | BetaRequestToolRemovalBlock,
+  available: Set<string>,
+): void {
+  const name = referencedToolName(block.tool);
+  if (name === undefined) return;
+  if (block.type === 'tool_removal') {
+    available.delete(name);
+  } else {
+    available.add(name);
+  }
+}
+
+function referencedToolName(
+  ref: BetaToolChangeToolReference | BetaToolChangeMCPToolReference | BetaToolChangeMCPToolsetReference,
+): string | undefined {
+  switch (ref.type) {
+    case 'tool_reference':
+      return ref.name;
+    default:
+      // mcp_tool_reference / mcp_toolset_reference run server-side; unknown reference
+      // types are ignored rather than rejected.
+      return undefined;
+  }
+}
+
 // vendored from typefest just to make things look a bit nicer on hover
 type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
 

package/src/resources/beta/agents/agents.ts

@@ -707,6 +707,7 @@ export interface BetaManagedAgentsMCPToolsetParams {
 export type BetaManagedAgentsModel =
   | 'claude-sonnet-5'
   | 'claude-fable-5'
+  | 'claude-opus-5'
   | 'claude-opus-4-8'
   | 'claude-opus-4-7'
   | 'claude-opus-4-6'

package/src/resources/beta/beta.ts

@@ -363,11 +363,16 @@ import {
   BetaEncryptedCodeExecutionResultBlockParam,
   BetaFallbackBlock,
   BetaFallbackBlockParam,
+  BetaFallbackCreditNotApplied,
+  BetaFallbackCreditRedeemed,
+  BetaFallbackCreditTokenParam,
+  BetaFallbackCreditUsage,
   BetaFallbackInfo,
   BetaFallbackInfoParam,
   BetaFallbackMessageIterationUsage,
   BetaFallbackParam,
   BetaFallbackRefusalTrigger,
+  BetaFallbacksParam,
   BetaFileDocumentSource,
   BetaFileImageSource,
   BetaImageBlockParam,
@@ -412,6 +417,8 @@ import {
   BetaRequestMCPServerToolConfiguration,
   BetaRequestMCPServerURLDefinition,
   BetaRequestMCPToolResultBlockParam,
+  BetaRequestToolAdditionBlock,
+  BetaRequestToolRemovalBlock,
   BetaSearchResultBlockParam,
   BetaServerToolCaller,
   BetaServerToolCaller20260120,
@@ -449,6 +456,9 @@ import {
   BetaTool,
   BetaToolBash20241022,
   BetaToolBash20250124,
+  BetaToolChangeMCPToolReference,
+  BetaToolChangeMCPToolsetReference,
+  BetaToolChangeToolReference,
   BetaToolChoice,
   BetaToolChoiceAny,
   BetaToolChoiceAuto,
@@ -633,7 +643,9 @@ export type AnthropicBeta =
   | 'dreaming-2026-04-21'
   | 'thinking-token-count-2026-05-13'
   | 'server-side-fallback-2026-06-01'
+  | 'server-side-fallback-2026-07-01'
   | 'fallback-credit-2026-06-01'
+  | 'fallback-credit-2026-07-01'
   | 'agent-memory-2026-07-22';
 
 export interface BetaAPIError {
@@ -842,11 +854,16 @@ export declare namespace Beta {
     type BetaEncryptedCodeExecutionResultBlockParam as BetaEncryptedCodeExecutionResultBlockParam,
     type BetaFallbackBlock as BetaFallbackBlock,
     type BetaFallbackBlockParam as BetaFallbackBlockParam,
+    type BetaFallbackCreditNotApplied as BetaFallbackCreditNotApplied,
+    type BetaFallbackCreditRedeemed as BetaFallbackCreditRedeemed,
+    type BetaFallbackCreditTokenParam as BetaFallbackCreditTokenParam,
+    type BetaFallbackCreditUsage as BetaFallbackCreditUsage,
     type BetaFallbackInfo as BetaFallbackInfo,
     type BetaFallbackInfoParam as BetaFallbackInfoParam,
     type BetaFallbackMessageIterationUsage as BetaFallbackMessageIterationUsage,
     type BetaFallbackParam as BetaFallbackParam,
     type BetaFallbackRefusalTrigger as BetaFallbackRefusalTrigger,
+    type BetaFallbacksParam as BetaFallbacksParam,
     type BetaFileDocumentSource as BetaFileDocumentSource,
     type BetaFileImageSource as BetaFileImageSource,
     type BetaImageBlockParam as BetaImageBlockParam,
@@ -893,6 +910,8 @@ export declare namespace Beta {
     type BetaRequestMCPServerToolConfiguration as BetaRequestMCPServerToolConfiguration,
     type BetaRequestMCPServerURLDefinition as BetaRequestMCPServerURLDefinition,
     type BetaRequestMCPToolResultBlockParam as BetaRequestMCPToolResultBlockParam,
+    type BetaRequestToolAdditionBlock as BetaRequestToolAdditionBlock,
+    type BetaRequestToolRemovalBlock as BetaRequestToolRemovalBlock,
     type BetaSearchResultBlockParam as BetaSearchResultBlockParam,
     type BetaServerToolCaller as BetaServerToolCaller,
     type BetaServerToolCaller20260120 as BetaServerToolCaller20260120,
@@ -930,6 +949,9 @@ export declare namespace Beta {
     type BetaTool as BetaTool,
     type BetaToolBash20241022 as BetaToolBash20241022,
     type BetaToolBash20250124 as BetaToolBash20250124,
+    type BetaToolChangeMCPToolReference as BetaToolChangeMCPToolReference,
+    type BetaToolChangeMCPToolsetReference as BetaToolChangeMCPToolsetReference,
+    type BetaToolChangeToolReference as BetaToolChangeToolReference,
     type BetaToolChoice as BetaToolChoice,
     type BetaToolChoiceAny as BetaToolChoiceAny,
     type BetaToolChoiceAuto as BetaToolChoiceAuto,

package/src/resources/beta/index.ts

@@ -292,11 +292,16 @@ export {
   type BetaEncryptedCodeExecutionResultBlockParam,
   type BetaFallbackBlock,
   type BetaFallbackBlockParam,
+  type BetaFallbackCreditNotApplied,
+  type BetaFallbackCreditRedeemed,
+  type BetaFallbackCreditTokenParam,
+  type BetaFallbackCreditUsage,
   type BetaFallbackInfo,
   type BetaFallbackInfoParam,
   type BetaFallbackMessageIterationUsage,
   type BetaFallbackParam,
   type BetaFallbackRefusalTrigger,
+  type BetaFallbacksParam,
   type BetaFileDocumentSource,
   type BetaFileImageSource,
   type BetaImageBlockParam,
@@ -344,6 +349,8 @@ export {
   type BetaRequestMCPServerToolConfiguration,
   type BetaRequestMCPServerURLDefinition,
   type BetaRequestMCPToolResultBlockParam,
+  type BetaRequestToolAdditionBlock,
+  type BetaRequestToolRemovalBlock,
   type BetaSearchResultBlockParam,
   type BetaServerToolCaller,
   type BetaServerToolCaller20260120,
@@ -381,6 +388,9 @@ export {
   type BetaTool,
   type BetaToolBash20241022,
   type BetaToolBash20250124,
+  type BetaToolChangeMCPToolReference,
+  type BetaToolChangeMCPToolsetReference,
+  type BetaToolChangeToolReference,
   type BetaToolChoice,
   type BetaToolChoiceAny,
   type BetaToolChoiceAuto,

package/src/resources/beta/messages/batches.ts

@@ -607,14 +607,15 @@ export namespace BatchCreateParams {
        * When the appended-assistant form is used on a model that otherwise disallows
        * assistant-turn prefill, this token also authorizes that one prefill.
        */
-      fallback_credit_token?: string | null;
+      fallback_credit_token?: string | BetaMessagesAPI.BetaFallbackCreditTokenParam | null;
 
       /**
        * Opt-in server-side retry on one or more substitute models when the requested
        * model declines for policy reasons. Tried in order: if the first entry also
-       * declines, the second is tried, and so on.
+       * declines, the second is tried, and so on. The string "default" requests the
+       * requested model's server-defined default fallback configuration.
        */
-      fallbacks?: Array<BetaMessagesAPI.BetaFallbackParam> | null;
+      fallbacks?: BetaMessagesAPI.BetaFallbacksParam | null;
 
       /**
        * Specifies the geographic region for inference processing. If not specified, the

package/src/resources/beta/messages/index.ts

@@ -106,11 +106,16 @@ export {
   type BetaEncryptedCodeExecutionResultBlockParam,
   type BetaFallbackBlock,
   type BetaFallbackBlockParam,
+  type BetaFallbackCreditNotApplied,
+  type BetaFallbackCreditRedeemed,
+  type BetaFallbackCreditTokenParam,
+  type BetaFallbackCreditUsage,
   type BetaFallbackInfo,
   type BetaFallbackInfoParam,
   type BetaFallbackMessageIterationUsage,
   type BetaFallbackParam,
   type BetaFallbackRefusalTrigger,
+  type BetaFallbacksParam,
   type BetaFileDocumentSource,
   type BetaFileImageSource,
   type BetaImageBlockParam,
@@ -156,6 +161,8 @@ export {
   type BetaRequestMCPServerToolConfiguration,
   type BetaRequestMCPServerURLDefinition,
   type BetaRequestMCPToolResultBlockParam,
+  type BetaRequestToolAdditionBlock,
+  type BetaRequestToolRemovalBlock,
   type BetaSearchResultBlockParam,
   type BetaServerToolCaller,
   type BetaServerToolCaller20260120,
@@ -193,6 +200,9 @@ export {
   type BetaTool,
   type BetaToolBash20241022,
   type BetaToolBash20250124,
+  type BetaToolChangeMCPToolReference,
+  type BetaToolChangeMCPToolsetReference,
+  type BetaToolChangeToolReference,
   type BetaToolChoice,
   type BetaToolChoiceAny,
   type BetaToolChoiceAuto,