activeagent 1.8.0 → 1.9.0

data/lib/active_agent/providers/_base_provider.rb

@@ -2,7 +2,9 @@ require "active_support/delegation"
 
 require_relative "common/response"
 require_relative "concerns/exception_handler"
+require_relative "concerns/input_requests"
 require_relative "concerns/instrumentation"
+require_relative "concerns/mcp_serving"
 require_relative "concerns/previewable"
 require_relative "concerns/tool_choice_clearing"
 
@@ -14,13 +16,28 @@ GEM_LOADERS = {
   ruby_llm:  [ "ruby_llm",  [ ">= 1.16", "< 3" ], "ruby_llm" ]
 }
 
+# Gems that define the same top-level constant as the client a provider asks
+# for. A bundle can then look like it already satisfies the provider while the
+# gem it actually needs is missing.
+#
+# `openai` and `ruby-openai` both define `OpenAI`, and only the former carries
+# the typed request models every OpenAI-family provider is written against — so
+# "add the openai gem" reads as nonsense to someone whose bundle already has an
+# `OpenAI` constant.
+#
+# @private
+GEM_CONFLICTS = {
+  openai: { gem: "ruby-openai", constant: "OpenAI" }
+}.freeze
+
 # Requires a provider's gem dependency.
 #
 # @param type [Symbol] provider type (:anthropic, :openai)
 # @param file_name [String] for error context
 # @return [void]
-# @raise [LoadError] when the gem is not installed, or when the loaded
-#   version is outside the supported range
+# @raise [LoadError] when the gem is not installed, when the loaded version is
+#   outside the supported range, or when something else already defines the
+#   client constant
 def require_gem!(type, file_name)
   gem_name, requirement, package_name = GEM_LOADERS.fetch(type)
   requirements = Array(requirement)
@@ -36,10 +53,58 @@ def require_gem!(type, file_name)
                        "Add `gem \"#{gem_name}\", #{requirements.map(&:inspect).join(', ')}` to your Gemfile and run `bundle update #{gem_name}`."
     end
 
+    if (conflict = gem_conflict_for(type))
+      if conflict[:gem]
+        raise LoadError, "#{provider_name} needs the '#{gem_name}' gem, but this bundle has '#{conflict[:gem]}'. " \
+                         "Both define #{conflict[:constant]}, so the two cannot be installed together — " \
+                         "replace `gem \"#{conflict[:gem]}\"` with `gem \"#{gem_name}\"` in your Gemfile and run `bundle install`."
+      end
+
+      where = conflict[:file] ? "in #{conflict[:file]}" : "elsewhere"
+      raise LoadError, "#{provider_name} needs the '#{gem_name}' gem, which defines #{conflict[:constant]}, " \
+                       "but #{conflict[:constant]} is already defined #{where}. " \
+                       "Rename or remove that definition, then add `gem \"#{gem_name}\"` to your Gemfile and run `bundle install`."
+    end
+
     raise LoadError, "The '#{gem_name}' gem is required for #{provider_name}. Please add it to your Gemfile and run `bundle install`."
   end
 end
 
+# Finds what already defines the constant the provider's client gem needs,
+# when that is not the gem itself.
+#
+# @param type [Symbol] provider type
+# @return [Hash, nil] `{ gem:, constant: }` when the conflicting gem in
+#   GEM_CONFLICTS is present, `{ constant:, file: }` when something else
+#   defines the constant (`file` is nil when Ruby cannot tell where), or nil
+# @api private
+def gem_conflict_for(type)
+  conflict = GEM_CONFLICTS[type]
+  return unless conflict
+  return conflict if Gem.loaded_specs.key?(conflict[:gem])
+
+  # With the provider's own gem activated, requiring it is what failed. The
+  # gem may have defined the constant itself before failing, and a clash with
+  # a definition from anywhere else raises TypeError, not LoadError.
+  return if Gem.loaded_specs.key?(GEM_LOADERS.fetch(type).first)
+
+  constant = conflict[:constant]
+  location = Object.const_source_location(constant)
+  return unless location
+
+  # `const_source_location` places a pending autoload, which is how Zeitwerk
+  # defines an application's constants, at the line that registered it rather
+  # than in the file that will define the constant.
+  file = Object.autoload?(constant) || location.first
+
+  # RubyGems installs a gem into a directory named `<name>-<version>`
+  # (`ruby-openai-8.3.0`), so the path identifies the gem even when its files
+  # were loaded without activating it.
+  return conflict if file&.match?(%r{/#{Regexp.escape(conflict[:gem])}-\d[^/]*/})
+
+  { constant: constant, file: file }
+end
+
 module ActiveAgent
   module Providers
     # Orchestrates LLM provider API requests, streaming, and multi-turn tool calling.
@@ -54,22 +119,24 @@ module ActiveAgent
       extend ActiveSupport::Delegation
 
       include ExceptionHandler
+      include InputRequests
       include Instrumentation
+      include MCPServing
       include Previewable
       include ToolChoiceClearing
 
       class ProvidersError < StandardError; end
 
-      attr_internal :options, :context, :trace_id,   # Setup
-                    :request, :message_stack,        # Runtime
-                    :stream_broadcaster, :streaming, # Callback (Streams)
-                    :stream_completion_pending,      # Callback (Streams)
-                    :stream_completion_result,       # Callback (Streams)
-                    :tools_function,                 # Callback (Tools)
-                    :usage_stack,                    # Usage Tracking
-                    :stream_usage_index,             # Usage Tracking (Streams)
-                    :max_tool_turns, :tool_turns,    # Tool-loop safety
-                    :instrumentation_enabled        # Per-generation privacy
+      attr_internal :options, :context, :trace_id,      # Setup
+                    :request, :message_stack,          # Runtime
+                    :stream_broadcaster, :streaming,   # Callback (Streams)
+                    :stream_completion_pending,        # Callback (Streams)
+                    :stream_completion_result,         # Callback (Streams)
+                    :tools_function,                   # Callback (Tools)
+                    :usage_stack,                      # Usage Tracking
+                    :stream_usage_index,               # Usage Tracking (Streams)
+                    :max_tool_turns, :tool_turns,      # Tool-loop safety
+                    :instrumentation_enabled          # Per-generation privacy
 
       # Upper bound on tool-calling round-trips within one generation. A
       # model that keeps emitting tool calls otherwise recurses until the
@@ -128,6 +195,10 @@ module ActiveAgent
         self.max_tool_turns     = kwargs.delete(:max_tool_turns) || DEFAULT_MAX_TOOL_TURNS
         self.tool_turns         = 0
         self.instrumentation_enabled = kwargs.delete(:instrumentation) != false
+        self.generation_action_name  = kwargs.delete(:action_name)
+        self.tool_approvals          = normalize_tool_approvals(kwargs.delete(:requires_approval))
+        self.input_request_resume    = kwargs.delete(:input_request_resume)
+        self.announce_input_requests = kwargs.delete(:announce_input_requests) != false
         self.options            = options_klass.new(kwargs.extract!(*options_klass.keys))
         self.context            = kwargs
         self.message_stack      = []
@@ -141,22 +212,29 @@ module ActiveAgent
       #
       # @return [String] markdown-formatted preview
       def preview
-        self.request = prompt_request_type.cast(context.except(:trace_id))
+        self.request = prompt_request_type.cast(preview_context.except(:trace_id))
         preview_prompt
       end
 
       # Executes prompt request with error handling and instrumentation.
       #
+      # The generation is wrapped so that a client-side MCP bridge is released
+      # however it ends. A bridged server holds a live connection — for a
+      # `command:` server, a process — and the tool loop that uses it finishes
+      # here, inside `resolve_prompt`, streaming included.
+      #
       # @return [ActiveAgent::Providers::Common::PromptResponse]
       def prompt
-        self.request = prompt_request_type.cast(context.except(:trace_id))
+        self.request = prompt_request_type.cast(prompt_context.except(:trace_id))
 
         instrument("prompt.active_agent") do |payload|
-          response = resolve_prompt
+          response = input_request_resume ? resume_prompt : resolve_prompt
           instrumentation_prompt_payload(payload, request, response)
 
           response
         end
+      ensure
+        mcp_release_bridge!
       end
 
       # Executes embedding request with error handling and instrumentation.
@@ -175,6 +253,40 @@ module ActiveAgent
 
       protected
 
+      # Request parameters for a real prompt, with `mcps:` resolved.
+      #
+      # Declarations the provider can serve itself are left in `mcps:` for it to
+      # translate; the rest are served client-side by {MCPServing}, which exposes
+      # their tools as ordinary tools the provider can already call.
+      #
+      # @return [Hash]
+      def prompt_context = mcp_resolved_context
+
+      # Request parameters for a preview, which resolves no client-side server:
+      # discovering a server's tools means connecting to it, and a preview must
+      # not perform I/O.
+      #
+      # @return [Hash]
+      def preview_context = mcp_preview_context
+
+      # Invokes a tool, on an MCP server when one provides it and on the agent's
+      # own tool function otherwise.
+      #
+      # @param name [String] tool name
+      # @param kwargs [Hash] tool arguments
+      # @return [Object] the tool's result, or an {MCPBridge::ErrorResult} for
+      #   a call that failed on an MCP server
+      # @raise [ActiveAgent::InputRequest::UnsupportedProviderError] when the
+      #   tool needs approval and the provider's tool loop never asked for it
+      def call_tool_function(name, **kwargs)
+        assert_approval_gate_reached!(name)
+        return mcp_call_tool(name, **kwargs) if mcp_owns_tool?(name)
+
+        result = isolate_undispatched_tool_call { tools_function.call(name, **kwargs) }
+        assert_input_request_supported!(result)
+        result
+      end
+
       # @param name [String, nil]
       # @raise [RuntimeError] when service name doesn't match provider
       def assert_service!(name)
@@ -463,6 +575,8 @@ module ActiveAgent
 
         if (tool_calls = process_prompt_finished_extract_function_calls)&.any? && tool_turn_allowed?
           process_function_calls(tool_calls)
+          return paused_prompt_response(api_response) if awaiting_input?
+
           resolve_prompt
         else
 
@@ -471,25 +585,33 @@ module ActiveAgent
           # as they continue to work.
           broadcast_stream_close
 
-          # To convert the messages into common format we first need to merge the current
-          # stack and then cast them to the provider type, so we can cast them out to common.
-          messages = prompt_request_type.cast(
-            messages: [ *request.messages, *message_stack ]
-          ).messages
-
-          # Create response object with usage_stack array for multi-turn cumulative tracking.
-          # This will returned as it closes up the recursive stack
-          Common::PromptResponse.new(
-            context:,
-            format: request.response_format,
-            messages:,
-            raw_request:  prompt_request_type.serialize(request),
-            raw_response: api_response,
-            usages: usage_stack
-          )
+          build_prompt_response(api_response)
         end
       end
 
+      # @param api_response [Object, nil] provider-specific response
+      # @param attributes [Hash] further response attributes
+      # @return [Common::PromptResponse]
+      def build_prompt_response(api_response, **attributes)
+        # To convert the messages into common format we first need to merge the current
+        # stack and then cast them to the provider type, so we can cast them out to common.
+        messages = prompt_request_type.cast(
+          messages: [ *request.messages, *message_stack ]
+        ).messages
+
+        # Create response object with usage_stack array for multi-turn cumulative tracking.
+        # This will returned as it closes up the recursive stack
+        Common::PromptResponse.new(
+          context:,
+          format: request.response_format,
+          messages:,
+          raw_request:  prompt_request_type.serialize(request),
+          raw_response: api_response,
+          usages: usage_stack,
+          **attributes
+        )
+      end
+
       # Counts a tool round-trip against the per-generation cap. When the
       # cap is hit the loop finishes cleanly with the messages gathered so
       # far (a partial result) instead of recursing indefinitely.

data/lib/active_agent/providers/anthropic/transforms.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/hash/deep_merge"
 require "active_support/core_ext/hash/keys"
 
 module ActiveAgent
@@ -11,6 +12,13 @@ module ActiveAgent
       # - Expand: shortcuts → API format (string → content blocks, consecutive messages → grouped)
       # - Compress: API format → shortcuts (single content blocks → strings for efficiency)
       module Transforms
+        # Keys Anthropic accepts on a request message. `MessageParam` carries
+        # `role` and `content`; the beta `BetaMessageParam` adds `clear_at` and
+        # `output_config`, both of which it permits only on `role: "system"`
+        # messages. `clear_at` is the enum `next_user_message`/`never` — a
+        # timestamp is not a value the API takes.
+        MESSAGE_PARAM_KEYS = %i[role content clear_at output_config].freeze
+
         class << self
           # Converts gem model object to hash via JSON round-trip.
           #
@@ -34,7 +42,14 @@ module ActiveAgent
             # Normalize json_schema response_format → output_config (Anthropic's native structured output field)
             if params[:response_format]
               output_config = normalize_response_format(params.delete(:response_format))
-              params[:output_config] = output_config if output_config
+
+              # Merge rather than replace: `output_config` also carries `effort`,
+              # and a caller who sets both expects both. The caller's own keys
+              # win, being the more explicit of the two. A caller-supplied
+              # `output_config` with no `response_format` is left untouched, and
+              # nothing is written when there is neither — the gem rejects an
+              # explicit nil here.
+              params[:output_config] = output_config.deep_merge(params[:output_config] || {}) if output_config
             end
 
             # Handle mcps parameter (common format) -> transforms to mcp_servers (provider format)
@@ -222,13 +237,19 @@ module ActiveAgent
           #
           # Supported (ActiveAgent common format):
           #   { type: "json_schema", json_schema: { name: "...", schema: {...}, strict: true } }
+          #   { type: "json_schema", name: "...", schema: {...}, strict: true }
           # → { format: { type: "json_schema", schema: {...} } }
           #
           # Notes:
+          # - The schema is read from the top level or from +json_schema+, as the
+          #   OpenAI transforms do; a top-level schema wins.
+          # - Anthropic's `format.type` is only ever `json_schema`, and `schema`
+          #   is required, so anything else has no output_config to build.
           # - Anthropic requires `additionalProperties: false` on all object schemas.
           #   This is auto-injected into any object schemas that don't have it set.
           # - Anthropic does not use OpenAI's `name` or `strict` fields in output_config.format.
-          # - json_object is not handled here; it remains prompt-emulated.
+          # - json_object is not handled here; it remains prompt-emulated, because
+          #   Anthropic has no schema-less JSON mode to request.
           # - text is not handled here; Anthropic returns plain text by default.
           #
           # @param format [Hash, Symbol, String] ActiveAgent common response_format
@@ -239,25 +260,24 @@ module ActiveAgent
               format_hash = format.deep_symbolize_keys
 
               if format_hash[:type].to_s == "json_schema"
-                schema = format_hash[:json_schema]&.dig(:schema)
-                if schema
-                  schema = inject_additional_properties(schema.deep_dup)
-                end
-                {
-                  format: {
-                    type: "json_schema",
-                    schema: schema
-                  }.compact
-                }
-              elsif format_hash[:type].to_s == "json_object"
-                # json_object is not handled here; it remains prompt-emulated.
-                nil
-              elsif format_hash[:type].to_s == "text"
-                # text is not handled here; it remains prompt-emulated.
-                nil
-              else
-                # Pass through (already properly structured or Anthropic native format)
+                # A named schema (a String) is resolved to its Hash by the prompt
+                # layer before it reaches here, so anything that is not a Hash
+                # carries no inline schema to send. The schema sits at the top
+                # level in the flat shape, or under +json_schema+.
+                json_schema = format_hash[:json_schema]
+                schema = format_hash[:schema]
+                schema = json_schema[:schema] if schema.nil? && json_schema.is_a?(Hash)
+                return nil unless schema
+
+                { format: { type: "json_schema", schema: inject_additional_properties(schema.deep_dup) } }
+              elsif format_hash.key?(:format)
+                # Already in Anthropic's own output_config shape; pass it through.
                 format_hash
+              else
+                # `json_object`, `text`, and anything else: there is no
+                # output_config to build. Sending one would be rejected, so a
+                # schema-less json_schema falls back rather than 400s.
+                nil
               end
             when Symbol, String
               # Bare :json_schema without a schema cannot use native output_config.
@@ -570,16 +590,25 @@ module ActiveAgent
           # @param gem_object [Object] original gem object (unused but for consistency)
           # @return [Hash] cleaned request hash
           def cleanup_serialized_request(hash, defaults, gem_object = nil)
-            # Remove response-only fields from messages
+            # Reduce every message to the keys a request message may carry.
+            #
+            # Anthropic returns response-only fields on every message, and
+            # multi-turn requests plus the json_object emulation retry re-submit
+            # prior assistant responses verbatim, so each one would otherwise be
+            # sent straight back and rejected with
+            # "messages.N.<field>: Extra inputs are not permitted".
+            #
+            # An allowlist rather than a denylist because the response model
+            # keeps growing: `container` and then `diagnostics` each arrived in a
+            # gem release, and the beta API adds `context_management` and
+            # `input_transformations` beyond both. Enumerating the fields the
+            # request accepts cannot fall behind that way.
+            #
+            # The request-level `container` parameter is a separate, valid field
+            # and is deliberately left alone.
             if hash[:messages]
               hash[:messages].each do |msg|
-                msg.delete(:id)
-                msg.delete(:model)
-                msg.delete(:stop_reason)
-                msg.delete(:stop_sequence)
-                msg.delete(:stop_details)
-                msg.delete(:type)
-                msg.delete(:usage)
+                msg.select! { |key, _| MESSAGE_PARAM_KEYS.include?(key) }
               end
             end
 

data/lib/active_agent/providers/anthropic_provider.rb

@@ -20,6 +20,24 @@ module ActiveAgent
       # Lead-in message for JSON response format emulation
       JSON_RESPONSE_FORMAT_LEAD_IN = "Here is the JSON requested:\n{"
 
+      # Models that accept a prefilled response: Claude Haiku 4.5, Sonnet 4.5,
+      # Opus 4.5, Opus 4.1, Opus 4, Sonnet 4 and the Claude 3 family. Every model
+      # from Claude Opus 4.6 and Sonnet 4.6 on refuses one, with or without
+      # thinking, so a new model needs no entry here.
+      #
+      # An id matches in its Anthropic form (`claude-sonnet-4-5`, with a dated
+      # snapshot or `-latest`), its Amazon Bedrock form (`anthropic.` or a region
+      # prefix such as `us.anthropic.`, and a `-v1:0` suffix) and its Vertex AI
+      # form (`claude-sonnet-4-5@20250929`). A family name must be followed by
+      # the end of the id or one of those suffixes, so `claude-opus-4` matches
+      # `claude-opus-4-20250514` but not `claude-opus-4-6`.
+      PREFILL_MODELS = /
+        \A(?:(?:[a-z-]+\.)?anthropic\.)?claude-
+        (?:3-(?:haiku|sonnet|opus)|3-5-(?:haiku|sonnet)|3-7-sonnet|
+           (?:opus|sonnet)-4(?:-0)?|opus-4-1|(?:haiku|sonnet|opus)-4-5)
+        (?=\z|@|-(?:\d{8}|latest|v\d))
+      /x
+
       attr_internal :json_format_retry_count
 
       def initialize(kwargs = {})
@@ -34,6 +52,14 @@ module ActiveAgent
         ::Anthropic::Client.new(**options.serialize)
       end
 
+      # Anthropic takes remote MCP servers through `mcp_servers`, so those are
+      # served by the provider as they always were — its own tool loop, with no
+      # tool schemas in the prompt. It cannot be handed a local process, so a
+      # `command:` declaration runs client-side instead.
+      #
+      # @return [Array<Symbol>]
+      def mcp_native_transports = [ :url ]
+
       protected
 
       # Removes forced tool choice after first use to prevent endless looping.
@@ -77,9 +103,19 @@ module ActiveAgent
         [ true, tool_name ]
       end
 
+      # Emulates the json_object response format. When {#json_object_prefill?}
+      # holds, the request ends on an assistant turn holding
+      # {JSON_RESPONSE_FORMAT_LEAD_IN}, so the model continues an object that is
+      # already open.
+      #
+      # Every other request is sent without the lead-in, and only its prompt
+      # asks for JSON. {Common::Messages::Assistant#parsed_json} then finds the
+      # object in the answer, inside a Markdown code fence or not.
+      #
       # @api private
       def prepare_prompt_request_response_format
         return unless request.response_format&.dig(:type) == "json_object"
+        return unless json_object_prefill?
 
         self.message_stack.push({
           role:    "assistant",
@@ -87,6 +123,33 @@ module ActiveAgent
         })
       end
 
+      # Whether the json_object emulation prefills the answer with the lead-in:
+      # only for a model in {PREFILL_MODELS}, and only with thinking off, since
+      # a prefill is refused while thinking is on. A missing or unrecognised
+      # model id gets no prefill, because every model accepts a request without
+      # one.
+      #
+      # @return [Boolean]
+      def json_object_prefill?
+        PREFILL_MODELS.match?(request.model.to_s) && !thinking_enabled?
+      end
+
+      # Whether the request turns thinking on, in any mode: a manual budget
+      # (`enabled`), `adaptive`, or any other type but `disabled`.
+      #
+      # The type is read from the request as serialized. An anthropic gem older
+      # than a thinking type coerces it into another variant, whose `type`
+      # reader can then disagree with what is sent: anthropic 1.12 holds
+      # `adaptive` in a `ThinkingConfigDisabled`.
+      #
+      # @return [Boolean]
+      def thinking_enabled?
+        return false unless request.thinking
+
+        type = Anthropic::Transforms.gem_to_hash(request.thinking)[:type]
+        type.present? && type.to_s != "disabled"
+      end
+
       # Selects between Anthropic's stable and beta message APIs.
       #
       # Uses beta API when explicitly requested via anthropic_beta option or when
@@ -184,8 +247,9 @@ module ActiveAgent
 
           self.message_stack[-1] = api_message
 
-          # Once we are finished, close out and run tooling callbacks (Recursive)
-          process_prompt_finished if message_stack.last[:stop_reason]
+          # Completion, tool loop included, runs from stream_finished! once
+          # the stream has drained, so each turn's tool calls run once.
+          self.stream_completion_pending = true if message_stack.last[:stop_reason]
         when :ping
           # No-Op Keep Awake
         when :overloaded_error
@@ -202,14 +266,25 @@ module ActiveAgent
         end
       end
 
-      # Executes tool calls and appends user message with results to message_stack.
+      # Executes tool calls and appends one user message holding every result
+      # to message_stack. Pushes nothing when a tool asked the user for input.
       #
       # @param api_function_calls [Array<Hash>] with :name, :input, and :id keys
       # @return [void]
       def process_function_calls(api_function_calls)
-        content = api_function_calls.map do |api_function_call|
+        results = dispatch_tool_calls(api_function_calls) do |api_function_call|
           process_tool_call_function(api_function_call)
         end
+        return unless results
+
+        content = api_function_calls.zip(results).map do |api_function_call, result|
+          ::Anthropic::Models::ToolResultBlockParam.new(
+            type:        "tool_result",
+            tool_use_id: api_function_call[:id],
+            content:     result.to_json,
+            is_error:    result.is_a?(MCPBridge::ErrorResult)
+          )
+        end
 
         api_message = ::Anthropic::Models::MessageParam.new(role: "user", content:)
         message     = Anthropic::Transforms.gem_to_hash(api_message)
@@ -217,29 +292,26 @@ module ActiveAgent
         message_stack.push(message)
       end
 
-      # Executes a single tool call via callback.
+      # Executes a single tool call via callback. A call that failed on a
+      # bridged MCP server returns an +MCPBridge::ErrorResult+, which
+      # {#process_function_calls} flags with `is_error` so the model reads its
+      # content as the failure it describes.
       #
       # @param api_function_call [Hash] with :name, :input, and :id keys
-      # @return [Anthropic::Models::ToolResultBlockParam]
+      # @return [Object] the tool's result
       def process_tool_call_function(api_function_call)
         instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
-          results = tools_function.call(
-            api_function_call[:name], **api_function_call[:input]
-          )
-
-          ::Anthropic::Models::ToolResultBlockParam.new(
-            type:        "tool_result",
-            tool_use_id: api_function_call[:id],
-            content:     results.to_json,
-            is_error:    false
-          )
+          call_tool_function(api_function_call[:name], **api_function_call[:input])
         end
       end
 
       # Processes completed API response and handles JSON format retries.
       #
       # When response_format is json_object and the response fails JSON validation,
-      # recursively retries the request to obtain well-formed JSON.
+      # recursively retries the request to obtain well-formed JSON. With the
+      # lead-in (see {#json_object_prefill?}), the unparseable answer stays in the
+      # conversation and the retry ends on a new lead-in after it. Without it,
+      # the answer is dropped and the same request is sent again.
       #
       # @see BaseProvider#process_prompt_finished
       # @param api_response [Anthropic::Models::Message]
@@ -249,11 +321,16 @@ module ActiveAgent
         api_response_hash = api_response ? Anthropic::Transforms.gem_to_hash(api_response) : nil
 
         common_response = super(api_response_hash)
+        return common_response if common_response.awaiting_input?
 
         # If we failed to get the expected well formed JSON Object Response, recursively try again
         if request.response_format&.dig(:type) == "json_object" && common_response.message.parsed_json.nil? && json_format_retry_count > 0
           self.json_format_retry_count -= 1
 
+          # No lead-in follows the answer here, so keeping it would end the
+          # retry on an assistant turn: a prefill.
+          message_stack.pop unless json_object_prefill?
+
           resolve_prompt
         else
           common_response
@@ -267,6 +344,11 @@ module ActiveAgent
       # then send the response back for completion. This method detects and reverses
       # that workaround by stripping the lead-in message and prepending "{" to the response.
       #
+      # The response to a request sent without the lead-in (see
+      # {#json_object_prefill?}) is returned as is. The brace goes on the last
+      # block that carries `text`. Blocks without it, such as `thinking`, are
+      # skipped.
+      #
       # @see BaseProvider#process_prompt_finished_extract_messages
       # @param api_response [Hash] API response with content blocks
       # @return [Array<Hash>, nil]
@@ -283,9 +365,9 @@ module ActiveAgent
           # Remove the lead-in message from the request
           request.messages.pop
 
-          # Prepend "{" to the response's first content text
-          if api_response[:content]&.first&.dig(:text)
-            api_response[:content][0][:text] = "{#{api_response[:content][0][:text]}"
+          # Prepend "{" to the response's JSON text block
+          if (text_block = Array(api_response[:content]).reverse.find { |block| block.is_a?(Hash) && block[:text].is_a?(String) })
+            text_block[:text] = "{#{text_block[:text]}"
           end
         end
 

data/lib/active_agent/providers/common/responses/prompt.rb

@@ -31,10 +31,31 @@ module ActiveAgent
 
           attribute :format, Types::FormatType.new, writable: false, default: {}
 
+          # @!attribute [r] input_requests
+          #   The questions tools put to the user, one per paused tool call.
+          #   @return [Array<ActiveAgent::InputRequest>]
+          attribute :input_requests, default: -> { [] }, writable: false
+
+          # @!attribute [r] checkpoint
+          #   What ActiveAgent::Generation#resume_now continues from, as a
+          #   JSON-safe hash. It holds the conversation, so store it as
+          #   carefully as the conversation itself.
+          #   @return [Hash, nil]
+          attribute :checkpoint, writable: false
+
           # The most recent message in the conversational stack
           def message
             messages.last
           end
+
+          # Whether the generation paused because a tool asked the user for
+          # input. The last message is then the assistant turn that made the
+          # tool calls, not an answer.
+          #
+          # @return [Boolean]
+          def awaiting_input?
+            input_requests.present?
+          end
         end
       end
     end