anthropic 1.72.0 → 1.73.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e7aa200569945cdf76744a8c251b760350a75834328da86c44930b40f741b31
-  data.tar.gz: 780bb11d38658bb95e1142b1c389fc82e49ad04d20cdc4c01a9c4ed54b7038dd
+  metadata.gz: b0814f7989dfdce90cdc7535edcba2765bcbb40ed802424357334ff1087e860e
+  data.tar.gz: b3eef636f0f74f2d42c8d56c784461214c2575616afc4fbf5750f95affb325a0
 SHA512:
-  metadata.gz: 3de8eca81334145eaf72e0bfd8e142143ce8742e341db711085acac170f16132308f3c02fdaf424bdbc7e51d0832bc1de7a79e2abed18a2d80e57a92697c3b8c
-  data.tar.gz: 5994156c894b26d1cd0d504888f2cebc5409e4ff41bf81aa17f36f643e7de6c863ee831a34dc2ba49415f9fa531ab4456c33851d7655cb6461f36b7b39192074
+  metadata.gz: '0668735fb6de38f7ca8f71985eb642a7ec67b770317604c6a4bbfd5685a57aa6c4caf3c919b6571247c99ba51bdf6419ce59329b1e4ae6070ad271a8e7559fe4'
+  data.tar.gz: 237c52d786dbfe007938ad70ec8c54e888fad60bcab49c0f2eb48b4ad082252ddd2fbc76c65e7b777385efd0fe89775bf3c9f9e7dcc82ddc4847ceb1bf130930

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.73.0 (2026-09-22)
+
+Full Changelog: [v1.72.0...v1.73.0](https://github.com/anthropics/anthropic-sdk-ruby/compare/v1.72.0...v1.73.0)
+
+### Features
+
+* **api:** add support for claude-opus-5-5, inline tool definitions and MCP tool-list pinning (beta) ([b68ad25](https://github.com/anthropics/anthropic-sdk-ruby/commit/b68ad25d7e21c929b0a2309ba5c8ecc48f09fcfa))
+* **tools:** add compact_before_next_turn() to the tool runner ([#258](https://github.com/anthropics/anthropic-sdk-ruby/issues/258)) ([adccb26](https://github.com/anthropics/anthropic-sdk-ruby/commit/adccb26c933e2057794f903e41308d65108ecaff))
+
+
+### Bug Fixes
+
+* **api:** share one evaluated_permission enum across Managed Agents events ([5cea62a](https://github.com/anthropics/anthropic-sdk-ruby/commit/5cea62a855bec9f4cc991b2309b6934b9db987bf))
+* **tools:** add_tools takes effect straight away ([#269](https://github.com/anthropics/anthropic-sdk-ruby/issues/269)) ([289bfad](https://github.com/anthropics/anthropic-sdk-ruby/commit/289bfad23d1d26d0b86006f9aca7a624f8a86ce6))
+* **tools:** leave reply-only params off the tool runner's compaction request ([#267](https://github.com/anthropics/anthropic-sdk-ruby/issues/267)) ([5a1d7d2](https://github.com/anthropics/anthropic-sdk-ruby/commit/5a1d7d2352e7e4f65c312219c7a5695187ea2926))
+
+
+### Chores
+
+* **ci:** give the lint and breaking-change detection jobs more time ([59fc172](https://github.com/anthropics/anthropic-sdk-ruby/commit/59fc172c0f462de5743e947b6ec3c4708a5aac58))
+* **docs:** add descriptions to the Dreams API reference ([cfc7239](https://github.com/anthropics/anthropic-sdk-ruby/commit/cfc7239c607941094a470586342ed77cee41d75c))
+* **docs:** add descriptions to the User Profiles API reference ([cfc7239](https://github.com/anthropics/anthropic-sdk-ruby/commit/cfc7239c607941094a470586342ed77cee41d75c))
+* **docs:** add memory store descriptions to the Managed Agents API reference ([cfc7239](https://github.com/anthropics/anthropic-sdk-ruby/commit/cfc7239c607941094a470586342ed77cee41d75c))
+* **docs:** improve descriptions in the Dreams API reference ([54a81a7](https://github.com/anthropics/anthropic-sdk-ruby/commit/54a81a7c9f7fce043fafb342014144bf2a1bf050))
+* **docs:** simplify the session thread agent type description ([23d1d44](https://github.com/anthropics/anthropic-sdk-ruby/commit/23d1d4418dcf305366c48f144756071f173f909b))
+* **docs:** update diagnostics field descriptions on beta messages ([678a792](https://github.com/anthropics/anthropic-sdk-ruby/commit/678a7923359f8de6be74cffd9bbd1123df5e2cb9))
+* **internal:** let the typecheck task use every core, up to 16 ([f0ac300](https://github.com/anthropics/anthropic-sdk-ruby/commit/f0ac30052d083a8bf95c66a7c98a80985649c70d))
+
+
+### Documentation
+
+* add path and header parameter descriptions ([d458058](https://github.com/anthropics/anthropic-sdk-ruby/commit/d458058bfe901b540f5b346af63926d344c253dd))
+
 ## 1.72.0 (2026-09-18)
 
 Full Changelog: [v1.71.0...v1.72.0](https://github.com/anthropics/anthropic-sdk-ruby/compare/v1.71.0...v1.72.0)

data/README.md

@@ -15,7 +15,7 @@ Add to your application's Gemfile:
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "anthropic", "~> 1.72.0"
+gem "anthropic", "~> 1.73.0"
 ```
 
 <!-- x-release-please-end -->
@@ -33,7 +33,7 @@ anthropic = Anthropic::Client.new(
 message = anthropic.messages.create(
   max_tokens: 1024,
   messages: [{role: "user", content: "Hello, Claude"}],
-  model: "claude-opus-4-6"
+  model: "claude-opus-5-5"
 )
 
 puts(message.content)

data/lib/anthropic/helpers/messages.rb

@@ -35,54 +35,29 @@ module Anthropic
 
           case data
           in {tools: Array => tool_array}
-            # rubocop:disable Metrics/BlockLength
-            mapped = tool_array.map do |tool|
-              case tool
-              # Runnable tool instance (an `Anthropic::BaseTool` subclass, hand-written or helper-built):
-              in Anthropic::Helpers::Tools::BaseTool
-                name = tool_api_name(tool)
-                # Helper-built tools (e.g. MCP) declare an explicit `tool_name` and only send the
-                # description they were given; hand-written tools fall back to their name.
-                description = tool.class.doc_string
-                description ||= name unless tool.class.tool_name
-                tools.store(name, tool)
-                input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(tool)
-                # On a clash the derived keys win, so nothing in `tool_options` can shadow them.
-                definition =
-                  {name:, description:, input_schema:}
-                  .merge(tool.class.tool_options) { |_key, derived, _option| derived }
-                  .compact
-                definition.tap { _1.update(strict:) if strict }
-              # Input schema class used directly as a tool:
-              in Anthropic::Helpers::InputSchema::JsonSchemaConverter
-                name = model_name(tool.name)
-
-                description =
-                  case tool
-                  in Class if tool <= Anthropic::Helpers::InputSchema::BaseModel
-                    tool.doc_string || name
+            tool_array.replace(tool_array.map { tool_to_param(_1, tools:, strict:) })
+          else
+          end
+
+          # A `tool_addition` block defines a tool by value, in the shape of a `tools` entry.
+          case data
+          in {messages: Array => messages}
+            messages.each do |message|
+              case message
+              in {role: :system | "system", content: Array => blocks}
+                blocks.each do |block|
+                  case block
+                  in {
+                    type: :tool_addition | "tool_addition",
+                    tool: {type: :tool_definition | "tool_definition", definition:} => tool
+                  }
+                    tool.store(:definition, tool_to_param(definition, tools:, strict:))
                   else
-                    name
                   end
-
-                tools.store(name, tool)
-                input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(tool)
-                {name:, description:, input_schema:}.tap { _1.update(strict:) if strict }
-              # Tool with explicit name/description and BaseModel as input_schema:
-              in {name: String => name,
-                  input_schema: Anthropic::Helpers::InputSchema::JsonSchemaConverter => tool,
-                  **rest}
-                tools.store(name, tool)
-                input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(tool)
-                rest.merge(name:, input_schema:).tap { _1.update(strict:) if strict }
+                end
               else
-                # Any other format (pass through unchanged)
-                # This includes raw JSON schemas and any other tool definitions.
-                tool
               end
             end
-            # rubocop:enable Metrics/BlockLength
-            tool_array.replace(mapped)
           else
           end
 
@@ -212,6 +187,64 @@ module Anthropic
           data[:betas] = data[:betas].to_a.dup.push("structured-outputs-2025-12-15").uniq
         end
 
+        # @api private
+        #
+        # Convert one tool in any of the forms the helpers accept into a plain tool definition,
+        # recording under its name what `tool_use.input` is parsed back into.
+        #
+        # @param tool [Object]
+        #
+        # @param tools [Hash{String=>Class}]
+        #
+        # @param strict [Boolean, nil]
+        #
+        # @return [Object]
+        private def tool_to_param(tool, tools:, strict:)
+          case tool
+          # Runnable tool instance (an `Anthropic::BaseTool` subclass, hand-written or helper-built):
+          in Anthropic::Helpers::Tools::BaseTool
+            name = tool_api_name(tool)
+            # Helper-built tools (e.g. MCP) declare an explicit `tool_name` and only send the
+            # description they were given; hand-written tools fall back to their name.
+            description = tool.class.doc_string
+            description ||= name unless tool.class.tool_name
+            tools.store(name, tool)
+            input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(tool)
+            # On a clash the derived keys win, so nothing in `tool_options` can shadow them.
+            definition =
+              {name:, description:, input_schema:}
+              .merge(tool.class.tool_options) { |_key, derived, _option| derived }
+              .compact
+            definition.tap { _1.update(strict:) if strict }
+          # Input schema class used directly as a tool:
+          in Anthropic::Helpers::InputSchema::JsonSchemaConverter
+            name = model_name(tool.name)
+
+            description =
+              case tool
+              in Class if tool <= Anthropic::Helpers::InputSchema::BaseModel
+                tool.doc_string || name
+              else
+                name
+              end
+
+            tools.store(name, tool)
+            input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(tool)
+            {name:, description:, input_schema:}.tap { _1.update(strict:) if strict }
+          # Tool with explicit name/description and BaseModel as input_schema:
+          in {name: String => name,
+              input_schema: Anthropic::Helpers::InputSchema::JsonSchemaConverter => model,
+              **rest}
+            tools.store(name, model)
+            input_schema = Anthropic::Helpers::InputSchema::JsonSchemaConverter.to_json_schema(model)
+            rest.merge(name:, input_schema:).tap { _1.update(strict:) if strict }
+          else
+            # Any other format (pass through unchanged)
+            # This includes raw JSON schemas and any other tool definitions.
+            tool
+          end
+        end
+
         # @api private
         #
         # The `name` a runnable tool is serialized under in `tools[]`.

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

@@ -29,7 +29,24 @@ module Anthropic
         private_constant :RUN_TOOLS_STOP_REASONS, :RESUME_STOP_REASONS, :STOP_STOP_REASONS
 
         # @return [Anthropic::Models::Beta::MessageCreateParams]
-        attr_accessor :params
+        attr_reader :params
+
+        # @param params [Anthropic::Models::Beta::MessageCreateParams]
+        #
+        # @raise [ArgumentError] if `compaction` is set, if the messages are replaced while the
+        #   conversation is being compacted, or if a compaction edit is added while a compaction is due
+        def params=(params)
+          reject_compaction_param!(params)
+          if @compaction_phase == :in_flight && !params[:messages].equal?(current_messages)
+            raise ArgumentError.new(
+              "Message params can't be changed while the conversation is being compacted, because the " \
+              "compaction response replaces them. Make the change on the next iteration."
+            )
+          end
+          check_can_compact!(params) if @pending_compaction || @compaction_phase == :in_flight
+
+          @params = params
+        end
 
         # @return [Boolean]
         def finished? = @finished
@@ -39,17 +56,75 @@ module Anthropic
           self.params = {**params.to_h, messages: params[:messages].to_a + messages}
         end
 
+        # @api public
+        #
+        # Sends the tools' definitions in `tool_addition` blocks with the next request, leaving
+        # `params[:tools]` and the prompt cache alone. A `BaseTool` is run under its name straight away,
+        # replacing a same-name tool even for a call already in the message being handled; a raw
+        # definition is never run here and stops a same-name tool from running. Needs the
+        # `inline-tools-2026-09-15` beta.
+        #
+        # @param tools [Array<Anthropic::Helpers::Tools::BaseTool, Anthropic::Models::Beta::BetaToolUnion, Hash{Symbol=>Object}>]
+        def add_tools(*tools)
+          # Converted in place, so the originals are kept apart to pair each with its definition.
+          request = {tools: tools.dup}
+          Anthropic::Helpers::Messages.distill_input_schema_models!(request, strict: nil)
+          tools.zip(request.fetch(:tools)) do |tool, definition|
+            block = {type: :tool_addition, tool: {type: :tool_definition, definition:}}
+            runnable = tool if tool.is_a?(Anthropic::Helpers::Tools::BaseTool)
+            name = changed_tool_name(block.fetch(:tool))
+            @tool_overrides.store(name, runnable) unless name.nil?
+            @pending_tool_changes << block
+          end
+        end
+
+        # @api public
+        #
+        # Sends `tool_removal` blocks with the next request. The tools stop being run straight away,
+        # so a call to one gets the "not found" error result. Needs the `inline-tools-2026-09-15` beta.
+        #
+        # @param tools [Array<Anthropic::Helpers::Tools::BaseTool, String, Symbol>] the tools, or their names
+        def remove_tools(*tools)
+          tools.each do |tool|
+            name =
+              case tool
+              in Anthropic::Helpers::Tools::BaseTool
+                Anthropic::Helpers::Messages.tool_api_name(tool)
+              in String | Symbol
+                tool.to_s
+              end
+            @tool_overrides.store(name, nil)
+            @pending_tool_changes << {type: :tool_removal, tool: {type: :tool_reference, name:}}
+          end
+        end
+
+        # Compact the conversation before the model's next turn. Once the current turn has finished,
+        # including any tool calls, the runner asks the API for a summary and replaces its messages with
+        # the compaction response, which you get like any other message. Requires the
+        # `compact-2026-09-04` beta.
+        #
+        # @param compaction [Anthropic::Models::Beta::BetaCompactionConfig, Hash{Symbol=>Object}, nil]
+        #   the same config `messages.create(compaction:)` takes, `{type: :summarize}` when omitted
+        #
+        # @raise [ArgumentError] if `context_management` has a compaction edit
+        #
+        # @return [void]
+        def compact_before_next_turn(compaction = nil)
+          return unless @compaction_phase.nil?
+
+          check_can_compact!(params)
+          @pending_compaction = compaction || {type: :summarize}
+        end
+
         # @return [Array<Anthropic::Beta::BetaMessageParam>]
         private def current_messages = params&.[](:messages).to_a
 
         # @return [Anthropic::Models::BetaMessage, nil]
         def next_message
           message = nil
-          unless finished?
-            fold do
-              message = @client.beta.messages.create(with_helper_header(_1, StainlessHelperHeader::BETA_TOOL_RUNNER))
-              [true, message]
-            end
+          fold do
+            message = @client.beta.messages.create(with_helper_header(_1, StainlessHelperHeader::BETA_TOOL_RUNNER))
+            [true, message]
           end
           message
         end
@@ -93,13 +168,25 @@ module Anthropic
         #
         # @yieldparam [Array(Boolean, Anthropic::Models::Beta::MessageCreateParams)]
         private def fold(&blk)
-          return nil if finished?
+          @compaction_phase = nil if @compaction_phase == :handling
+          return nil if finished? && @pending_compaction.nil?
 
+          brk = false
           # rubocop:disable Metrics/BlockLength
           # rubocop:disable Style/CaseEquality
           loop do
+            break if finished?
             return if @max_iterations && @iteration_count >= @max_iterations
 
+            send_pending_tool_changes
+
+            if @pending_compaction && !turn_paused?
+              brk = compact(@pending_compaction, &blk)
+              break if brk
+              next
+            end
+
+            reject_compaction_param!(params)
             tools = params[:tools].to_a.grep(Anthropic::Helpers::Tools::BaseTool)
             messages = current_messages
             brk, response = blk.call(params)
@@ -121,21 +208,27 @@ module Anthropic
               break
             end
 
-            tool_uses =
-              next_step == :run_tools ? response.content.grep(Anthropic::Beta::BetaToolUseBlock) : []
+            tool_uses = next_step == :run_tools ? client_tool_uses(response) : []
 
             # 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)
+            available = available_tool_names([*tools, *@tool_overrides.values.compact])
 
             mapped =
               tool_uses.map do |tool_use|
                 resp = {type: :tool_result, tool_use_id: tool_use.id}
                 if available.include?(tool_use.name) &&
-                   (tool = tools.find { _1.class.model === tool_use.parsed })
+                   (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)
                   begin
-                    raw = tool.call(tool_use.parsed)
+                    # `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)
                     is_error = false
                   rescue StandardError => e
                     is_error = true
@@ -154,20 +247,7 @@ module Anthropic
               break
             end
 
-            content = response.content.map do
-              case _1
-              in Anthropic::Beta::BetaToolUseBlock
-                # `parsed` is only set for calls to a declared tool; any other call (e.g. to an
-                # unregistered tool) must replay the `input` the API sent, never a null.
-                input = _1.parsed.nil? ? _1.input : _1.parsed
-                raw = {**_1, input:}.except(:parsed)
-                Anthropic::Internal::Type::Converter.dump(Anthropic::Beta::BetaToolUseBlock, raw)
-              else
-                _1
-              end
-            end
-
-            messages << {role: :assistant, content:}
+            messages << assistant_turn(response)
             messages << {role: :user, content: mapped} unless mapped.empty?
             adopt_container(response)
 
@@ -177,6 +257,199 @@ module Anthropic
           end
           # rubocop:enable Style/CaseEquality
           # rubocop:enable Metrics/BlockLength
+
+          compact_after_final_turn(&blk) if finished? && !brk
+          nil
+        end
+
+        # @api private
+        #
+        # @param response [Anthropic::Models::BetaMessage]
+        #
+        # @return [Hash{Symbol=>Object}]
+        private def assistant_turn(response)
+          content = response.content.map do
+            case _1
+            # The class alone doesn't make a block a tool call, see `#client_tool_uses`.
+            in Anthropic::Beta::BetaToolUseBlock if block_type(_1) == :tool_use
+              # `parsed` is only set for calls to a declared tool; any other call (e.g. to an
+              # unregistered tool) must replay the `input` the API sent, never a null. So must a
+              # tool `add_tools` / `remove_tools` changed: `parsed` came from `params[:tools]`.
+              input = _1.parsed.nil? || @tool_overrides.key?(_1.name) ? _1.input : _1.parsed
+              raw = {**_1, input:}.except(:parsed)
+              Anthropic::Internal::Type::Converter.dump(Anthropic::Beta::BetaToolUseBlock, raw)
+            else
+              _1
+            end
+          end
+
+          {role: :assistant, content:}
+        end
+
+        # @api private
+        #
+        # A block of a type this SDK version doesn't know is coerced to the closest model, which can
+        # be `BetaToolUseBlock`, so the class alone doesn't make a block a tool call.
+        #
+        # @param response [Anthropic::Models::BetaMessage]
+        #
+        # @return [Array<Anthropic::Beta::BetaToolUseBlock>]
+        private def client_tool_uses(response)
+          response.content.grep(Anthropic::Beta::BetaToolUseBlock).select { block_type(_1) == :tool_use }
+        end
+
+        # @api private
+        #
+        # @param block [Anthropic::Models::Beta::BetaContentBlock, Hash{Symbol=>Object}]
+        #
+        # @return [Symbol, nil]
+        private def block_type(block) = read_field(block, :type)&.to_sym
+
+        # @api private
+        #
+        # @param params [Anthropic::Models::Beta::MessageCreateParams]
+        private def reject_compaction_param!(params)
+          return if params[:compaction].nil?
+
+          raise ArgumentError.new(
+            "`compaction` cannot be set on a tool runner: every request in the loop would compact again. " \
+            "Call `#compact_before_next_turn` when the conversation should be compacted instead."
+          )
+        end
+
+        # @api private
+        #
+        # @param params [Anthropic::Models::Beta::MessageCreateParams]
+        private def check_can_compact!(params)
+          # The compaction request is sent without `context_management`, so the API can't reject this
+          # combination there: it would run and bill the compaction, then reject the next request,
+          # where the compaction response and the compaction edit meet.
+          edits = read_field(params[:context_management], :edits)
+          return unless Array(edits).any? { read_field(_1, :type).to_s.start_with?("compact_") }
+
+          raise ArgumentError.new(
+            "`#compact_before_next_turn` can't be used while `context_management` has a compaction edit, " \
+            "because the API doesn't accept a compaction block together with one. Remove the edit first."
+          )
+        end
+
+        # @api private
+        #
+        # The API can't compact a conversation that ends mid-turn, so a paused turn is resumed first.
+        #
+        # @return [Boolean]
+        private def turn_paused?
+          !@last_response.nil? && determine_next_step_from_stop_reason(@last_response.stop_reason) == :resume
+        end
+
+        # @api private
+        #
+        # @param compaction [Anthropic::Models::Beta::BetaCompactionConfig, Hash{Symbol=>Object}]
+        #
+        # @return [Boolean] whether the caller asked for a single message
+        private def compact(compaction, &blk)
+          check_can_compact!(params)
+          request = {**without_compaction_incompatible_params(params), compaction:}
+          @pending_compaction = nil
+          @compaction_phase = :in_flight
+
+          brk, response = blk.call(request)
+
+          if response.content.any? { block_type(_1) == :compaction && !read_field(_1, :content).to_s.empty? }
+            keep_removals_from_history
+            # The response has to be sent back as it came, first, replacing the messages it summarizes.
+            @params = {**params.to_h, messages: [assistant_turn(response)]}
+          else
+            warn("[anthropic-ruby] Compaction produced no summary; keeping the conversation as it is.")
+          end
+          # `#next_message` hands the response over only now; its caller is looking at it until the
+          # runner is next advanced, which is when `#fold` clears this.
+          @compaction_phase = :handling if brk
+          brk
+        ensure
+          @compaction_phase = nil if @compaction_phase == :in_flight
+        end
+
+        # @api private
+        #
+        # A compaction request returns only the compaction block, never a reply, so the API rejects
+        # the params that only shape a reply. The runner's later requests keep them.
+        #
+        # @param params [Anthropic::Models::Beta::MessageCreateParams, Hash{Symbol=>Object}]
+        #
+        # @return [Hash{Symbol=>Object}]
+        private def without_compaction_incompatible_params(params)
+          kept = params.to_h.except(:context_management, :stop_sequences, :output_format)
+          forced_tool = [:any, :tool].include?(read_field(kept[:tool_choice], :type)&.to_sym)
+          kept = without_output_format(forced_tool ? kept.except(:tool_choice) : kept)
+          return kept unless kept[:fallbacks].is_a?(Array)
+
+          fallbacks = kept[:fallbacks].map do
+            fallback = Anthropic::Internal::Type::Converter.dump(Anthropic::Beta::BetaFallbackParam, _1)
+            without_output_format(fallback)
+          end
+          {**kept, fallbacks:}
+        end
+
+        # @api private
+        #
+        # @param params [Hash{Symbol=>Object}] a request's params, or one of its fallbacks'
+        #
+        # @return [Hash{Symbol=>Object}]
+        private def without_output_format(params)
+          # Read in its wire form: a typed `BetaOutputConfig` holds `format` under its Ruby name, `format_`.
+          dumped = Anthropic::Internal::Type::Converter.dump(
+            Anthropic::Beta::BetaOutputConfig,
+            params[:output_config]
+          )
+          output_config = dumped.to_h.except(:format)
+          output_config.empty? ? params.except(:output_config) : {**params, output_config:}
+        end
+
+        # @api private
+        private def compact_after_final_turn(&blk)
+          return if @pending_compaction.nil?
+
+          # The loop never adds the final turn to the history, so it is added here for the compaction
+          # to cover it, and forgotten so that a later compaction doesn't add it again.
+          unless @last_response.nil?
+            if client_tool_uses(@last_response).any?
+              # A turn that was cut short can end with tool calls that are never run, and the API
+              # can't compact a conversation whose last turn has an unanswered tool call.
+              warn(
+                "[anthropic-ruby] The pending compaction was skipped because the last turn " \
+                "(stop_reason: #{@last_response.stop_reason.inspect}) ended with tool calls that " \
+                "were not run. Call `#compact_before_next_turn` again if you continue the conversation."
+              )
+              @pending_compaction = nil
+              return
+            end
+
+            current_messages << assistant_turn(@last_response)
+            @last_response = nil
+          end
+
+          compact(@pending_compaction, &blk)
+        end
+
+        # @api private
+        #
+        # A paused turn is sent back as it came, so nothing may follow it.
+        private def send_pending_tool_changes
+          return if @pending_tool_changes.empty? || @last_response&.stop_reason == :pause_turn
+
+          current_messages << {role: :system, content: @pending_tool_changes}
+          @pending_tool_changes = []
+        end
+
+        # @api private
+        #
+        # A compaction response replaces the history, `tool_removal` blocks included, so what the
+        # history took away is taken out of the overrides first.
+        private def keep_removals_from_history
+          runnable = [*params[:tools].to_a.grep(Anthropic::Helpers::Tools::BaseTool), *@tool_overrides.values.compact]
+          names = runnable.map { Anthropic::Helpers::Messages.tool_api_name(_1) }
+          (names - available_tool_names(runnable).to_a).each { @tool_overrides.store(_1, nil) }
         end
 
         # @api private
@@ -219,16 +492,15 @@ module Anthropic
         #
         # 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.
+        # server-executed and never dispatched here, so they are ignored. The overrides already
+        # hold the changes waiting to be sent, so those count as the history's last message.
         #
         # @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)
+        private def available_tool_names(tools)
           available = Set.new(tools.map { Anthropic::Helpers::Messages.tool_api_name(_1) })
-          messages.each do |message|
+          [*current_messages, {role: :system, content: @pending_tool_changes}].each do |message|
             next unless read_field(message, :role)&.to_sym == :system
 
             Array(read_field(message, :content)).each { apply_tool_change(_1, available) }
@@ -244,10 +516,10 @@ module Anthropic
         private def apply_tool_change(block, available)
           case read_field(block, :type)&.to_sym
           in :tool_removal
-            name = referenced_tool_name(read_field(block, :tool))
+            name = changed_tool_name(read_field(block, :tool))
             available.delete(name) unless name.nil?
           in :tool_addition
-            name = referenced_tool_name(read_field(block, :tool))
+            name = changed_tool_name(read_field(block, :tool))
             available.add(name) unless name.nil?
           else
             nil # non tool_removal / tool_addition blocks leave the set untouched
@@ -256,13 +528,16 @@ module Anthropic
 
         # @api private
         #
-        # @param ref [Anthropic::Beta::BetaToolChangeToolReference, Hash{Symbol=>Object}, nil]
+        # @param tool [Anthropic::Beta::BetaToolChangeToolReference, Anthropic::Beta::BetaToolChangeToolDefinitionParam, Hash{Symbol=>Object}, nil]
         #
         # @return [String, nil]
-        private def referenced_tool_name(ref)
-          case read_field(ref, :type)&.to_sym
+        private def changed_tool_name(tool)
+          case read_field(tool, :type)&.to_sym
           in :tool_reference
-            read_field(ref, :name).to_s
+            read_field(tool, :name).to_s
+          in :tool_definition
+            # Not every `tools[]` entry has a name (e.g. `mcp_toolset`); those never run here.
+            read_field(read_field(tool, :definition), :name)&.to_s
           else
             nil # `mcp_*` references run server-side; unknown types ignored (forward compatibility)
           end
@@ -403,12 +678,17 @@ module Anthropic
         def initialize(client, params:, max_iterations: nil, compaction_control: nil)
           @client = client
           @params = params.to_h
+          reject_compaction_param!(@params)
           @finished = false
           @max_iterations = max_iterations
           @iteration_count = 0
           @compaction_control = compaction_control
           @compaction_warned = false
           @last_response = nil
+          @pending_tool_changes = []
+          @tool_overrides = {}
+          @pending_compaction = nil
+          @compaction_phase = nil
         end
 
         private def with_helper_header(params, helper)