samagotchi 0.98.0 → 0.99.0

data/lib/samagotchi/llm/anthropic_messages.rb

@@ -46,7 +46,12 @@ module Samagotchi
     # - cache_control refused (Fireworks lists it unsupported): no
     #   breakpoints for the host;
     # - max_tokens over the model's output limit: the limit the message
-    #   names, per model.
+    #   names, per model;
+    # - deferred tools or a tool_reference refused: none deferred for the
+    #   model from then on (#loads_tools? false; a load goes as text);
+    # - a deferred tool's input_schema refused: that tool leaves the list
+    #   for the model (call_tool still reaches it), one fix per tool, at
+    #   most MAX_SCHEMA_FIXES per request.
     # A signature 400 (Claude 5.x preserved thinking: a replayed block bound
     # to a prefix that changed) is recovered here too (AnthropicBindingRecovery):
     # asked again with drop_block, or with the blocks stripped, and the
@@ -77,6 +82,16 @@ module Samagotchi
                     \bdisplay\W{0,4}(?:extra\s+inputs\s+are\s+not\s+permitted|is\s+not\s+(?:permitted|allowed|supported))/xi
       # "max_tokens: 200000 > 128000, which is the maximum allowed number of output tokens for …"
       OUTPUT_CAP_RE = /max_tokens`?:?\s*\d+\s*>\s*(\d+)/i
+      # The beta a mid-conversation system message (a tool change) needs.
+      INLINE_TOOLS_BETA = "inline-tools-2026-09-15"
+      # A 400 refusing a tool change: its block, the beta, or the system role.
+      TOOL_CHANGES_RE = /tool_addition|inline-tools|role.{0,40}system|system.{0,40}role/i
+      # A 400 refusing deferred tools or a load by reference.
+      TOOL_LOADING_RE = /defer_loading|tool_reference/i
+      # A 400 naming a tool's input schema: "tools.3.custom.input_schema: …".
+      TOOL_SCHEMA_RE = /tools\.(\d+)\.(?:custom\.)?input_schema/i
+      # The deferred tools a request drops for bad schemas, at most.
+      MAX_SCHEMA_FIXES = 5
       # max_tokens when default.max_tokens is unset and the model list names
       # none (a listed one is capped by it too).
       DEFAULT_MAX_TOKENS = 64_000
@@ -136,7 +151,7 @@ module Samagotchi
         begin
           # A rebuilt body (a refusal fix's retry) keeps the recovery.
           body, stripped = @binding.recovered_body(request_body(messages, tools, model, options), recovery)
-          headers = recovery.step == :drop_block ? { "anthropic-beta" => AnthropicBindingRecovery::BINDING_BETA } : {}
+          headers = beta_headers(body, recovery)
           request = post_request("#{@base_url}/v1/messages", body, session_id: session_id, extra_headers: headers)
           log_fields = { model: model, purpose: @purpose, sampling: sampling_summary(body), cache: cache_summary(body) }
           response, transformations =
@@ -156,6 +171,7 @@ module Samagotchi
 
           fix = refusal_fix(e, body, model)
           raise if fix.nil? || fixed.include?(fix)
+          raise if fix.is_a?(Array) && fixed.count { |done| done.is_a?(Array) } >= MAX_SCHEMA_FIXES
 
           fixed << fix
           retry
@@ -196,6 +212,17 @@ module Samagotchi
       # @return [Hash] frozen
       def thinking_off_refused_fields = thinking_fields(:low)
 
+      # Whether requests for +model+ declare the tools a session reaches but
+      # doesn't declare deferred (defer_loading), loaded by reference from
+      # a find_tools result (ChatLoop#tool_definitions, AnthropicWire): the
+      # dialect's tool_loading, unless the host refused it for +model+.
+      def loads_tools?(model) = @dialect.tool_loading && !@refusals.refused?(:tool_loading, model.to_s)
+
+      # Whether requests for +model+ take a mid-conversation tool change (a
+      # system message with tool_addition blocks, INLINE_TOOLS_BETA): where
+      # tools load, unless the host refused changes for +model+.
+      def tool_changes?(model) = loads_tools?(model) && !@refusals.refused?(:tool_changes, model.to_s)
+
       # Whether +model+ gets the budget form (it refused adaptive thinking).
       def budget_form?(model) = @refusals.refused?(:thinking_form, model.to_s)
 
@@ -229,13 +256,15 @@ module Samagotchi
         options = thinking_between_tools(options) if @refusals.refused?(:thinking_off_form, model.to_s)
         options = without_display(options) if @refusals.refused?(:thinking_display)
         cache = PromptCache.control if @purpose == "chat" && @dialect.cache_breakpoints && !@refusals.refused?(:cache_control)
-        translated = AnthropicWire.translate(messages, cache: cache)
+        tools = without_refused_tools(tools, model)
+        deferred = Array(tools).filter_map { |tool| tool.dig(:function, :name).to_s if tool[:defer_loading] }
+        translated = AnthropicWire.translate(messages, cache: cache, deferred: deferred)
         max_tokens = options.delete(:max_tokens) || default_max_tokens(model)
         output_cap = @refusals[:output_cap, model.to_s]
         max_tokens = [max_tokens, output_cap].min if output_cap
         body = { model: model, max_tokens: max_tokens }
         body[:system] = translated.system unless translated.system.empty?
-        body[:messages] = translated.messages
+        body[:messages] = tool_changes?(model) ? translated.messages : translated.messages.reject { |m| m[:role] == "system" }
         body[:stream] = @stream
         unless Array(tools).empty?
           body[:tools] = AnthropicWire.tools(tools)
@@ -244,6 +273,20 @@ module Samagotchi
         with_budget_room(body.merge(options).compact)
       end
 
+      # +tools+ without the deferred ones the host refused for +model+: all
+      # of them after a :tool_loading refusal, else the ones whose schema
+      # it refused. A find result that loaded one then references only the
+      # rest (AnthropicWire renders references for this request's deferred
+      # names), so no reference is left without its tool.
+      def without_refused_tools(tools, model)
+        return Array(tools).reject { |tool| tool[:defer_loading] } if @refusals.refused?(:tool_loading, model.to_s)
+
+        bad = Array(@refusals[:tool_schema, model.to_s])
+        return tools if bad.empty?
+
+        Array(tools).reject { |tool| tool[:defer_loading] && bad.include?(tool.dig(:function, :name).to_s) }
+      end
+
       # Adaptive thinking at a level as the budget form: thinking enabled
       # with BUDGETS' budget (medium without an effort), shown as asked (no
       # display when it asked none), and no effort (a model without
@@ -326,6 +369,18 @@ module Samagotchi
           @refusals.remember(:cache_control)
           Log.info(:http, "cache_control_refused", host: @host_name, detail: detail[0, 200])
           :cache_control
+        elsif changes?(body) && !@refusals.refused?(:tool_changes, model.to_s) && TOOL_CHANGES_RE.match?(detail)
+          @refusals.remember(:tool_changes, model.to_s)
+          Log.info(:http, "tool_changes_refused", host: @host_name, model: model.to_s, detail: detail[0, 200])
+          :tool_changes
+        elsif (tool = refused_schema_tool(detail, body))
+          @refusals.add(:tool_schema, model.to_s, tool)
+          Log.info(:http, "tool_schema_refused", host: @host_name, model: model.to_s, tool: tool, detail: detail[0, 200])
+          [:tool_schema, tool]
+        elsif !@refusals.refused?(:tool_loading, model.to_s) && TOOL_LOADING_RE.match?(detail) && loads?(body)
+          @refusals.remember(:tool_loading, model.to_s)
+          Log.info(:http, "tool_loading_refused", host: @host_name, model: model.to_s, detail: detail[0, 200])
+          :tool_loading
         elsif (cap = detail[OUTPUT_CAP_RE, 1]&.to_i) && cap.positive? && body[:max_tokens].to_i > cap
           @refusals.remember(:output_cap, model.to_s, cap)
           Log.info(:http, "output_cap", host: @host_name, model: model.to_s, max_tokens: cap)
@@ -333,6 +388,32 @@ module Samagotchi
         end
       end
 
+      # The deferred tool a 400 names by its input_schema's path, or nil.
+      def refused_schema_tool(detail, body)
+        index = detail[TOOL_SCHEMA_RE, 1] or return nil
+        tool = Array(body[:tools])[index.to_i]
+        tool[:name] if tool.is_a?(Hash) && tool[:defer_loading]
+      end
+
+      # Whether +body+ carries a tool change (a system message).
+      def changes?(body) = Array(body[:messages]).any? { |message| message[:role] == "system" }
+
+      # The anthropic-beta header: the binding beta on a drop_block step,
+      # INLINE_TOOLS_BETA with a tool change; both comma-joined.
+      def beta_headers(body, recovery)
+        betas = []
+        betas << AnthropicBindingRecovery::BINDING_BETA if recovery.step == :drop_block
+        betas << INLINE_TOOLS_BETA if changes?(body)
+        betas.empty? ? {} : { "anthropic-beta" => betas.join(",") }
+      end
+
+      # Whether +body+ declares a deferred tool or loads one by reference.
+      def loads?(body)
+        return true if Array(body[:tools]).any? { |tool| tool[:defer_loading] }
+
+        JSON.generate(body[:messages]).include?('"tool_reference"')
+      end
+
       # The model list's max_tokens for +model+ (capped), else the cap.
       def default_max_tokens(model)
         listed = listed_model(model)&.raw&.dig("max_tokens")

data/lib/samagotchi/llm/anthropic_wire.rb

@@ -4,6 +4,7 @@ require "digest"
 require "json"
 require_relative "../log"
 require_relative "utf8_scrub"
+require_relative "../tools/tool_index"
 
 module Samagotchi
   module LLM
@@ -13,11 +14,18 @@ module Samagotchi
     # - the head system message → the top-level system, as text blocks: with
     #   its cache_split, two blocks, the breakpoint on the first; a later
     #   system message → user text (a mid-conversation system role is
-    #   model-gated);
+    #   model-gated), but a plugin's tool change (tool_change:) → a system
+    #   message of its own, tool_addition blocks by reference for the names
+    #   deferred in this request (none: dropped), placed after the run of
+    #   user-role messages it sits in, before the next assistant message;
     # - an assistant message → its saved blocks verbatim (anthropic_content),
     #   else a text block and its tool_use blocks (arguments as the input
     #   object); one with neither is dropped;
-    # - tool messages → tool_result blocks in a user message;
+    # - tool messages → tool_result blocks in a user message; one whose
+    #   loaded: names tools this request declares deferred loads them: its
+    #   tool_result holds only their tool_reference blocks, and its text
+    #   follows as a sibling text block (Messages takes no text beside a
+    #   reference), never marked;
     # - user parts → text blocks and image blocks (a data URL as base64, an
     #   http(s) URL as a url source).
     # Consecutive messages of one role go as one message (so a turn's tool
@@ -47,11 +55,15 @@ module Samagotchi
       #   (PromptCache.control): on the head system's first block and on the
       #   last block that didn't come from a later system message (a tail
       #   note moves each request, as PromptCache's rule says); nil sets none
+      # @param deferred [Array<String>] the tools this request declares
+      #   deferred (defer_loading)
       # @return [Translated]
-      def translate(wire, cache: nil)
+      def translate(wire, cache: nil, deferred: [])
         system = []
         messages = []
         notes = {}.compare_by_identity
+        # Tool changes wait for the end of the user turn they sit in.
+        changes = []
         Array(wire).each_with_index do |raw, index|
           message = raw.to_h.transform_keys(&:to_sym)
           role = message[:role].to_s
@@ -60,9 +72,20 @@ module Samagotchi
             next
           end
 
+          if role == "system" && message[:tool_change]
+            blocks = tool_additions(message[:tool_change], deferred)
+            changes << { role: "system", content: blocks } unless blocks.empty?
+            next
+          end
+
           case role
-          when "assistant" then append(messages, "assistant", assistant_blocks(message))
-          when "tool" then append(messages, "user", [tool_result(message)])
+          when "assistant"
+            flush_changes(messages, changes)
+            append(messages, "assistant", assistant_blocks(message))
+          when "tool"
+            blocks = tool_blocks(message, deferred)
+            blocks.drop(1).each { |block| notes[block] = true }
+            append(messages, "user", blocks)
           when "system"
             blocks = content_blocks(message[:content])
             blocks.each { |block| notes[block] = true }
@@ -70,18 +93,22 @@ module Samagotchi
           else append(messages, "user", content_blocks(message[:content]))
           end
         end
+        flush_changes(messages, changes)
         messages.each { |message| message[:content] << text_block(PLACEHOLDER) if message[:content].empty? }
         mark_last(messages, cache, notes) if cache
         Translated.new(system: system, messages: messages)
       end
 
-      # ChatLoop's function definitions as Messages tools.
+      # ChatLoop's function definitions as Messages tools; a deferred one
+      # (defer_loading: true beside its function) keeps the flag.
       # @param tools [Array<Hash>] {type: "function", function: {name:, description:, parameters:}}
       def tools(tools)
         Array(tools).map do |tool|
           function = (tool[:function] || tool["function"] || tool).to_h.transform_keys(&:to_sym)
+          deferred = tool[:defer_loading] || tool["defer_loading"]
           { name: function[:name].to_s, description: function[:description],
-            input_schema: function[:parameters] || { type: "object", properties: {} } }.compact
+            input_schema: function[:parameters] || { type: "object", properties: {} },
+            defer_loading: (true if deferred == true) }.compact
         end
       end
 
@@ -133,8 +160,27 @@ module Samagotchi
         text.empty? ? "tool" : text
       end
 
+      # A tool change's tool_addition blocks, by reference, for its names
+      # deferred in this request (a reference must name a tool in tools).
+      def tool_additions(change, deferred)
+        change = change.to_h.transform_keys(&:to_sym)
+        names = Array(change[:add]).map(&:to_s) & Array(deferred)
+        names.map { |name| { type: "tool_addition", tool: { type: "tool_reference", name: name } } }
+      end
+
+      # The waiting tool changes after the messages so far (a user turn:
+      # Messages wants a system change after one), each a message of its
+      # own; none before the first user message.
+      def flush_changes(messages, changes)
+        return if changes.empty? || messages.last.nil? || messages.last[:role] != "user"
+
+        messages.concat(changes)
+        changes.clear
+      end
+
       # A message joins the one before it when the role is the same; an
-      # assistant message with no blocks is dropped.
+      # assistant message with no blocks is dropped. A system message (a
+      # tool change) is never joined.
       def append(messages, role, blocks)
         return if role == "assistant" && blocks.empty?
 
@@ -215,6 +261,29 @@ module Samagotchi
         block
       end
 
+      # A tool message's blocks: its tool_result, or, when its loaded:
+      # names tools deferred in this request, a tool_result of their
+      # references and the text after it.
+      def tool_blocks(message, deferred)
+        names = Array(message[:loaded]).map(&:to_s) & Array(deferred)
+        return [tool_result(message)] if names.empty?
+
+        refs = names.map { |name| { type: "tool_reference", tool_name: name } }
+        [{ type: "tool_result", tool_use_id: tool_id(message[:tool_call_id]), content: refs },
+         text_block(loaded_text(scrub(message[:content].to_s), names))]
+      end
+
+      # The sibling text: the load first, then the result's text without the
+      # line that points at call_tool (D11: the saved result and the prompt
+      # don't change; only this wire says it).
+      def loaded_text(text, names)
+        line = "Loaded: #{names.join(", ")}. #{LOADED_HINT}"
+        text = text.sub("#{Tools::ToolIndex::CALL_HINT}\n\n", "")
+        blank?(text) ? line : "#{line}\n\n#{text}"
+      end
+
+      LOADED_HINT = "Call them directly by these names."
+
       # A String or a parts list as blocks.
       def content_blocks(content)
         return blank?(content.to_s) ? [] : [text_block(scrub(content.to_s))] unless content.is_a?(Array)
@@ -241,14 +310,23 @@ module Samagotchi
       end
 
       # Breakpoint #2: the last user block that can carry one and didn't
-      # come from a later system message (+notes+).
+      # come from a later system message or a load's text (+notes+); on a
+      # tool_result of references, its last reference.
       def mark_last(messages, cache, notes)
         markable = ->(block) { !UNMARKABLE.include?(type_of(block)) && !notes.key?(block) }
         message = messages.reverse_each.find { |m| m[:role] == "user" && m[:content].any?(&markable) } or return
         index = message[:content].rindex(&markable)
         block = message[:content][index]
         key = block.key?("type") ? "cache_control" : :cache_control
-        message[:content][index] = block.merge(key => cache)
+        message[:content][index] = references?(block) ? mark_reference(block, cache) : block.merge(key => cache)
+      end
+
+      def references?(block) = type_of(block) == "tool_result" && block[:content].is_a?(Array)
+
+      def mark_reference(block, cache)
+        refs = block[:content].dup
+        refs[-1] = refs[-1].merge(cache_control: cache)
+        block.merge(content: refs)
       end
 
       def type_of(block) = (block[:type] || block["type"]).to_s
@@ -260,7 +338,8 @@ module Samagotchi
       def scrub(text) = Utf8Scrub.call(text)
 
       private_class_method :append, :system_blocks, :assistant_blocks, :input_of, :warn_arguments, :tool_result,
-                           :content_blocks, :image_block, :mark_last, :valid_tool_use, :type_of, :text_block, :blank?, :scrub
+                           :content_blocks, :image_block, :mark_last, :valid_tool_use, :type_of, :text_block, :blank?, :scrub,
+                           :tool_blocks, :loaded_text, :references?, :mark_reference, :tool_additions, :flush_changes
     end
   end
 end

data/lib/samagotchi/llm/chat_loop.rb

@@ -22,6 +22,8 @@ require_relative "../tool_runner"
 require_relative "../tool_response"
 require_relative "../tool_ids"
 require_relative "../tool_declarations"
+require_relative "../tools/deferred_tools"
+require_relative "../tool_loads"
 require_relative "../vision_context"
 require_relative "../log"
 require_relative "../empty_answer_retry"
@@ -100,11 +102,38 @@ module Samagotchi
       # Tool definitions for the request: the schemas the native prompts are
       # rendered from (the kernel's registry, the tools the turn's LLM
       # context layers offer), with the chat-only enums and closed
-      # parameters.
-      def tool_definitions
-        ToolDeclarations.chat_schemas(tools.schemas(layers: llm_context_layers)).map do |schema|
+      # parameters. On an adapter that loads tools for +model+
+      # (#loads_tools?), every tool the session reaches but doesn't declare
+      # follows, deferred (Tools::DeferredTools: +conversation+, the
+      # request's, names the ones it loaded); never without a declared one.
+      def tool_definitions(conversation = nil, model: nil)
+        declared = ToolDeclarations.chat_schemas(tools.schemas(layers: llm_context_layers)).map do |schema|
           { type: "function", function: schema.slice(:name, :description, :parameters) }
         end
+        return declared if declared.empty? || !loads_tools?(model)
+
+        declared + deferred_tools(conversation).map do |tool|
+          { type: "function", function: { name: tool.name, description: tool.description, parameters: tool.schema },
+            defer_loading: true }
+        end
+      end
+
+      # The tools a request on a host that loads tools declares deferred
+      # (Tools::DeferredTools).
+      def deferred_tools(conversation)
+        Tools::DeferredTools.list(tools, conversation, layers: llm_context_layers)
+      end
+
+      # Whether the adapter takes tools it doesn't declare up front for
+      # +model+ (AnthropicMessages#loads_tools?); OpenAIChat doesn't.
+      def loads_tools?(model)
+        @adapter.respond_to?(:loads_tools?) && @adapter.loads_tools?(model.to_s)
+      end
+
+      # Whether the adapter takes a mid-conversation tool change for +model+
+      # (AnthropicMessages#tool_changes?: a plugin's ctx.load_tools, ToolLoads).
+      def tool_changes?(model)
+        @adapter.respond_to?(:tool_changes?) && @adapter.tool_changes?(model.to_s)
       end
 
       # The kernel's tools.
@@ -156,6 +185,11 @@ module Samagotchi
       #
       # The conversation goes through the kernel's LLMContextView first,
       # as the native prompt does (it keeps every entry in place).
+      #
+      # On an adapter that loads tools (#loads_tools?), a find result's
+      # tool message carries its loaded: names (AnthropicWire renders the
+      # load); no other wire sees them. A plugin's tool change
+      # (ToolLoads) goes only to an adapter that takes tool changes.
       def wire_messages(conversation, since: nil, reasoning: reasoning_history)
         conversation = llm_context_view.messages(conversation)
         paired = paired_call_ids(conversation)
@@ -172,7 +206,13 @@ module Samagotchi
           items = plan.items(entry, index)
           case entry[:role].to_s
           when "system"
-            wire << system_message(entry, index)
+            if ToolLoads.entry?(entry)
+              # Only to a host that takes tool changes; never an empty
+              # system message elsewhere.
+              wire << { role: "system", content: entry[:content].to_s, TOOL_CHANGE => entry[TOOL_CHANGE] } if tool_change_wire?
+            else
+              wire << system_message(entry, index)
+            end
           when "user"
             # A steer or merged input (always a String) goes with its header.
             content = Steer.header(entry) ? Steer.wire_text(entry, entry[:content].to_s) : entry[:content]
@@ -186,7 +226,10 @@ module Samagotchi
           when "tool_response"
             id = entry[:tool_call_id]
             if id && paired.include?(id)
-              wire << { role: "tool", content: with_placeholders(entry[:content].to_s, items), tool_call_id: id }
+              message = { role: "tool", content: with_placeholders(entry[:content].to_s, items), tool_call_id: id }
+              # A find result's loads, for a wire that loads tools (AnthropicWire).
+              message[:loaded] = entry[:loaded] if entry[:loaded].is_a?(Array) && @adapter.respond_to?(:loads_tools?)
+              wire << message
               tool_images.concat(image_parts(items))
             else
               text = "[tool results]\n#{entry[:content]}"
@@ -215,6 +258,9 @@ module Samagotchi
 
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
+      # Whether this turn's requests carry tool changes (the turn's model).
+      def tool_change_wire? = tool_changes?(@kernel.turn_settings&.model_name)
+
       # The first index whose model entries carry their reasoning (nil:
       # none do) under +level+. Under turn: +since+ when given, where a
       # Run's reasoning starts (ReasoningHistory.run_start, the native
@@ -368,6 +414,9 @@ module Samagotchi
         removed
       end
 
+      # A system entry's tools a plugin loaded ({add:, by:}; ToolLoads).
+      TOOL_CHANGE = ToolLoads::KEY
+
       # The shape the engine persists: role and content (parts stay an
       # Array), plus a model turn's tool_calls and thinking (the host's
       # reasoning, sent back as #wire_messages says), a result's tool_call_id, the image
@@ -376,7 +425,9 @@ module Samagotchi
       # (the live row's params line and label, never sent back), an
       # edit/write result's tool_diffs (never sent), an empty-answer
       # note's marker (TurnNote.empty, never sent), and an answer's display
-      # and display_refs (AnswerDisplay, AnswerRefs; never sent).
+      # and display_refs (AnswerDisplay, AnswerRefs; never sent), a
+      # find_tools result's loaded names and a tool change's TOOL_CHANGE
+      # (sent only to a wire that loads tools).
       def plain(conversation)
         conversation.map do |entry|
           content = entry[:content].is_a?(Array) ? entry[:content] : entry[:content].to_s
@@ -395,6 +446,8 @@ module Samagotchi
           message[AnswerDisplay::KEY] = entry[AnswerDisplay::KEY] if entry[AnswerDisplay::KEY]
           message[AnswerRefs::KEY] = entry[AnswerRefs::KEY] if entry[AnswerRefs::KEY]
           ContextNote::KEYS.each { |key| message[key] = entry[key] if entry.key?(key) }
+          message[ToolResponse::LOADED] = entry[ToolResponse::LOADED] if entry[ToolResponse::LOADED].is_a?(Array)
+          message[TOOL_CHANGE] = entry[TOOL_CHANGE] if entry[TOOL_CHANGE].is_a?(Hash)
           message
         end
       end
@@ -530,6 +583,8 @@ module Samagotchi
           @request_image_tokens = nil
           @without_reasoning = false
           @recovery_repeated = false
+          # The names the last request declared deferred.
+          @deferred = []
           @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context)
           loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
                                                              emit: method(:emit))
@@ -753,8 +808,10 @@ module Samagotchi
         end
 
         def request(iteration, retry_generation, streamed, thought, generation_controller, streamed_any = nil)
+          definitions = @loop.tool_definitions(@conversation, model: @model_name)
+          @deferred = definitions.filter_map { |tool| tool.dig(:function, :name) if tool[:defer_loading] }
           @loop.adapter.chat(
-            messages: @loop.wire_messages(@conversation, since: @reasoning_start, reasoning: reasoning_level), tools: @loop.tool_definitions, model: @model_name,
+            messages: @loop.wire_messages(@conversation, since: @reasoning_start, reasoning: reasoning_level), tools: definitions, model: @model_name,
             cancel_controller: generation_controller || @cancel_controller, session_id: @loop.session_id,
             options: @loop.request_options(retry_generation: retry_generation, model: @model_name),
             on_delta: lambda { |content:, reasoning:, payload:|
@@ -938,6 +995,7 @@ module Samagotchi
         # with its call (ToolResponse.single: the capped output), with the
         # next id (ToolIds).
         def dispatch(tool_calls, iteration, cap)
+          log_direct_deferred(tool_calls)
           calls = tool_calls.map { |tool_call| NativeToolNormalizer.normalize(tool_call) }
           runs = ToolResponse.run_batch(@loop.tool_runner, calls, iteration: iteration, emit: method(:emit),
                                                                   on_stream_event: @on_stream_event, cap: cap) do |run, index|
@@ -947,6 +1005,17 @@ module Samagotchi
           @tool_activity.concat(ToolResponse.activities(runs))
         end
 
+        # A call of a tool the last request declared deferred: whether the
+        # conversation had loaded it (how well a load leads to a direct
+        # call, and how often the model calls one it only read about).
+        def log_direct_deferred(tool_calls)
+          direct = tool_calls.map { |call| call.name.to_s } & @deferred
+          return if direct.empty?
+
+          loaded = Tools::DeferredTools.loaded_names(@conversation)
+          direct.each { |name| Log.info(:turn, "tool_direct_deferred", tool: name, loaded: loaded.include?(name)) }
+        end
+
         # Queued input at an iteration boundary (Steer.inject!). Returns true
         # when there was any.
         def inject_pending_input(iteration, answer: nil)

data/lib/samagotchi/llm/dialect.rb

@@ -15,8 +15,10 @@ module Samagotchi
     #   nil for none;
     # cache_breakpoints: whether chat requests carry cache_control;
     # session_header: a header that carries the session id (beside
-    #   Session-Id), nil for none.
-    Dialect = Data.define(:name, :auth, :thinking_display, :cache_breakpoints, :session_header) do
+    #   Session-Id), nil for none;
+    # tool_loading: whether requests declare tools deferred
+    #   (defer_loading) and load them by reference (tool_reference).
+    Dialect = Data.define(:name, :auth, :thinking_display, :cache_breakpoints, :session_header, :tool_loading) do
       # The dialect for a `dialect:` name (HostConfig#dialect); STANDARD for
       # nil or an unknown one.
       def self.for(name) = self::BY_NAME.fetch(name.to_s, self::STANDARD)
@@ -44,14 +46,15 @@ module Samagotchi
     end
 
     Dialect::STANDARD = Dialect.new(name: "standard", auth: :x_api_key, thinking_display: "summarized",
-                                    cache_breakpoints: true, session_header: nil)
+                                    cache_breakpoints: true, session_header: nil, tool_loading: true)
     # Fireworks' /v1/messages (docs.fireworks.ai, anthropic-compatibility):
     # Bearer auth, no `display` in its thinking schema (every object refuses
     # extra fields; thinking comes back by default), an automatic prefix
     # cache (no breakpoints), and x-session-affinity to keep a session on
-    # one replica, where its cache is.
+    # one replica, where its cache is. Its compatibility list has no
+    # deferred tools.
     Dialect::FIREWORKS = Dialect.new(name: "fireworks", auth: :bearer, thinking_display: nil,
-                                     cache_breakpoints: false, session_header: "x-session-affinity")
+                                     cache_breakpoints: false, session_header: "x-session-affinity", tool_loading: false)
     Dialect::BY_NAME = { "standard" => Dialect::STANDARD, "fireworks" => Dialect::FIREWORKS }.freeze
   end
 end

data/lib/samagotchi/llm/refusal_memo.rb

@@ -23,6 +23,12 @@ module Samagotchi
       # Whether +kind+ is remembered for +model+ (nil: the host).
       def refused?(kind, model = nil) = @mutex.synchronize { @facts.key?([kind, model]) }
 
+      # Add +item+ to the list remembered for +kind+ and +model+ (a value
+      # that grows: the deferred tools a model's host refused, one by one).
+      def add(kind, model, item)
+        @mutex.synchronize { (@facts[[kind, model]] ||= []) << item unless Array(@facts[[kind, model]]).include?(item) }
+      end
+
       # The value remembered for +kind+ and +model+, or nil.
       def [](kind, model = nil) = @mutex.synchronize { @facts[[kind, model]] }
     end

data/lib/samagotchi/llm/turn_settings.rb

@@ -15,14 +15,22 @@ module Samagotchi
     # window (ContextWindow.setting, nil for none) and LLM context strategy
     # (LLMContextStrategy.resolve, nil for none), and its price on its host
     # (hosts.<name>.models.<id>.price, a ModelPrice; nil for none), what
-    # SessionMetrics estimates an unreported cost from. The Engine sets them once
-    # per turn, in Engine#generate, after the model's host is synced.
+    # SessionMetrics estimates an unreported cost from, and whether the turn's
+    # host takes tools it doesn't declare up front (+loads_tools+:
+    # AnthropicMessages#loads_tools?; a direct call of a reachable tool then
+    # runs). The Engine sets them once per turn, in Engine#generate, after
+    # the model's host is synced.
     TurnSettings = Data.define(:vision, :sampling, :thinking, :reasoning_history, :model_name, :window_setting,
-                               :llm_context, :price) do
+                               :llm_context, :price, :loads_tools) do
+      def initialize(vision:, sampling:, thinking:, reasoning_history:, model_name:, window_setting:, llm_context:,
+                     price:, loads_tools: false)
+        super
+      end
+
       # No vision, no sampling, the default thinking, no reasoning sent
-      # back, no model name.
+      # back, no model name, no tools loaded.
       def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, reasoning_history: :drop,
-                          model_name: nil, window_setting: nil, llm_context: nil, price: nil)
+                          model_name: nil, window_setting: nil, llm_context: nil, price: nil, loads_tools: false)
     end
   end
 end

data/lib/samagotchi/llm_context_stale.rb

@@ -192,7 +192,7 @@ module Samagotchi
         id = entry[:tool_call_id].to_s
         matches = id.empty? ? [] : batch.select { |call_id, _| call_id.to_s == id }
         call = matches.one? ? matches.first.last : nil
-        call &&= Tools::BuiltinCalls.unwrap_saved(call, entry[:content])
+        call &&= Tools::BuiltinCalls.unwrap_saved(Tools::BuiltinCalls.wrap_saved(call, entry[:content]), entry[:content])
         texts = call && refs.size == 1 ? ToolResponse.runs_named(entry[:content], [call[:name]]) : nil
         return texts ? [[refs.first, call, texts.first.text]] : []
       end
@@ -201,7 +201,7 @@ module Samagotchi
       # built-in (BuiltinCalls.unwrap_saved).
       calls = batch.map(&:last)
       calls = calls.zip(ToolResponse.runs(entry[:content], calls.size)).map do |call, run|
-        Tools::BuiltinCalls.unwrap_saved(call, run&.text)
+        Tools::BuiltinCalls.unwrap_saved(Tools::BuiltinCalls.wrap_saved(call, run&.text), run&.text)
       end
       texts = ToolResponse.runs_named(entry[:content], calls.map { |call| call[:name] })
       return [] unless texts && texts.size == refs.size

data/lib/samagotchi/message_parts.rb

@@ -237,7 +237,8 @@ module Samagotchi
                   tool_id: nil, marks: {})
       # A built-in reached through call_tool reloads as that built-in's
       # row, with via (its saved params and label are the built-in's).
-      call = Tools::BuiltinCalls.unwrap_saved(call, output)
+      # A direct call of an MCP tool reloads as the call_tool row it ran as.
+      call = Tools::BuiltinCalls.unwrap_saved(Tools::BuiltinCalls.wrap_saved(call, output), output)
       name = call[:name].to_s
       params = shown.is_a?(String) ? shown : ToolActivity.tool_activity_params(name, call, registry: registry)
       part = { tool: name, params: params.to_s }

data/lib/samagotchi/plugin/api.rb

@@ -40,7 +40,7 @@ module Samagotchi
         "ctx.prompt_files" => "0.60.0", "chi.annotation" => "0.66.0", "chi.toolkit" => "0.66.0",
         "ctx.use_toolkit" => "0.66.0", "ctx.toolkit" => "0.66.0", "ctx.declared_tools" => "0.66.0",
         "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
-        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0"
+        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0"
       }.freeze
 
       # @param bundle [String]