anthropic 1.48.2 → 1.49.0

data/lib/anthropic/middleware.rb

@@ -0,0 +1,435 @@
+# frozen_string_literal: true
+
+module Anthropic
+  # The per-attempt request object a middleware sees.
+  #
+  # Fields mirror what resource methods pass to `BaseClient#request` (see
+  # `RequestComponents`), with `path`/`query` resolved to a `URI::Generic`,
+  # headers fully normalized, and `retry_count`/`metadata` added.
+  #
+  # `body` is the **canonical** Anthropic request body — for JSON endpoints
+  # (`POST /v1/messages` etc.) a `Hash` like `{model:, messages:, max_tokens:}`,
+  # `nil` for body-less methods. It is *not* a serialized `String`: JSON
+  # encoding, 3p-provider rewrite (Bedrock/Vertex), and request signing all
+  # happen inside `nxt.call`, so a middleware that edits `body` via
+  # `req.with(body: ...)` does not need to re-serialize.
+  #
+  # Instances are frozen and the `headers`/`body`/`url`/`options` values the
+  # SDK supplies are deep-frozen — mutating them or any nested `Hash`/`Array`
+  # (e.g. `body[:messages]`) raises. Use {#with} to derive a copy. `metadata`
+  # is the one intentionally shared, mutable scratchpad that persists across
+  # retry attempts.
+  class APIRequest
+    # @api private
+    MEMBERS =
+      [:method, :url, :headers, :body, :stream, :cast_to, :unwrap, :options, :retry_count, :metadata].freeze
+
+    # @return [Symbol] the HTTP method (`:get`, `:post`, …)
+    attr_reader :method
+
+    # @return [URI::Generic] the resolved request URL (deep-frozen)
+    attr_reader :url
+
+    # @return [Hash{String=>String}] normalized request headers (deep-frozen)
+    attr_reader :headers
+
+    # @return [Object, nil] the canonical request body — usually a
+    #   `Hash{Symbol=>Object}` for JSON endpoints, `nil` for body-less, but may
+    #   be a `String`/`IO` for upload paths (see class doc; deep-frozen where
+    #   structurally copyable)
+    attr_reader :body
+
+    # @return [Class, nil] the SSE stream class to decode into; `nil` for
+    #   non-streaming
+    attr_reader :stream
+
+    # @return [Anthropic::Internal::Type::Converter::Input, nil] the model
+    #   class the response body will be coerced to; `nil` for paginated
+    #   requests
+    attr_reader :cast_to
+
+    # @return [Symbol, Integer, Array<Symbol, Integer>, Proc, nil] the envelope
+    #   key(s) the SDK digs out of the decoded body before coercing
+    attr_reader :unwrap
+
+    # @return [Hash{Symbol=>Object}] request options (`:timeout`, …;
+    #   deep-frozen)
+    attr_reader :options
+
+    # @return [Integer] number of prior attempts (`0` on the first)
+    attr_reader :retry_count
+
+    # @return [Hash{Symbol=>Object}] mutable cross-attempt scratchpad shared
+    #   between retries
+    attr_reader :metadata
+
+    # @param method [Symbol]
+    # @param url [URI::Generic]
+    # @param headers [Hash{String=>String}]
+    # @param body [Object, nil]
+    # @param stream [Class, nil]
+    # @param cast_to [Anthropic::Internal::Type::Converter::Input, nil]
+    # @param unwrap [Symbol, Integer, Array<Symbol, Integer>, Proc, nil]
+    # @param options [Hash{Symbol=>Object}]
+    # @param retry_count [Integer]
+    # @param metadata [Hash{Symbol=>Object}]
+    def initialize(
+      method:,
+      url:,
+      headers:,
+      body:,
+      stream:,
+      cast_to:,
+      unwrap:,
+      options:,
+      retry_count:,
+      metadata:
+    )
+      @method = method
+      @url = url
+      @headers = headers
+      @body = body
+      @stream = stream
+      @cast_to = cast_to
+      @unwrap = unwrap
+      @options = options
+      @retry_count = retry_count
+      @metadata = metadata
+      freeze
+    end
+
+    # @return [Boolean] whether the SDK call is a streaming/SSE request
+    def streaming? = !@stream.nil?
+
+    # @return [Boolean] whether this is a retry attempt (`retry_count > 0`)
+    def retry? = @retry_count.positive?
+
+    # @return [Float] the request timeout in seconds. Informational only — the
+    #   transport deadline is fixed when the SDK enters the middleware
+    #   terminal, so deriving a request via `with(options: {timeout: …})` does
+    #   not change it. Time spent inside middleware does not count against it.
+    def timeout = @options.to_h.fetch(:timeout, 0.0)
+
+    # Derive a copy with the given members replaced.
+    #
+    # @param method [Symbol]
+    # @param url [URI::Generic]
+    # @param headers [Hash{String=>String}]
+    # @param body [Object, nil]
+    # @param stream [Class, nil]
+    # @param cast_to [Anthropic::Internal::Type::Converter::Input, nil]
+    # @param unwrap [Symbol, Integer, Array<Symbol, Integer>, Proc, nil]
+    # @param options [Hash{Symbol=>Object}]
+    # @param retry_count [Integer]
+    # @param metadata [Hash{Symbol=>Object}]
+    # @return [Anthropic::APIRequest]
+    def with(**changes)
+      unknown = changes.keys - MEMBERS
+      unless unknown.empty?
+        raise ArgumentError,
+              "unknown keyword#{'s' if unknown.length > 1}: #{unknown.map(&:inspect).join(', ')}"
+      end
+      self.class.new(**to_h, **changes)
+    end
+
+    # @return [Hash{Symbol=>Object}]
+    def to_h = MEMBERS.to_h { [_1, instance_variable_get(:"@#{_1}")] }
+  end
+
+  # The per-attempt response object a middleware sees.
+  #
+  # `nxt.call(req)` returns an `APIResponse` for **all** HTTP status codes —
+  # 4xx and 5xx included. It does **not** raise on error status; the SDK
+  # converts to a typed `APIError` only after the chain completes. This lets a
+  # middleware inspect `res.status` on a 5xx and choose to substitute, retry
+  # differently, or pass through. Connection-level failures
+  # ({Anthropic::Errors::APITimeoutError}, {Anthropic::Errors::APIConnectionError})
+  # **do** raise from `nxt.call`.
+  class APIResponse
+    # Raised when a middleware returns an {APIResponse} whose body enumerator was
+    # already consumed without first calling {APIResponse#buffer!}. The SDK cannot
+    # parse a drained, unbuffered body. Fix by calling `res.buffer!` (or
+    # `res.parse`) before reading, or by using `res.wrap_body` to transform the
+    # stream without consuming it.
+    class ConsumedBodyError < Anthropic::Errors::Error
+    end
+
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [Hash{String=>String}] normalized response headers
+    attr_reader :headers
+
+    # @return [Net::HTTPResponse, nil] the raw response. `nil` for an
+    #   `APIResponse.new(...)` constructed by a middleware (e.g. a mock).
+    attr_reader :raw
+
+    # @return [Anthropic::APIRequest, nil] the request that produced this
+    #   response. {#parse} uses it to recover the SDK return type; a fabricated
+    #   response without one parses to the decoded body only.
+    attr_reader :request
+
+    # @api private
+    #
+    # Wraps the `[status, Net::HTTPResponse, Enumerable<String>]` tuple the
+    # pooled requester returns.
+    #
+    # @param status [Integer]
+    # @param raw [Net::HTTPResponse]
+    # @param stream [Enumerable<String>]
+    # @param request [Anthropic::APIRequest, nil]
+    # @return [Anthropic::APIResponse]
+    def self.wrap(status, raw, stream, request: nil)
+      # `initialize` normalizes `headers`, so pass the raw header hash straight
+      # through rather than normalizing twice on every response.
+      new(status: status, headers: raw.each_header.to_h, body: stream, raw: raw, request: request)
+    end
+
+    # @param status [Integer]
+    # @param headers [Hash{String=>String}]
+    # @param body [Enumerable<String>, String, nil]
+    # @param raw [Net::HTTPResponse, nil]
+    # @param streaming [Boolean, nil] override `streaming?`; inferred from
+    #   `request` if `nil`
+    # @param request [Anthropic::APIRequest, nil]
+    def initialize(status:, headers: {}, body: nil, raw: nil, streaming: nil, request: nil)
+      @status = status
+      @headers = Anthropic::Internal::Util.normalized_headers(headers)
+      @raw = raw
+      @request = request
+      @streaming = streaming
+      @buffered = nil
+      @drained = false
+      @parsed = Anthropic::Internal::OMIT
+
+      @body =
+        case body
+        in nil
+          @buffered = [].freeze
+        in String
+          @buffered = [body].freeze
+        in Array
+          @buffered = body.dup.freeze
+        else
+          # Wrap once so the first pull flips `@drained`; `to_tuple`/`buffer!`
+          # then detect a body that was iterated without buffering. Fused so
+          # `Util.close_fused!` (stream `close`, connection reaping) propagates
+          # to the upstream enum without first pulling a chunk off the socket.
+          Anthropic::Internal::Util.chain_fused(body) do |y|
+            @drained = true
+            body.each { y << _1 }
+          end
+        end
+    end
+
+    # @return [Enumerable<String>] the response body. **Single-consumer**
+    #   unless {#buffer!} has been called. After `buffer!`, this is a
+    #   rewindable `Array`.
+    def body = @buffered || @body
+
+    # @return [Boolean] whether the request that produced this response is a
+    #   streaming/SSE request.
+    def streaming?
+      return @streaming unless @streaming.nil?
+      @request&.streaming? || false
+    end
+
+    # @return [Boolean] whether the SDK would retry this status under its
+    #   default policy — parity with the Python SDK's `Response.is_retryable`.
+    #   Useful for middleware that wants to match the SDK's own retry decision.
+    def retryable?
+      Anthropic::Internal::Transport::BaseClient.should_retry?(@status, headers: @headers)
+    end
+
+    # Drain the body into memory so it can be re-read. Idempotent once
+    # buffered.
+    #
+    # @param force [Boolean] allow buffering a streaming response. By default
+    #   this raises because buffering an SSE stream defeats streaming; pass
+    #   `force: true` if you know the stream is bounded.
+    # @return [self]
+    # @raise [ArgumentError] if `streaming?` and `force` is false.
+    # @raise [Anthropic::APIResponse::ConsumedBodyError] if the body was
+    #   already drained by a raw `body.each` without buffering.
+    def buffer!(force: false)
+      return self if @buffered
+
+      if streaming? && !force
+        raise ArgumentError,
+              "Refusing to buffer a streaming response; pass `force: true` " \
+              "or use `wrap_body` to transform the stream without buffering."
+      end
+
+      if @drained
+        raise ConsumedBodyError,
+              "Response body was already consumed. Call `buffer!` (or " \
+              "`parse`) before reading the body, or use `wrap_body` to " \
+              "transform the stream without consuming it."
+      end
+
+      @buffered = @body.to_a.freeze
+      @drained = true
+      self
+    end
+
+    # Replace the body with the block's return value — the composable way to
+    # intercept streamed chunks without buffering.
+    #
+    # @param streaming [Boolean] value for the new response's `streaming?`.
+    #   Pass `false` if the wrapper collapses the stream to a buffered body.
+    # @yieldparam upstream [Enumerable<String>]
+    # @yieldreturn [Enumerable<String>]
+    # @return [Anthropic::APIResponse]
+    def wrap_body(streaming: streaming?)
+      raise ArgumentError, "wrap_body requires a block" unless block_given?
+      self.class.new(
+        status: @status,
+        headers: @headers,
+        body: yield(body),
+        raw: @raw,
+        streaming: streaming,
+        request: @request
+      )
+    end
+
+    # Decode and coerce the body to the SDK-typed result the original caller
+    # would have received (e.g. `Anthropic::Message`). Internally `buffer!`s
+    # first, so calling `parse` does not steal the body from downstream — the
+    # SDK reuses the buffered copy.
+    #
+    # For non-streaming responses the decoded value is coerced to the request's
+    # return type and memoized — repeated calls across the chain cost a single
+    # decode. A fabricated response without a `request:` parses to the decoded
+    # body (e.g. a `Hash`) instead of an SDK model.
+    #
+    # For streaming requests, returns a typed stream reading an independent
+    # buffered copy of the response body — iterating (or `break`ing out of) it
+    # neither consumes nor cancels the events the SDK caller will read. Streams
+    # are single-consumer, so each call returns a fresh stream rather than a
+    # memoized one.
+    #
+    # @example
+    #   usage_logger = lambda do |req, nxt|
+    #     res = nxt.call(req)
+    #     LOGGER.info("usage: #{res.parse.usage}") if res.status < 300
+    #     res
+    #   end
+    #
+    # @return [Object]
+    def parse
+      return parse_stream if streaming?
+      return @parsed unless Anthropic::Internal::OMIT.equal?(@parsed)
+
+      buffer!
+      decoded = Anthropic::Internal::Util.decode_content(@headers, stream: body.each)
+      unwrapped = Anthropic::Internal::Util.dig(decoded, @request&.unwrap)
+      cast_to = @request&.cast_to || Anthropic::Internal::Type::Unknown
+      @parsed = Anthropic::Internal::Type::Converter.coerce(cast_to, unwrapped)
+    end
+
+    # @api private
+    #
+    # Back to the `[Integer, Net::HTTPResponse|nil, Hash, Enumerable<String>]`
+    # tuple shape `send_request` works with internally. Headers come from
+    # {#headers} — never re-derived from `raw` — so a middleware that returns
+    # a modified header set over the original raw response is honored.
+    #
+    # @return [Array(Integer, Net::HTTPResponse|nil, Hash{String=>String}, Enumerable<String>)]
+    def to_tuple
+      if @buffered.nil? && @drained
+        raise ConsumedBodyError,
+              "Middleware consumed the response body without buffering it. " \
+              "Call `buffer!` (or `parse`) before reading, or use `wrap_body`."
+      end
+      [status, @raw, @headers, @buffered || @body]
+    end
+
+    private
+
+    # A fresh typed stream over a buffered copy of the response body.
+    #
+    # @return [Anthropic::Internal::Type::BaseStream, Enumerable]
+    def parse_stream
+      buffer!(force: true)
+      decoded = Anthropic::Internal::Util.decode_content(@headers, stream: body.each)
+      stream = @request&.stream
+      return decoded unless stream
+
+      stream.new(
+        model: @request.cast_to,
+        url: @request.url,
+        status: status,
+        headers: @headers,
+        response: @raw,
+        unwrap: @request.unwrap,
+        stream: decoded
+      )
+    end
+  end
+
+  # HTTP around-middleware.
+  #
+  # A middleware is any object that responds to `#call(request, nxt)` and
+  # returns an {Anthropic::APIResponse}. `nxt` is itself a `#call(request)`-able
+  # that invokes the rest of the chain and, ultimately, a single HTTP attempt.
+  # The chain runs **per attempt, inside the SDK's retry loop** — the same
+  # placement as Go, TypeScript, Java, and Python.
+  #
+  # Register middleware at the client level via `Anthropic::Client.new(middleware: [...])`,
+  # or per request via `request_options: {middleware: [...]}`. Request-level
+  # entries run innermost (below client-level entries), so client-level
+  # middleware still wraps every request a per-call middleware fabricates or
+  # retries.
+  #
+  # On provider clients (Bedrock/Vertex/AWS), a provider middleware is
+  # appended below all user entries on every dispatch: it rewrites the
+  # canonical request into the provider's wire shape and applies provider
+  # auth (SigV4/OAuth), so user middleware always sees the canonical
+  # Anthropic request and every re-issued or retried leg is re-signed.
+  #
+  # @example
+  #   log = ->(req, nxt) { res = nxt.call(req); LOGGER.info(res.status); res }
+  #   Anthropic::Client.new(middleware: [log])
+  module Middleware
+    # Optional mixin that names the middleware contract for users who prefer a
+    # class to a lambda. `include Anthropic::Middleware` and implement
+    # `#call(request, nxt)`. The SDK treats *any* `#call(req, nxt)` object as
+    # middleware (lambdas, procs, `Method`s included), so including this is for
+    # discovery and type-checking — under Sorbet the method is `abstract`, so a
+    # missing or mis-typed `#call` is a static error — not a runtime
+    # requirement.
+    #
+    # @example
+    #   class AddTeamHeader
+    #     include Anthropic::Middleware
+    #
+    #     def initialize(team) = @team = team
+    #
+    #     def call(request, nxt)
+    #       nxt.call(request.with(headers: request.headers.merge("x-team" => @team)))
+    #     end
+    #   end
+    #
+    # @param request [Anthropic::APIRequest] the per-attempt request
+    # @param nxt [#call] invokes the rest of the chain; returns an {APIResponse}
+    # @return [Anthropic::APIResponse]
+    def call(request, nxt)
+      raise NotImplementedError, "#{self.class} must implement #{Anthropic::Middleware}#call(request, nxt)"
+    end
+
+    class << self
+      # @api private
+      #
+      # Compose `list` into a single callable. `list[0]` is outermost.
+      #
+      # @param list [Array<#call>]
+      # @param terminal [#call] the innermost callable — the actual HTTP attempt
+      # @return [#call]
+      def build_chain(list, terminal)
+        list.reverse.reduce(terminal) do |inner, mw|
+          ->(req) { mw.call(req, inner) }
+        end
+      end
+    end
+  end
+end

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

@@ -106,13 +106,15 @@ module Anthropic
         # Values: direct: The model can call this tool directly. code_execution_20250825:
         # The tool can be called from the code execution environment (v1).
         # code_execution_20260120: The tool can be called from the code execution
-        # environment (v2 with persistence).
+        # environment (v2 with persistence). code_execution_20260521: The tool can be
+        # called from the code execution environment (v2 with persistence).
         module AllowedCaller
           extend Anthropic::Internal::Type::Enum
 
           DIRECT = :direct
           CODE_EXECUTION_20250825 = :code_execution_20250825
           CODE_EXECUTION_20260120 = :code_execution_20260120
+          CODE_EXECUTION_20260521 = :code_execution_20260521
 
           # @!method self.values
           #   @return [Array<Symbol>]

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

@@ -63,13 +63,15 @@ module Anthropic
         # Values: direct: The model can call this tool directly. code_execution_20250825:
         # The tool can be called from the code execution environment (v1).
         # code_execution_20260120: The tool can be called from the code execution
-        # environment (v2 with persistence).
+        # environment (v2 with persistence). code_execution_20260521: The tool can be
+        # called from the code execution environment (v2 with persistence).
         module AllowedCaller
           extend Anthropic::Internal::Type::Enum
 
           DIRECT = :direct
           CODE_EXECUTION_20250825 = :code_execution_20250825
           CODE_EXECUTION_20260120 = :code_execution_20260120
+          CODE_EXECUTION_20260521 = :code_execution_20260521
 
           # @!method self.values
           #   @return [Array<Symbol>]

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

@@ -63,13 +63,15 @@ module Anthropic
         # Values: direct: The model can call this tool directly. code_execution_20250825:
         # The tool can be called from the code execution environment (v1).
         # code_execution_20260120: The tool can be called from the code execution
-        # environment (v2 with persistence).
+        # environment (v2 with persistence). code_execution_20260521: The tool can be
+        # called from the code execution environment (v2 with persistence).
         module AllowedCaller
           extend Anthropic::Internal::Type::Enum
 
           DIRECT = :direct
           CODE_EXECUTION_20250825 = :code_execution_20250825
           CODE_EXECUTION_20260120 = :code_execution_20260120
+          CODE_EXECUTION_20260521 = :code_execution_20260521
 
           # @!method self.values
           #   @return [Array<Symbol>]

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

@@ -66,13 +66,15 @@ module Anthropic
         # Values: direct: The model can call this tool directly. code_execution_20250825:
         # The tool can be called from the code execution environment (v1).
         # code_execution_20260120: The tool can be called from the code execution
-        # environment (v2 with persistence).
+        # environment (v2 with persistence). code_execution_20260521: The tool can be
+        # called from the code execution environment (v2 with persistence).
         module AllowedCaller
           extend Anthropic::Internal::Type::Enum
 
           DIRECT = :direct
           CODE_EXECUTION_20250825 = :code_execution_20250825
           CODE_EXECUTION_20260120 = :code_execution_20260120
+          CODE_EXECUTION_20260521 = :code_execution_20260521
 
           # @!method self.values
           #   @return [Array<Symbol>]

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Models
+    module Beta
+      class BetaCodeExecutionTool20260521 < Anthropic::Internal::Type::BaseModel
+        # @!attribute name
+        #   Name of the tool.
+        #
+        #   This is how the tool will be called by the model and in `tool_use` blocks.
+        #
+        #   @return [Symbol, :code_execution]
+        required :name, const: :code_execution
+
+        # @!attribute type
+        #
+        #   @return [Symbol, :code_execution_20260521]
+        required :type, const: :code_execution_20260521
+
+        # @!attribute allowed_callers
+        #
+        #   @return [Array<Symbol, Anthropic::Models::Beta::BetaCodeExecutionTool20260521::AllowedCaller>, nil]
+        optional :allowed_callers,
+                 -> { Anthropic::Internal::Type::ArrayOf[enum: Anthropic::Beta::BetaCodeExecutionTool20260521::AllowedCaller] }
+
+        # @!attribute cache_control
+        #   Create a cache control breakpoint at this content block.
+        #
+        #   @return [Anthropic::Models::Beta::BetaCacheControlEphemeral, nil]
+        optional :cache_control, -> { Anthropic::Beta::BetaCacheControlEphemeral }, nil?: true
+
+        # @!attribute defer_loading
+        #   If true, tool will not be included in initial system prompt. Only loaded when
+        #   returned via tool_reference from tool search.
+        #
+        #   @return [Boolean, nil]
+        optional :defer_loading, Anthropic::Internal::Type::Boolean
+
+        # @!attribute strict
+        #   When true, guarantees schema validation on tool names and inputs
+        #
+        #   @return [Boolean, nil]
+        optional :strict, Anthropic::Internal::Type::Boolean
+
+        # @!method initialize(allowed_callers: nil, cache_control: nil, defer_loading: nil, strict: nil, name: :code_execution, type: :code_execution_20260521)
+        #   Some parameter documentations has been truncated, see
+        #   {Anthropic::Models::Beta::BetaCodeExecutionTool20260521} for more details.
+        #
+        #   Code execution tool with REPL state persistence.
+        #
+        #   @param allowed_callers [Array<Symbol, Anthropic::Models::Beta::BetaCodeExecutionTool20260521::AllowedCaller>]
+        #
+        #   @param cache_control [Anthropic::Models::Beta::BetaCacheControlEphemeral, nil] Create a cache control breakpoint at this content block.
+        #
+        #   @param defer_loading [Boolean] If true, tool will not be included in initial system prompt. Only loaded when re
+        #
+        #   @param strict [Boolean] When true, guarantees schema validation on tool names and inputs
+        #
+        #   @param name [Symbol, :code_execution] Name of the tool.
+        #
+        #   @param type [Symbol, :code_execution_20260521]
+
+        # Specifies who can invoke a tool.
+        #
+        # Values: direct: The model can call this tool directly. code_execution_20250825:
+        # The tool can be called from the code execution environment (v1).
+        # code_execution_20260120: The tool can be called from the code execution
+        # environment (v2 with persistence). code_execution_20260521: The tool can be
+        # called from the code execution environment (v2 with persistence).
+        module AllowedCaller
+          extend Anthropic::Internal::Type::Enum
+
+          DIRECT = :direct
+          CODE_EXECUTION_20250825 = :code_execution_20250825
+          CODE_EXECUTION_20260120 = :code_execution_20260120
+          CODE_EXECUTION_20260521 = :code_execution_20260521
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+
+    BetaCodeExecutionTool20260521 = Beta::BetaCodeExecutionTool20260521
+  end
+end

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

@@ -51,9 +51,9 @@ module Anthropic
         # Marks the point in `content` where one model's output gives way to the next.
         #
         # One block appears per hop where a preceding model actually ran this turn and
-        # declined. A turn routed directly by the sticky decision has no such boundary
-        # and carries no block — the signal for whether a fallback model served the
-        # response is the presence of a `fallback_message` entry in
+        # declined. A turn where no preceding model ran and declined has no such
+        # boundary and carries no block — the signal for whether a fallback model
+        # served the response is the presence of a `fallback_message` entry in
         # `usage.iterations`, not this block.
         #
         # The block is treated like a server-tool content block for streaming: it

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

@@ -76,19 +76,17 @@ module Anthropic
 
         # A `fallback` block echoed back from a prior response.
         #
-        # Accepted in `messages[].content` and never rendered into the prompt,
-        # not validated against the request's `fallbacks` chain or top-level
-        # `model`, and stripped before the sticky-routing cache key is computed.
+        # Accepted in `messages[].content` and not rendered into the prompt; not
+        # validated against the request's `fallbacks` chain or top-level `model`.
         #
-        # Callers should echo the assistant turn verbatim — block included. The
-        # block's position is load-bearing for thinking verification: the thinking
-        # runs on either side of a fallback hop carry independently-rooted
-        # verification hash chains, and this block is the only record of where one
-        # chain ends and the next begins. When thinking runs flank the boundary,
-        # omitting the block merges the runs into one contiguous span whose hashes
-        # cannot verify (the request is rejected), and moving it into the middle of
-        # a single run splits that run's chain and is likewise rejected; between
-        # non-thinking blocks the block's placement has no verification effect.
+        # Echo the assistant turn back verbatim, including this block in its
+        # original position. The block marks the boundary between content produced
+        # before and after a fallback hop, and the server relies on that boundary
+        # to validate the turn: when thinking runs flank the boundary, omitting
+        # the block merges them into one span the server cannot validate (the
+        # request is rejected), and moving it into the middle of a single run is
+        # likewise rejected; between non-thinking blocks the block's placement has
+        # no validation effect.
         variant :fallback, -> { Anthropic::Beta::BetaFallbackBlockParam }
 
         # @!method self.variants

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

@@ -20,22 +20,28 @@ module Anthropic
         #   @return [Anthropic::Models::Beta::BetaFallbackInfo]
         required :to, -> { Anthropic::Beta::BetaFallbackInfo }
 
+        # @!attribute trigger
+        #   What caused the `from` model to hand over at this hop.
+        #
+        #   @return [Anthropic::Models::Beta::BetaFallbackRefusalTrigger]
+        required :trigger, -> { Anthropic::Beta::BetaFallbackRefusalTrigger }
+
         # @!attribute type
         #
         #   @return [Symbol, :fallback]
         required :type, const: :fallback
 
-        # @!method initialize(from:, to:, type: :fallback)
+        # @!method initialize(from:, to:, trigger:, type: :fallback)
         #   Some parameter documentations has been truncated, see
         #   {Anthropic::Models::Beta::BetaFallbackBlock} for more details.
         #
         #   Marks the point in `content` where one model's output gives way to the next.
         #
         #   One block appears per hop where a preceding model actually ran this turn and
-        #   declined. A turn routed directly by the sticky decision has no such boundary and
-        #   carries no block — the signal for whether a fallback model served the response
-        #   is the presence of a `fallback_message` entry in `usage.iterations`, not this
-        #   block.
+        #   declined. A turn where no preceding model ran and declined has no such boundary
+        #   and carries no block — the signal for whether a fallback model served the
+        #   response is the presence of a `fallback_message` entry in `usage.iterations`,
+        #   not this block.
         #
         #   The block is treated like a server-tool content block for streaming: it arrives
         #   via the standard `content_block_start` / `content_block_stop` pair and carries
@@ -45,6 +51,8 @@ module Anthropic
         #
         #   @param to [Anthropic::Models::Beta::BetaFallbackInfo] The fallback model producing the content that follows this block. Its `model` is
         #
+        #   @param trigger [Anthropic::Models::Beta::BetaFallbackRefusalTrigger] What caused the `from` model to hand over at this hop.
+        #
         #   @param type [Symbol, :fallback]
       end
     end