anthropic 1.78.0 → 1.79.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 064db3cf4e22be64272a2aa28eb45829da4ddd01a3fdfec1cfc8bc0b6e9d0216
-  data.tar.gz: 1f65d4417898900499d402aff8b3225c2f2016a52984c25637800e4a8d4ec0c6
+  metadata.gz: 74e6cbcdcbbf6d31ad5a08947e0b061fb8be75a367c6be4aac63cf7a715279fc
+  data.tar.gz: 9dcb1523d20c8af4dce1dadd9d6387f6dca92c0c2c8647eed98caa4a1e915197
 SHA512:
-  metadata.gz: f6588afface6416906b56c266d0c088057aa93363b4cadb7e445ab7ec096c6bfb46006433109230ce001ce0fb4fb023cef2e294e35bb62c480c32f82d893c769
-  data.tar.gz: c6103754b6be3dfeb451995ab5d5a9b8aa68e0af8d7ad48306d06d8cf8c82d6100a152c9cb467600346ddd2446fbde3b9ef8e24a71350c1f4a4905e77b7f28e8
+  metadata.gz: 4d5532e5feec100f1edd36c35e00bc9b61192624fcd785710373fcb439fdc300cc0b499142df492bdc92098ebfe4a29ec36216fb0e8636f0c0e272c42865cdd0
+  data.tar.gz: 734afbe0a5d61ca96d6872c8ac7ee0ec771ac76b07349843b826e14cad1afa8a46619ed6ee416b3ba48405c4f3453800a174f15fe75f7e78a8f774b3384f979b

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [1.79.0](https://github.com/anthropics/anthropic-sdk-ruby/compare/v1.78.0...v1.79.0) (2026-10-14)
+
+### Features
+
+* **api:** add execution_identity to Managed Agents agents
+* **api:** add organization_type_not_supported error to spend limit lists
+* **api:** add telemetry destination test endpoint
+* **api:** add telemetry destinations to the Admin API
+* **client:** add OpenTelemetry tracing for API calls, streaming and tool runs, on by default: once the application registers a tracer provider each call emits a span, and each request carries the trace context in the headers of the registered propagator, such as `traceparent`. `open_telemetry: false` or `ANTHROPIC_OPEN_TELEMETRY=false` turns both off, and `open_telemetry: {propagation: false}` or `ANTHROPIC_OPEN_TELEMETRY_PROPAGATION=false` only the headers, where a variable applies only to a client that is given no `open_telemetry` option. Adds the dependency `opentelemetry-api` (`>= 1.2.4`, `< 2`)
+
+
+### Bug Fixes
+
+* **api:** rename telemetry destination test response model
+* **client:** ignore OpenTelemetry env vars when the option is set
+* **client:** keep the discriminator when a union's .new builds a variant
+* **streaming:** keep every field of a tool use block when attaching its parsed input
+* **streaming:** pass events of an unknown type through the message stream helper untouched
+* **tools:** name the toolset on the tool runner's result for a toolset member's call
+
+
+### Chores
+
+* **docs:** correct prefill, thinking, fallback and model descriptions
+* **docs:** document the scope required to assign the managed role
+* **docs:** update model examples
+* include the license files in the published packages
+* **internal:** narrow the tripwire test rule in the contributor guides
+
+
+### Documentation
+
+* **api:** clarify when custom tool results can be sent
+* **api:** say is_enabled is always true for user spend limits
+
 ## [1.78.0](https://github.com/anthropics/anthropic-sdk-ruby/compare/v1.77.1...v1.78.0) (2026-10-09)
 
 ### Features

data/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2023 Anthropic, PBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -15,7 +15,7 @@ Add to your application's Gemfile:
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "anthropic", "~> 1.78.0"
+gem "anthropic", "~> 1.79.0"
 ```
 
 <!-- x-release-please-end -->
@@ -44,6 +44,47 @@ puts(message.content)
 
 Ruby 3.2.0+
 
+## OpenTelemetry
+
+Spans are on by default.
+Register a tracer provider with OpenTelemetry, for example with `OpenTelemetry::SDK.configure`, and every client reports each API call as a span.
+No client option is needed.
+Each request also carries the trace context in the headers that the registered propagator writes, such as `traceparent`, with or without a tracer provider.
+
+The `open_telemetry` client option changes the default:
+
+- `open_telemetry: {tracer_provider: provider}` uses `provider` instead of the registered tracer provider.
+- `open_telemetry: {propagation: false}` sends no trace context headers, such as `traceparent` and `baggage`, with the client's requests.
+  It is for an application whose HTTP client instrumentation already sends them, so that a request does not carry them twice. The spans are unaffected.
+- `open_telemetry: false` turns the spans and the trace context headers off. It is short for `{traces: false}`, which is short for `{traces: {enabled: false}}`.
+- `open_telemetry: {traces: {content_mode: :content}}` adds the messages, stop sequences, and tool calls to the spans.
+  It also adds `url.query` and `url.full` to the span of a request whose query has an `email`, `path_prefix` or `expected_content_sha256` parameter, which has neither otherwise.
+- `open_telemetry: {traces: {max_content_bytes: 65_536}}` sets the most bytes of content that one span holds, in place of 0.75 MB.
+  A span whose content is cut to fit has `anthropic.content.truncated`.
+
+`open_telemetry: true` is short for `{traces: true}`, and `traces: true` is short for `traces: {enabled: true}`.
+With `enabled: false`, the other keys of `traces` are unused.
+What the option leaves unset has its default.
+
+A client that is given no `open_telemetry` option reads the environment when it is made: `ANTHROPIC_OPEN_TELEMETRY=false` turns its spans and the trace context headers off, `ANTHROPIC_OPEN_TELEMETRY_PROPAGATION=false` turns only the headers off, `ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content` adds the content, and `ANTHROPIC_OPEN_TELEMETRY_TRACES_MAX_CONTENT_BYTES=65536` sets the most bytes.
+A client that is given the option, even `true` or `{}`, reads none of these variables: `open_telemetry: true` turns the spans on whatever `ANTHROPIC_OPEN_TELEMETRY` says.
+
+The keys of the option, and of its `traces`, can be Symbols or Strings, and a key that the option does not have raises `ArgumentError`.
+So does a `propagation` other than `true` or `false`, a `content_mode` other than `:metadata_only` or `:content`, and a `max_content_bytes` that is not an Integer of 1 or more.
+An environment variable with such a value is ignored.
+
+One request option sets `gen_ai.conversation.id` on the span of a call:
+
+```ruby
+anthropic.messages.create(**params, request_options: {open_telemetry: {conversation_id: id}})
+```
+
+`conversation_id` is the only key of the request option, and any other key raises `ArgumentError`: the tracer provider, `propagation` and the `traces` settings belong to the client.
+Without it, the span of a request to a Session thread, such as `beta.sessions.threads.retrieve`, has the thread's ID as its `gen_ai.conversation.id`.
+
+In the content mode, the content of a streamed response comes from the message that `messages.stream` accumulates.
+The span of a `messages.stream_raw` call has the request's content only.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).

data/lib/anthropic/client.rb

@@ -190,6 +190,36 @@ module Anthropic
     # @param timeout [Float, nil] Request timeout in seconds. Defaults to
     # `Anthropic::Client::DEFAULT_TIMEOUT_IN_SECONDS` when `nil`.
     #
+    # @param open_telemetry [Hash{Symbol=>Object}, Boolean, nil] OpenTelemetry tracing of this client's API calls. Each call emits a span when
+    # the application has registered a tracer provider with the OpenTelemetry API.
+    # `true` and `false` are short for `{traces: true}` and `{traces: false}`. Keys
+    # can be Strings, and an unknown key raises `ArgumentError`. A client that is
+    # given no option reads `ENV["ANTHROPIC_OPEN_TELEMETRY"]`, where `false` is
+    # `open_telemetry: false`, `ENV["ANTHROPIC_OPEN_TELEMETRY_PROPAGATION"]`, where
+    # `false` is `propagation: false`,
+    # `ENV["ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE"]` and
+    # `ENV["ANTHROPIC_OPEN_TELEMETRY_TRACES_MAX_CONTENT_BYTES"]`. A client that is
+    # given the option, even `true` or `{}`, reads none of them.
+    #
+    #   @option open_telemetry [#tracer] :tracer_provider Used in place of the registered tracer provider.
+    #
+    #   @option open_telemetry [Boolean] :propagation `false` sends no trace context headers, such as `traceparent`, with this
+    #   client's requests, for an application whose HTTP client instrumentation already
+    #   sends them, so that a request does not carry them twice. The spans are
+    #   unaffected. Defaults to `true`.
+    #
+    #   @option open_telemetry [Hash{Symbol=>Object}, Boolean] :traces The settings of the spans. `true` and `false` are short for `{enabled: true}`
+    #   and `{enabled: false}`. Its keys:
+    #
+    #   - `:enabled` (Boolean): `false` disables the spans, and the other keys are then
+    #     unused. Defaults to `true`.
+    #   - `:content_mode` (Symbol, String): `:content` adds the content of requests and
+    #     responses to the spans, and `:metadata_only` does not. Defaults to
+    #     `:metadata_only`.
+    #   - `:max_content_bytes` (Integer): the most bytes of content that one span holds,
+    #     1 or more. Content over the bound is cut, and the span then has
+    #     `anthropic.content.truncated`. Defaults to 0.75 MB.
+    #
     # @param initial_retry_delay [Float]
     #
     # @param max_retry_delay [Float]
@@ -207,6 +237,7 @@ module Anthropic
       proxy: nil,
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: nil,
+      open_telemetry: nil,
       initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
       max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY,
       middleware: nil
@@ -298,6 +329,7 @@ module Anthropic
         base_url: base_url,
         proxy: proxy,
         timeout: timeout,
+        open_telemetry: open_telemetry,
         max_retries: max_retries,
         initial_retry_delay: initial_retry_delay,
         max_retry_delay: max_retry_delay,

data/lib/anthropic/helpers/aws/client.rb

@@ -54,6 +54,9 @@ module Anthropic
         #
         # @param max_retry_delay [Float]
         #
+        # @param open_telemetry [Hash{Symbol=>Object}, Boolean, nil] OpenTelemetry tracing of this
+        #   client's API calls. See {Anthropic::Client#initialize}.
+        #
         def initialize(
           api_key: nil,
           aws_access_key: nil,
@@ -67,7 +70,8 @@ module Anthropic
           max_retries: self.class::DEFAULT_MAX_RETRIES,
           timeout: nil,
           initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
-          max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
+          max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY,
+          open_telemetry: nil
         )
           effective_api_key, resolved_base_url = setup_aws_auth(
             api_key: api_key,
@@ -96,10 +100,16 @@ module Anthropic
             timeout: timeout,
             max_retries: max_retries,
             initial_retry_delay: initial_retry_delay,
-            max_retry_delay: max_retry_delay
+            max_retry_delay: max_retry_delay,
+            open_telemetry: open_telemetry
           )
         end
 
+        # @api private
+        #
+        # @return [String]
+        private def open_telemetry_scope = "#{super}.aws"
+
         # @api private
         #
         # @return [#call]

data/lib/anthropic/helpers/aws_auth.rb

@@ -185,6 +185,10 @@ module Anthropic
       # a `StringIO`, which the terminal's encoding passes through untouched,
       # so the signed payload is exactly the bytes that go over the wire.
       #
+      # The headers that carry a trace context are sent but not signed: an HTTP
+      # instrumentation may replace them with the context of its own span after
+      # this, which would invalidate a signature that covered them.
+      #
       # @param req [Anthropic::APIRequest]
       # @return [Anthropic::APIRequest]
       private def sign_aws_request(req)
@@ -201,7 +205,10 @@ module Anthropic
             StringIO.new(encoded.to_s)
           end
 
-        signed = @signer.sign_request(http_method: req.method, url: req.url, body: body, headers: headers)
+        # The propagator is read per request: the application may register it after it makes the client.
+        unsigned = %w[traceparent tracestate baggage] | Anthropic::Internal::Tracing.trace_header_names(nil)
+        signable = headers.reject { |name, _| unsigned.include?(name.to_s.downcase) }
+        signed = @signer.sign_request(http_method: req.method, url: req.url, body: body, headers: signable)
         headers = Anthropic::Internal::Util.normalized_headers(headers, signed.headers)
         headers.delete("connection")
         req.with(headers: headers, body: body)

data/lib/anthropic/helpers/bedrock/client.rb

@@ -61,6 +61,9 @@ module Anthropic
         #   the Bedrock URL rewrite and SigV4 signing happen inside the continuation, per
         #   attempt.
         #
+        # @param open_telemetry [Hash{Symbol=>Object}, Boolean, nil] OpenTelemetry tracing of this
+        #   client's API calls. See {Anthropic::Client#initialize}.
+        #
         def initialize(
           aws_region: nil,
           base_url: nil,
@@ -73,7 +76,8 @@ module Anthropic
           aws_session_token: nil,
           aws_profile: nil,
           api_key: nil,
-          middleware: nil
+          middleware: nil,
+          open_telemetry: nil
         )
           api_key ||= ENV["AWS_BEARER_TOKEN_BEDROCK"]
 
@@ -140,7 +144,8 @@ module Anthropic
             max_retries: max_retries,
             initial_retry_delay: initial_retry_delay,
             max_retry_delay: max_retry_delay,
-            middleware: middleware
+            middleware: middleware,
+            open_telemetry: open_telemetry
           )
         end
 
@@ -206,6 +211,18 @@ module Anthropic
           super
         end
 
+        # @api private
+        #
+        # @return [Hash{String=>String}]
+        def open_telemetry_attributes
+          {**super, Anthropic::Internal::Tracing::GEN_AI_PROVIDER_NAME => "aws.bedrock"}
+        end
+
+        # @api private
+        #
+        # @return [String]
+        private def open_telemetry_scope = "#{super}.bedrock"
+
         # @api private
         #
         # The Bedrock provider middleware: rewrites the canonical request into

data/lib/anthropic/helpers/bedrock/mantle_client.rb

@@ -58,6 +58,9 @@ module Anthropic
         #
         # @param max_retry_delay [Float]
         #
+        # @param open_telemetry [Hash{Symbol=>Object}, Boolean, nil] OpenTelemetry tracing of this
+        #   client's API calls. See {Anthropic::Client#initialize}.
+        #
         def initialize(
           api_key: nil,
           aws_access_key: nil,
@@ -70,7 +73,8 @@ module Anthropic
           max_retries: self.class::DEFAULT_MAX_RETRIES,
           timeout: nil,
           initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
-          max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY
+          max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY,
+          open_telemetry: nil
         )
           effective_api_key, resolved_base_url = setup_aws_auth(
             api_key: api_key,
@@ -94,7 +98,8 @@ module Anthropic
             max_retries: max_retries,
             timeout: timeout,
             initial_retry_delay: initial_retry_delay,
-            max_retry_delay: max_retry_delay
+            max_retry_delay: max_retry_delay,
+            open_telemetry: open_telemetry
           )
 
           # Only initialize supported resources
@@ -126,6 +131,18 @@ module Anthropic
                 "Skills are not supported on Bedrock Mantle. Only Messages (/v1/messages) is supported."
         end
 
+        # @api private
+        #
+        # @return [Hash{String=>String}]
+        def open_telemetry_attributes
+          {**super, Anthropic::Internal::Tracing::GEN_AI_PROVIDER_NAME => "aws.bedrock"}
+        end
+
+        # @api private
+        #
+        # @return [String]
+        private def open_telemetry_scope = "#{super}.bedrock"
+
         # @api private
         #
         # @return [#call]

data/lib/anthropic/helpers/google_cloud/client.rb

@@ -87,6 +87,9 @@ module Anthropic
         #   is applied per attempt, after user middleware.
         #
         # @raise [ArgumentError]
+        #
+        # @param open_telemetry [Hash{Symbol=>Object}, Boolean, nil] OpenTelemetry tracing of this
+        #   client's API calls. See {Anthropic::Client#initialize}.
         def initialize(
           project: ENV["ANTHROPIC_GOOGLE_CLOUD_PROJECT"] || ENV["GOOGLE_CLOUD_PROJECT"],
           location: ENV["ANTHROPIC_GOOGLE_CLOUD_LOCATION"] || "global",
@@ -99,7 +102,8 @@ module Anthropic
           timeout: nil,
           initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
           max_retry_delay: self.class::DEFAULT_MAX_RETRY_DELAY,
-          middleware: nil
+          middleware: nil,
+          open_telemetry: nil
         )
           if skip_auth && (token_provider || google_credentials)
             raise ArgumentError.new(
@@ -151,7 +155,8 @@ module Anthropic
             max_retries: max_retries,
             initial_retry_delay: initial_retry_delay,
             max_retry_delay: max_retry_delay,
-            middleware: middleware
+            middleware: middleware,
+            open_telemetry: open_telemetry
           )
         end
 
@@ -180,6 +185,11 @@ module Anthropic
         # @return [Hash{String=>String}]
         private def auth_headers = {}
 
+        # @api private
+        #
+        # @return [String]
+        private def open_telemetry_scope = "#{super}.google_cloud"
+
         # @api private
         #
         # The Google Cloud provider middleware: applies the Google OAuth

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

@@ -22,12 +22,20 @@ module Anthropic
         #
         # @return [Enumerable<generic<Elem>>]
         private def iterator
-          @iterator ||= Anthropic::Internal::Util.chain_fused(@stream) do |y|
+          # Closing this stream closes the raw stream, which ends the request.
+          @iterator ||= Anthropic::Internal::Util.chain_fused(@raw_stream.to_enum) do |y|
             @raw_stream.each do |raw_event|
-              @accumated_message_snapshot = accumulate_event(
-                event: raw_event,
-                current_snapshot: @accumated_message_snapshot
-              )
+              # An event of a type this version doesn't know arrives as the closest known class, with
+              # `type` left as a String.
+              unless raw_event.type.is_a?(Symbol)
+                y << raw_event
+                next
+              end
+
+              @accumated_message_snapshot =
+                Anthropic::Helpers::Tracing.accumulate_streamed_message(@raw_stream) do
+                  accumulate_event(event: raw_event, current_snapshot: @accumated_message_snapshot)
+                end
               events_to_yield = build_events(event: raw_event, message_snapshot: @accumated_message_snapshot)
               events_to_yield.each(&y)
             end
@@ -96,18 +104,11 @@ module Anthropic
             raise ArgumentError.new(message)
           end
 
-          if current_snapshot.nil?
-            return event.message if event.type == :message_start
-
-            message = "Unexpected event order, got \"#{event.type}\" before \":message_start\""
-            raise RuntimeError.new(message)
-          end
-
           case event
           in Anthropic::Models::RawMessageStartEvent
-            # `coerce` returns `event.message` itself when it is already a Message (as does the
-            # first-event return above), so the snapshot *is* the message_start event's message
-            # and the branches below mutate it in place rather than an isolated copy.
+            # `coerce` returns `event.message` itself when it is already a Message, so the snapshot *is*
+            # the message_start event's message and the branches below mutate it in place rather than
+            # an isolated copy.
             return Anthropic::Internal::Type::Converter.coerce(Anthropic::Models::Message, event.message)
           in Anthropic::Models::BetaRawMessageStartEvent
             return Anthropic::Internal::Type::Converter.coerce(Anthropic::Models::BetaMessage, event.message)
@@ -316,6 +317,7 @@ module Anthropic
         # @api private
         #
         # Parse tool use blocks and text blocks with structured output in the message.
+        # A block is kept as it arrived, with only `parsed` added to it.
         #
         # @param message [Anthropic::Models::Message] The message to parse
         #
@@ -324,7 +326,7 @@ module Anthropic
           return message unless message&.content
 
           # rubocop:disable Metrics/BlockLength
-          message.content.each_with_index do |content, index|
+          message.content.each do |content|
             case content.type
             when :tool_use
               next unless (tool = @tools[content.name])
@@ -342,20 +344,7 @@ module Anthropic
                   e
                 end
 
-              cls =
-                case content
-                in Anthropic::ContentBlock
-                  Anthropic::Models::ToolUseBlock
-                else
-                  Anthropic::Models::BetaToolUseBlock
-                end
-              message.content[index] = cls.new(
-                id: content.id,
-                input: content.input,
-                name: content.name,
-                type: content.type,
-                parsed: parsed
-              )
+              content.parsed = parsed
             when :text
               next unless (model = @models.first&.last)
 
@@ -367,19 +356,7 @@ module Anthropic
                   {error: e.message}
                 end
 
-              cls =
-                case content
-                in Anthropic::ContentBlock
-                  Anthropic::Models::TextBlock
-                else
-                  Anthropic::Models::BetaTextBlock
-                end
-              message.content[index] = cls.new(
-                citations: content.citations,
-                text: content.text,
-                type: content.type,
-                parsed: parsed
-              )
+              content.parsed = parsed
             end
           end
           # rubocop:enable Metrics/BlockLength

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

@@ -122,8 +122,9 @@ module Anthropic
         # @return [Anthropic::Models::BetaMessage, nil]
         def next_message
           message = nil
-          fold do
-            message = @client.beta.messages.create(with_helper_header(_1, StainlessHelperHeader::BETA_TOOL_RUNNER))
+          fold do |params|
+            message =
+              @client.beta.messages.create(with_helper_header(params, StainlessHelperHeader::BETA_TOOL_RUNNER))
             [true, message]
           end
           message
@@ -132,7 +133,16 @@ module Anthropic
         # @return [Array<Anthropic::Models::BetaMessage>]
         def run_until_finished
           messages = []
-          each_streaming { messages << _1.accumulated_message }
+          # Not `each_streaming`: an error from this block is the runner's, not the application's.
+          fold do |params|
+            stream =
+              @client.beta.messages.stream(with_helper_header(params, StainlessHelperHeader::BETA_TOOL_RUNNER))
+            message = stream.accumulated_message
+            messages << message
+            [false, message]
+          ensure
+            stream&.close
+          end
           messages
         end
 
@@ -142,9 +152,10 @@ module Anthropic
             raise ArgumentError.new("A block must be given to ##{__method__}")
           end
 
-          fold do
-            message = @client.beta.messages.create(with_helper_header(_1, StainlessHelperHeader::BETA_TOOL_RUNNER))
-            blk.call(message)
+          fold do |params|
+            message =
+              @client.beta.messages.create(with_helper_header(params, StainlessHelperHeader::BETA_TOOL_RUNNER))
+            in_app { blk.call(message) }
             [false, message]
           end
         end
@@ -155,9 +166,10 @@ module Anthropic
             raise ArgumentError.new("A block must be given to ##{__method__}")
           end
 
-          fold do
-            stream = @client.beta.messages.stream(with_helper_header(_1, StainlessHelperHeader::BETA_TOOL_RUNNER))
-            blk.call(stream)
+          fold do |params|
+            stream =
+              @client.beta.messages.stream(with_helper_header(params, StainlessHelperHeader::BETA_TOOL_RUNNER))
+            in_app { blk.call(stream) }
             [false, stream.accumulated_message]
           ensure
             stream&.close
@@ -166,11 +178,74 @@ module Anthropic
 
         # @api private
         #
+        # Runs the runner's own code with the tool runner span current.
+        private def in_tool_runner(&blk)
+          otel_context = @tool_runner_otel_context
+          otel_context ? OpenTelemetry::Context.with_current(otel_context, &blk) : yield
+        end
+
+        # @api private
+        #
+        # @param raw [Object]
+        #
+        # @return [Array<Object>, String]
+        private def tool_result_content(raw) = raw.is_a?(Array) ? raw : raw.to_s
+
+        # @api private
+        #
+        # Runs the application's block in the context it started the loop from, where the tool runner
+        # span is not current. An error it raises is the application stopping the runner, except an API
+        # error: that is the stream the runner yielded failing as the application reads it.
+        private def in_app(&blk)
+          otel_context = @app_otel_context
+          otel_context ? OpenTelemetry::Context.with_current(otel_context, &blk) : yield
+        rescue Anthropic::Errors::APIError
+          raise
+        rescue StandardError
+          @stopped_by_app = true
+          raise
+        end
+
+        # @api private
+        #
+        # Runs one loop in its `anthropic.messages.tool_runner` span, which has no status when the
+        # application stops the loop.
+        #
         # @yieldparam [Array(Boolean, Anthropic::Models::Beta::MessageCreateParams)]
         private def fold(&blk)
           @compaction_phase = nil if @compaction_phase == :handling
           return nil if finished? && @pending_compaction.nil?
 
+          # A loop the application starts from inside another one has its own span.
+          outer = [@tool_runner_otel_context, @app_otel_context, @stopped_by_app]
+          @stopped_by_app = false
+          tool_runner_span = Anthropic::Helpers::Tracing.start_tool_runner_span(@client, params)
+          if tool_runner_span
+            @tool_runner_otel_context = OpenTelemetry::Trace.context_with_span(tool_runner_span)
+            # The application can start each loop from another context, so it is read on every entry.
+            @app_otel_context = OpenTelemetry::Context.current
+          else
+            @tool_runner_otel_context = @app_otel_context = nil
+          end
+          begin
+            value = in_tool_runner { run_loop(&blk) }
+            returned = true
+            value
+          rescue StandardError => e
+            error = e unless @stopped_by_app
+            raise
+          ensure
+            if tool_runner_span
+              Anthropic::Helpers::Tracing.end_tool_runner_span(tool_runner_span, returned: returned, error: error)
+            end
+            @tool_runner_otel_context, @app_otel_context, @stopped_by_app = outer
+          end
+        end
+
+        # @api private
+        #
+        # @yieldparam [Array(Boolean, Anthropic::Models::Beta::MessageCreateParams)]
+        private def run_loop(&blk)
           brk = false
           # rubocop:disable Metrics/BlockLength
           # rubocop:disable Style/CaseEquality
@@ -213,27 +288,42 @@ module Anthropic
             mapped =
               tool_uses.map do |tool_use|
                 resp = {type: :tool_result, tool_use_id: tool_use.id}
+                # The result of a toolset member's call has to name the toolset as the call does.
+                resp[:toolset_name] = tool_use[:toolset_name] if tool_use[:toolset_name].is_a?(String)
                 if available.include?(tool_use.name) &&
                    (tool = @tool_overrides.fetch(tool_use.name) do
                      tools.find do
                        _1.class.model === tool_use.parsed && Anthropic::Helpers::Messages.tool_api_name(_1) == tool_use.name
                      end
                    end)
+                  tool_use_span = Anthropic::Helpers::Tracing.start_tool_use_span(
+                    @client,
+                    tool,
+                    tool_use,
+                    params[:request_options]
+                  )
                   begin
                     # `parsed` was read against `params[:tools]`, which an added tool is not in.
                     input = tool_use.parsed
                     input = Anthropic::Internal::Type::Converter.coerce(tool, tool_use.input) if @tool_overrides.key?(tool_use.name)
-                    raw = tool.call(input)
+                    run = proc { tool.call(input) }
+                    raw = tool_use_span ? OpenTelemetry::Trace.with_span(tool_use_span, &run) : run.call
                     is_error = false
                   rescue StandardError => e
                     is_error = true
                     raw = e.message
+                  ensure
+                    if tool_use_span
+                      # `is_error` is unset when the run was interrupted, and then so is the span's status.
+                      result = {content: tool_result_content(raw), is_error:} unless is_error.nil?
+                      Anthropic::Helpers::Tracing.end_tool_use_span(@client, tool_use_span, tool_use.input, result)
+                    end
                   end
                 else
                   is_error = true
                   raw = "Error: parsed '#{tool_use.name}' not found"
                 end
-                content = raw.is_a?(Array) ? raw : raw.to_s
+                content = tool_result_content(raw)
                 {**resp, content:, is_error:}
               end
 
@@ -585,6 +675,9 @@ module Anthropic
           @tool_overrides = {}
           @pending_compaction = nil
           @compaction_phase = nil
+          @tool_runner_otel_context = nil
+          @app_otel_context = nil
+          @stopped_by_app = false
         end
 
         private def with_helper_header(params, helper)