anthropic 1.58.0 → 1.59.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48ab35bd8cf4f04042fe7c27121f1735ac8cad21809ced2a9dd9cafd220e5f6c
-  data.tar.gz: e1fe6ba52bb7ebf74ca4c76c7aaec7a485ee44b9453f7978a44fe1bee8dc188d
+  metadata.gz: a5c7920c024b325266d16d26526490511c33ee3de9136b7a0314a6d7c28f8c0a
+  data.tar.gz: 21354f0f03146858812a863149f1c02b7f961cdbd3d7726b166530d628d340eb
 SHA512:
-  metadata.gz: c7f72255a73f80441ee63badd6b98f72f6607b8a56e3c3fdfb6d33fa65938d8917702988b22c707c190952458087e2e24710b8b6f7867eb68c045357fd6aaf9e
-  data.tar.gz: 6d7b44b71542c194de65cdffdd164ad1e4d25d4caf668b3f0b0f90977ae8bdeb7a1bae803dbaf698aeb1ac583c723de2ae1a0a517e8214a659e9535bc9b4eea1
+  metadata.gz: be751a0e2ddaf99238b87eefb9d67fb7479542f624d42490dc009eb1b1fcdd92159bea36526d41ab07d26687ab943911b94e27941b809f6322478ffaaa0baff2
+  data.tar.gz: da3afb6cf93ae7f9a4ab4fe2bca496f80eca4222ab80638677bca0eebd6cc9c0e556f980d2214a112aec585349193b8fcf73dde751b8a087c0da56a65647fd7f

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.59.0 (2026-07-24)
+
+Full Changelog: [v1.58.0...v1.59.0](https://github.com/anthropics/anthropic-sdk-ruby/compare/v1.58.0...v1.59.0)
+
+### Features
+
+* **api:** add claude-opus-5 model ([56d4632](https://github.com/anthropics/anthropic-sdk-ruby/commit/56d46324125672b08af378289727211500c73ae0))
+* **api:** add tool addition/removal blocks and tool_change events ([56d4632](https://github.com/anthropics/anthropic-sdk-ruby/commit/56d46324125672b08af378289727211500c73ae0))
+* **api:** expand client-side fallback credit token types and add server-side fallbacks default option ([56d4632](https://github.com/anthropics/anthropic-sdk-ruby/commit/56d46324125672b08af378289727211500c73ae0))
+
+
+### Chores
+
+* **internal:** codegen related update ([4db7e95](https://github.com/anthropics/anthropic-sdk-ruby/commit/4db7e9578d2919891461cfca07303789a966d4d8))
+
 ## 1.58.0 (2026-07-23)
 
 Full Changelog: [v1.57.0...v1.58.0](https://github.com/anthropics/anthropic-sdk-ruby/compare/v1.57.0...v1.58.0)

data/README.md

@@ -15,7 +15,7 @@ Add to your application's Gemfile:
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "anthropic", "~> 1.58.0"
+gem "anthropic", "~> 1.59.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/anthropic/helpers/messages.rb

@@ -40,7 +40,7 @@ module Anthropic
               case tool
               # BaseTool whose class declares an explicit `tool_name` (e.g. MCP-built tools):
               in Anthropic::Helpers::Tools::BaseTool if tool.class.tool_name
-                name = tool.class.tool_name
+                name = tool_api_name(tool)
                 description = tool.class.doc_string
                 tools.store(name, tool)
                 input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(tool)
@@ -51,8 +51,8 @@ module Anthropic
                 result
               # Direct tool class:
               in Anthropic::Helpers::InputSchema::JsonSchemaConverter
-                classname = tool.is_a?(Anthropic::Helpers::Tools::BaseTool) ? tool.class.name : tool.name
-                name = model_name(classname)
+                name =
+                  tool.is_a?(Anthropic::Helpers::Tools::BaseTool) ? tool_api_name(tool) : model_name(tool.name)
 
                 description =
                   case tool
@@ -206,6 +206,15 @@ module Anthropic
           data[:betas] = data[:betas].to_a.dup.push("structured-outputs-2025-12-15").uniq
         end
 
+        # @api private
+        #
+        # The `name` a runnable tool is serialized under in `tools[]`.
+        #
+        # @param tool [Anthropic::Helpers::Tools::BaseTool]
+        #
+        # @return [String]
+        def tool_api_name(tool) = tool.class.tool_name || model_name(tool.class.name)
+
         # @api private
         #
         # @param classname [String]

data/lib/anthropic/helpers/refusal_fallback.rb

@@ -22,9 +22,11 @@ module Anthropic
   # 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 accepts or the chain is exhausted. A message served by a
+  # the request is retried with each entry of `fallbacks` applied as a patch
+  # against the original params (a set field overrides, an explicit `nil`
+  # unsets, an absent field keeps the original value) — 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; an exhausted chain surfaces the final refusal verbatim.
   #
@@ -39,8 +41,11 @@ module Anthropic
   # path: the credit token is redeemable only against the refused request's
   # body, so the other per-entry overrides would be rejected.
   #
-  # The fallback-credit beta the credit tokens require is sent by default on
-  # every request the middleware handles; the `betas:` option controls this.
+  # Credit tokens are sent in the object form with `mode: :best_effort`, so a
+  # failing redemption never rejects the retry — it proceeds at normal price
+  # and the outcome is reported on `usage.fallback_credit`. The fallback-credit
+  # beta this requires is sent by default on every request the middleware
+  # handles; the `betas:` option controls this.
   #
   # To keep later requests on the model that accepted, pass a
   # {BetaFallbackState} via the `fallback_state` request option; requests
@@ -57,17 +62,25 @@ module Anthropic
     include Anthropic::Middleware
 
     # Betas sent by default; override with the `betas:` option.
-    DEFAULT_BETAS = ["fallback-credit-2026-06-01"].freeze
+    DEFAULT_BETAS = ["fallback-credit-2026-07-01"].freeze
 
     # @param fallbacks [Array<Hash, Anthropic::Models::Beta::BetaFallbackParam>]
     #   the fallback chain, tried in order. Each entry must carry `model:`; on
     #   the non-streaming path the remaining keys (`max_tokens:`, `thinking:`,
-    #   …) are merged over the original request body for that hop.
+    #   …) patch the original request body for that hop — a value overrides
+    #   the param, an explicit `nil` unsets it, an absent key keeps the
+    #   original value.
     # @param betas [Array<String>] betas added to the `anthropic-beta` header
     #   of every `/v1/messages` request this middleware handles. Defaults to
-    #   `["fallback-credit-2026-06-01"]`; pass `[]` to send none.
+    #   `["fallback-credit-2026-07-01"]`; pass `[]` to send none.
     def initialize(fallbacks, betas: DEFAULT_BETAS)
-      @fallbacks = fallbacks.map { _1.respond_to?(:to_h) ? _1.to_h : _1 }.freeze
+      # Entry keys are symbolized because they patch the symbol-keyed request
+      # body; a String key would never match, so its override/unset would
+      # silently miss.
+      @fallbacks = fallbacks.map do |entry|
+        entry = entry.to_h if entry.respond_to?(:to_h)
+        entry.is_a?(Hash) ? entry.transform_keys(&:to_sym) : entry
+      end.freeze
       @betas = betas.freeze
       @warned_missing_state = false
     end
@@ -82,7 +95,7 @@ module Anthropic
         raise Anthropic::Errors::Error,
               "Sending the `fallbacks:` request param is not supported when using " \
               "`BetaRefusalFallbackMiddleware`. Either remove the middleware and send " \
-              "`fallbacks:` with the `server-side-fallback-2026-06-01` beta header to " \
+              "`fallbacks:` with the `server-side-fallback-2026-07-01` beta header to " \
               "let the API handle refusal fallbacks, or omit `fallbacks:` to let the " \
               "middleware handle them on the client side."
       end
@@ -122,7 +135,7 @@ module Anthropic
           # for the spliced hops.
           body.merge(model: @fallbacks.fetch(start_index).fetch(:model))
         else
-          body.merge(@fallbacks.fetch(start_index))
+          apply_fallback(body, @fallbacks.fetch(start_index))
         end
       res = nxt.call(req.with(body: initial_body))
       return res unless res.status < 300
@@ -138,6 +151,54 @@ module Anthropic
 
     private
 
+    # Apply one fallback entry as a patch against the original request body:
+    # a key set to a value overrides that param, a key explicitly set to `nil`
+    # unsets it (the hop request omits the key rather than sending `null`),
+    # and an absent key leaves the original value. `output_config` patches
+    # one level deep — its subfields override/unset/keep individually against
+    # the original `output_config`. Entries always patch the original body,
+    # never an earlier hop's patched body, so overrides can't compound across
+    # hops.
+    #
+    # @param body [Hash{Symbol=>Object}]
+    # @param entry [Hash{Symbol=>Object}]
+    # @return [Hash{Symbol=>Object}]
+    def apply_fallback(body, entry)
+      patched = patch(body, entry)
+      override = entry[:output_config]
+      return patched if override.nil?
+
+      merged = patch(hash_of(body[:output_config]), hash_of(override))
+      merged.empty? ? patched.except(:output_config) : patched.merge(output_config: merged)
+    end
+
+    # @param base [Hash{Symbol=>Object}]
+    # @param overrides [Hash{Symbol=>Object}] a value sets the key, an
+    #   explicit `nil` deletes it, an absent key keeps `base`'s value
+    # @return [Hash{Symbol=>Object}]
+    def patch(base, overrides)
+      overrides.each_with_object(base.dup) do |(key, value), out|
+        value.nil? ? out.delete(key) : out[key] = value
+      end
+    end
+
+    # Normalize a nested config to a symbol-keyed hash of API field names,
+    # preserving keys that were explicitly set to `nil`. A typed model is
+    # dumped (raw `to_h` uses internal names, e.g. `format_` for `format`).
+    #
+    # @param value [Hash, Anthropic::Internal::Type::BaseModel, nil]
+    # @return [Hash{Symbol=>Object}]
+    def hash_of(value)
+      case value
+      when Anthropic::Internal::Type::BaseModel
+        Anthropic::Internal::Type::Converter.dump(value.class, value)
+      when Hash
+        value.transform_keys(&:to_sym)
+      else
+        {}
+      end
+    end
+
     # @return [Boolean] whether `req` is a `client.beta.messages` create call
     #   with a `Hash` body and a non-empty fallback chain.
     def applies?(req)
@@ -189,6 +250,16 @@ module Anthropic
       body.merge(messages: messages)
     end
 
+    # The object form of `fallback_credit_token` with `best_effort` redemption:
+    # a token-layer failure serves the retry at normal price instead of
+    # rejecting it, so a stale or already-spent credit can't fail the fallback.
+    #
+    # @param token [String]
+    # @return [Hash{Symbol=>Object}] shape of {Anthropic::Models::Beta::BetaFallbackCreditTokenParam}
+    def credit_token_param(token)
+      {token: token, mode: Anthropic::Models::Beta::BetaFallbackCreditTokenParam::Mode::BEST_EFFORT}
+    end
+
     # --- non-streaming ------------------------------------------------------
 
     # @param req [Anthropic::APIRequest]
@@ -212,8 +283,8 @@ module Anthropic
 
         index += 1
         entry = @fallbacks.fetch(index)
-        hop_body = body.merge(entry)
-        hop_body = hop_body.merge(fallback_credit_token: token) if token
+        hop_body = apply_fallback(body, entry)
+        hop_body = hop_body.merge(fallback_credit_token: credit_token_param(token)) if token
 
         begin
           hop_res = nxt.call(req.with(body: hop_body))
@@ -381,7 +452,7 @@ module Anthropic
     def issue_hop(req, nxt, body, model, token, base, partial)
       continuation = base + partial
       2.times do |attempt|
-        hop_body = body.merge(model: model, fallback_credit_token: token)
+        hop_body = body.merge(model: model, fallback_credit_token: credit_token_param(token))
         unless continuation.empty?
           hop_body = hop_body.merge(
             messages: body.fetch(:messages) + [{role: :assistant, content: continuation}]

data/lib/anthropic/helpers/streaming/message_stream.rb

@@ -177,8 +177,13 @@ module Anthropic
               current_snapshot.usage.server_tool_use = event.usage.server_tool_use
             end
 
-            if event.is_a?(Anthropic::Models::BetaRawMessageDeltaEvent) && !event.usage.iterations.nil?
-              current_snapshot.usage.iterations = event.usage.iterations
+            if event.is_a?(Anthropic::Models::BetaRawMessageDeltaEvent)
+              unless event.usage.iterations.nil?
+                current_snapshot.usage.iterations = event.usage.iterations
+              end
+              unless event.usage.fallback_credit.nil?
+                current_snapshot.usage.fallback_credit = event.usage.fallback_credit
+              end
             end
           else
           end

data/lib/anthropic/helpers/tools/runner.rb

@@ -92,6 +92,11 @@ module Anthropic
             next unless current_messages.equal?(messages)
             break if compacted
 
+            # A `tool_removal` block only hints the model, so a call to a withdrawn tool can still
+            # arrive; a name missing from this set routes down the same "not found" path as an
+            # undeclared tool.
+            available = available_tool_names(tools, messages)
+
             mapped =
               response
               .content
@@ -99,7 +104,8 @@ module Anthropic
               .grep(Anthropic::Beta::BetaToolUseBlock)
               .map do |tool_use|
                 resp = {type: :tool_result, tool_use_id: tool_use.id}
-                if (tool = tools.find { _1.class.model === tool_use.parsed })
+                if available.include?(tool_use.name) &&
+                   (tool = tools.find { _1.class.model === tool_use.parsed })
                   begin
                     raw = tool.call(tool_use.parsed)
                     is_error = false
@@ -142,6 +148,97 @@ module Anthropic
           # rubocop:enable Metrics/BlockLength
         end
 
+        # @api private
+        #
+        # Replays `tool_removal` / `tool_addition` blocks from `role: :system` messages to
+        # find which tool names are still offered to the model. MCP references are
+        # server-executed and never dispatched here, so they are ignored.
+        #
+        # @param tools [Array<Anthropic::Helpers::Tools::BaseTool>]
+        #
+        # @param messages [Array<Anthropic::Beta::BetaMessageParam, Hash{Symbol=>Object}>]
+        #
+        # @return [Set<String>]
+        private def available_tool_names(tools, messages)
+          available = Set.new(tools.map { Anthropic::Helpers::Messages.tool_api_name(_1) })
+          messages.each do |message|
+            next unless read_field(message, :role)&.to_sym == :system
+
+            Array(read_field(message, :content)).each { apply_tool_change(_1, available) }
+          end
+          available
+        end
+
+        # @api private
+        #
+        # @param block [Anthropic::Beta::BetaContentBlockParam, Hash{Symbol=>Object}]
+        #
+        # @param available [Set<String>]
+        private def apply_tool_change(block, available)
+          case read_field(block, :type)&.to_sym
+          in :tool_removal | :tool_addition
+            apply_tool_delta(block, available)
+          in :mid_conv_system
+            # `mid_conv_system` content is limited by the API schema to text / tool_addition /
+            # tool_removal blocks, so exactly one level is walked; anything else inside is a no-op.
+            Array(read_field(block, :content)).each { apply_tool_delta(_1, available) }
+          else
+            nil # other and unknown block types leave the set untouched (forward compatibility)
+          end
+        end
+
+        # @api private
+        #
+        # @param block [Anthropic::Beta::BetaContentBlockParam, Hash{Symbol=>Object}]
+        #
+        # @param available [Set<String>]
+        private def apply_tool_delta(block, available)
+          case read_field(block, :type)&.to_sym
+          in :tool_removal
+            name = referenced_tool_name(read_field(block, :tool))
+            available.delete(name) unless name.nil?
+          in :tool_addition
+            name = referenced_tool_name(read_field(block, :tool))
+            available.add(name) unless name.nil?
+          else
+            nil # non tool_removal / tool_addition blocks leave the set untouched
+          end
+        end
+
+        # @api private
+        #
+        # @param ref [Anthropic::Beta::BetaToolChangeToolReference, Hash{Symbol=>Object}, nil]
+        #
+        # @return [String, nil]
+        private def referenced_tool_name(ref)
+          case read_field(ref, :type)&.to_sym
+          in :tool_reference
+            read_field(ref, :name).to_s
+          else
+            nil # `mcp_*` references run server-side; unknown types ignored (forward compatibility)
+          end
+        end
+
+        # @api private
+        #
+        # Reads a field off either a plain hash (symbol or string keys) or a typed model.
+        #
+        # @param obj [Object]
+        #
+        # @param key [Symbol]
+        #
+        # @return [Object, nil]
+        private def read_field(obj, key)
+          case obj
+          in Hash
+            obj.fetch(key) { obj[key.to_s] }
+          in Anthropic::Internal::Type::BaseModel
+            obj.public_send(key) if obj.respond_to?(key)
+          else
+            nil
+          end
+        end
+
         # Check token usage and compact messages if threshold exceeded
         #
         # @return [Boolean] true if compaction occurred, false otherwise

data/lib/anthropic/internal/type/converter.rb

@@ -53,6 +53,8 @@ module Anthropic
           in Anthropic::FilePart
             state[:can_retry] = false if value.content.is_a?(IO)
             value
+          in Time
+            value.iso8601
           else
             value
           end

data/lib/anthropic/models/anthropic_beta.rb

@@ -63,8 +63,12 @@ module Anthropic
 
       variant const: -> { Anthropic::Models::AnthropicBeta::SERVER_SIDE_FALLBACK_2026_06_01 }
 
+      variant const: -> { Anthropic::Models::AnthropicBeta::SERVER_SIDE_FALLBACK_2026_07_01 }
+
       variant const: -> { Anthropic::Models::AnthropicBeta::FALLBACK_CREDIT_2026_06_01 }
 
+      variant const: -> { Anthropic::Models::AnthropicBeta::FALLBACK_CREDIT_2026_07_01 }
+
       variant const: -> { Anthropic::Models::AnthropicBeta::AGENT_MEMORY_2026_07_22 }
 
       # @!method self.variants
@@ -104,7 +108,9 @@ module Anthropic
       DREAMING_2026_04_21 = :"dreaming-2026-04-21"
       THINKING_TOKEN_COUNT_2026_05_13 = :"thinking-token-count-2026-05-13"
       SERVER_SIDE_FALLBACK_2026_06_01 = :"server-side-fallback-2026-06-01"
+      SERVER_SIDE_FALLBACK_2026_07_01 = :"server-side-fallback-2026-07-01"
       FALLBACK_CREDIT_2026_06_01 = :"fallback-credit-2026-06-01"
+      FALLBACK_CREDIT_2026_07_01 = :"fallback-credit-2026-07-01"
       AGENT_MEMORY_2026_07_22 = :"agent-memory-2026-07-22"
 
       # @!endgroup

data/lib/anthropic/models/beta/beta_content_block_param.rb

@@ -74,6 +74,20 @@ module Anthropic
         # point in the conversation, rather than only via the top-level `system` parameter.
         variant :mid_conv_system, -> { Anthropic::Beta::BetaMidConversationSystemBlockParam }
 
+        # Mid-conversation directive to surface a declared tool.
+        #
+        # ``tool`` references a tool (or MCP toolset) by name from the request's
+        # ``tools``; it is offered to the model from this point in the
+        # conversation onward.
+        variant :tool_addition, -> { Anthropic::Beta::BetaRequestToolAdditionBlock }
+
+        # Mid-conversation directive to withdraw a tool.
+        #
+        # ``tool`` references a tool (or MCP toolset) by name from the request's
+        # ``tools``; it is no longer offered to the model from this point in the
+        # conversation onward.
+        variant :tool_removal, -> { Anthropic::Beta::BetaRequestToolRemovalBlock }
+
         # A `fallback` block echoed back from a prior response.
         #
         # Accepted in `messages[].content` and not rendered into the prompt; not
@@ -90,7 +104,7 @@ module Anthropic
         variant :fallback, -> { Anthropic::Beta::BetaFallbackBlockParam }
 
         # @!method self.variants
-        #   @return [Array(Anthropic::Models::Beta::BetaTextBlockParam, Anthropic::Models::Beta::BetaImageBlockParam, Anthropic::Models::Beta::BetaRequestDocumentBlock, Anthropic::Models::Beta::BetaSearchResultBlockParam, Anthropic::Models::Beta::BetaThinkingBlockParam, Anthropic::Models::Beta::BetaRedactedThinkingBlockParam, Anthropic::Models::Beta::BetaToolUseBlockParam, Anthropic::Models::Beta::BetaToolResultBlockParam, Anthropic::Models::Beta::BetaServerToolUseBlockParam, Anthropic::Models::Beta::BetaWebSearchToolResultBlockParam, Anthropic::Models::Beta::BetaWebFetchToolResultBlockParam, Anthropic::Models::Beta::BetaAdvisorToolResultBlockParam, Anthropic::Models::Beta::BetaCodeExecutionToolResultBlockParam, Anthropic::Models::Beta::BetaBashCodeExecutionToolResultBlockParam, Anthropic::Models::Beta::BetaTextEditorCodeExecutionToolResultBlockParam, Anthropic::Models::Beta::BetaToolSearchToolResultBlockParam, Anthropic::Models::Beta::BetaMCPToolUseBlockParam, Anthropic::Models::Beta::BetaRequestMCPToolResultBlockParam, Anthropic::Models::Beta::BetaContainerUploadBlockParam, Anthropic::Models::Beta::BetaCompactionBlockParam, Anthropic::Models::Beta::BetaMidConversationSystemBlockParam, Anthropic::Models::Beta::BetaFallbackBlockParam)]
+        #   @return [Array(Anthropic::Models::Beta::BetaTextBlockParam, Anthropic::Models::Beta::BetaImageBlockParam, Anthropic::Models::Beta::BetaRequestDocumentBlock, Anthropic::Models::Beta::BetaSearchResultBlockParam, Anthropic::Models::Beta::BetaThinkingBlockParam, Anthropic::Models::Beta::BetaRedactedThinkingBlockParam, Anthropic::Models::Beta::BetaToolUseBlockParam, Anthropic::Models::Beta::BetaToolResultBlockParam, Anthropic::Models::Beta::BetaServerToolUseBlockParam, Anthropic::Models::Beta::BetaWebSearchToolResultBlockParam, Anthropic::Models::Beta::BetaWebFetchToolResultBlockParam, Anthropic::Models::Beta::BetaAdvisorToolResultBlockParam, Anthropic::Models::Beta::BetaCodeExecutionToolResultBlockParam, Anthropic::Models::Beta::BetaBashCodeExecutionToolResultBlockParam, Anthropic::Models::Beta::BetaTextEditorCodeExecutionToolResultBlockParam, Anthropic::Models::Beta::BetaToolSearchToolResultBlockParam, Anthropic::Models::Beta::BetaMCPToolUseBlockParam, Anthropic::Models::Beta::BetaRequestMCPToolResultBlockParam, Anthropic::Models::Beta::BetaContainerUploadBlockParam, Anthropic::Models::Beta::BetaCompactionBlockParam, Anthropic::Models::Beta::BetaMidConversationSystemBlockParam, Anthropic::Models::Beta::BetaRequestToolAdditionBlock, Anthropic::Models::Beta::BetaRequestToolRemovalBlock, Anthropic::Models::Beta::BetaFallbackBlockParam)]
       end
     end
 

data/lib/anthropic/models/beta/beta_fallback_credit_not_applied.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Models
+    module Beta
+      class BetaFallbackCreditNotApplied < Anthropic::Internal::Type::BaseModel
+        # @!attribute reason
+        #   Why the reprice was not applied.
+        #
+        #   A closed enum; additions to the redemption-check vocabulary arrive as deliberate
+        #   schema updates.
+        #
+        #   @return [Symbol, Anthropic::Models::Beta::BetaFallbackCreditNotApplied::Reason]
+        required :reason, enum: -> { Anthropic::Beta::BetaFallbackCreditNotApplied::Reason }
+
+        # @!attribute type
+        #
+        #   @return [Symbol, :not_applied]
+        required :type, const: :not_applied
+
+        # @!attribute remove_to_redeem
+        #   Request fields to remove before retrying, so the retry can redeem this token.
+        #
+        #   Present exactly when `reason` is `variant_fields_present` — never null, never an
+        #   empty array; absent otherwise. Fields are named only from your own request, and
+        #   only after the sealed variant hash matched. A served best-effort retry has
+        #   already been billed at normal price; nothing redeems retroactively, but a
+        #   corrected re-send inside the token's five-minute window can still redeem.
+        #
+        #   @return [Array<String>, nil]
+        optional :remove_to_redeem, Anthropic::Internal::Type::ArrayOf[String], nil?: true
+
+        # @!method initialize(reason:, remove_to_redeem: nil, type: :not_applied)
+        #   Some parameter documentations has been truncated, see
+        #   {Anthropic::Models::Beta::BetaFallbackCreditNotApplied} for more details.
+        #
+        #   No reprice was applied; `reason` says why.
+        #
+        #   @param reason [Symbol, Anthropic::Models::Beta::BetaFallbackCreditNotApplied::Reason] Why the reprice was not applied.
+        #
+        #   @param remove_to_redeem [Array<String>, nil] Request fields to remove before retrying, so the retry can redeem this
+        #
+        #   @param type [Symbol, :not_applied]
+
+        # Why the reprice was not applied.
+        #
+        # A closed enum; additions to the redemption-check vocabulary arrive as deliberate
+        # schema updates.
+        #
+        # @see Anthropic::Models::Beta::BetaFallbackCreditNotApplied#reason
+        module Reason
+          extend Anthropic::Internal::Type::Enum
+
+          BODY_MISMATCH = :body_mismatch
+          CONTINUATION_EXCLUDED = :continuation_excluded
+          CONTINUATION_ONLY = :continuation_only
+          EXPIRED = :expired
+          INVALID_TARGET_MODEL = :invalid_target_model
+          NOT_ENABLED = :not_enabled
+          REPRICE_UNAVAILABLE = :reprice_unavailable
+          TEMPORARILY_UNAVAILABLE = :temporarily_unavailable
+          VARIANT_FIELDS_PRESENT = :variant_fields_present
+          WRONG_ORGANIZATION = :wrong_organization
+          WRONG_PLATFORM = :wrong_platform
+          WRONG_WORKSPACE = :wrong_workspace
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+
+    BetaFallbackCreditNotApplied = Beta::BetaFallbackCreditNotApplied
+  end
+end

data/lib/anthropic/models/beta/beta_fallback_credit_redeemed.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Models
+    module Beta
+      class BetaFallbackCreditRedeemed < Anthropic::Internal::Type::BaseModel
+        # @!attribute type
+        #
+        #   @return [Symbol, :redeemed]
+        required :type, const: :redeemed
+
+        # @!method initialize(type: :redeemed)
+        #   The reprice was applied: the retry is billed as if the conversation had been on
+        #   the retry model all along.
+        #
+        #   @param type [Symbol, :redeemed]
+      end
+    end
+
+    BetaFallbackCreditRedeemed = Beta::BetaFallbackCreditRedeemed
+  end
+end

data/lib/anthropic/models/beta/beta_fallback_credit_token_param.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Models
+    module Beta
+      class BetaFallbackCreditTokenParam < Anthropic::Internal::Type::BaseModel
+        # @!attribute token
+        #   The opaque `fallback_credit_token` from a prior refusal's `stop_details` — the
+        #   same string the bare-string form carries.
+        #
+        #   @return [String]
+        required :token, String
+
+        # @!attribute mode
+        #   How a failing token affects the retry. `strict` (the default, and the
+        #   bare-string behavior): a failing redemption is a 400 and the retry is not
+        #   served. `best_effort`: the retry is served either way — a token-layer failure no
+        #   longer rejects the request; the retry proceeds at normal price and the outcome
+        #   is reported on the response's `usage.fallback_credit`. Two failures stay hard in
+        #   both modes: a malformed token, and combining `fallback_credit_token` with
+        #   `fallbacks`.
+        #
+        #   @return [Symbol, Anthropic::Models::Beta::BetaFallbackCreditTokenParam::Mode, nil]
+        optional :mode, enum: -> { Anthropic::Beta::BetaFallbackCreditTokenParam::Mode }
+
+        # @!method initialize(token:, mode: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Anthropic::Models::Beta::BetaFallbackCreditTokenParam} for more details.
+        #
+        #   Object form of `fallback_credit_token`: the token plus a redemption mode.
+        #
+        #   Requires `anthropic-beta: fallback-credit-2026-07-01`; without that header the
+        #   field accepts the bare string only. The bare string and the mode-less object are
+        #   equivalent (both select `strict`), so wrapping an existing token changes nothing
+        #   by itself.
+        #
+        #   @param token [String] The opaque `fallback_credit_token` from a prior refusal's `stop_details` — the s
+        #
+        #   @param mode [Symbol, Anthropic::Models::Beta::BetaFallbackCreditTokenParam::Mode] How a failing token affects the retry. `strict` (the default, and the bare-strin
+
+        # How a failing token affects the retry. `strict` (the default, and the
+        # bare-string behavior): a failing redemption is a 400 and the retry is not
+        # served. `best_effort`: the retry is served either way — a token-layer failure no
+        # longer rejects the request; the retry proceeds at normal price and the outcome
+        # is reported on the response's `usage.fallback_credit`. Two failures stay hard in
+        # both modes: a malformed token, and combining `fallback_credit_token` with
+        # `fallbacks`.
+        #
+        # @see Anthropic::Models::Beta::BetaFallbackCreditTokenParam#mode
+        module Mode
+          extend Anthropic::Internal::Type::Enum
+
+          STRICT = :strict
+          BEST_EFFORT = :best_effort
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+
+    BetaFallbackCreditTokenParam = Beta::BetaFallbackCreditTokenParam
+  end
+end