samagotchi 0.98.0 → 0.100.0

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,8 @@ 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",
+        "ctx.usage" => "0.100.0"
       }.freeze
 
       # @param bundle [String]

data/lib/samagotchi/plugin/context.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require_relative "../log"
 require_relative "../paths"
 require_relative "../session_metrics/cost"
+require_relative "../session_metrics/usage"
 require_relative "../guardrails/context"
 require_relative "../hook_question"
 require_relative "../idle_client"
@@ -48,16 +49,19 @@ module Samagotchi
     # :non_interactive), which ctx.frontend names for plugins.
     # +toolkit+ returns the session's toolkit name, +declared_tools+ the
     # tool names its next turn declares, +use_toolkit+ takes a name and
-    # returns whether it staged it (Engine#use_toolkit).
+    # returns whether it staged it (Engine#use_toolkit); +load_tools+ takes
+    # (names, bundle) and returns the wire names it staged
+    # (Engine#load_tools).
     # +cancel_controller+ takes (handler:) and returns the controller a
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
     # plugin handler: +handler+) until the turn has ended.
-    # +cost+ returns the session's spend now (SessionMetrics::Cost).
+    # +cost+ returns the session's spend now (SessionMetrics::Cost),
+    # +usage+ its work now (SessionMetrics::Usage).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
-                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
-                      :cancel_controller, :cost, keyword_init: true)
+                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
+                      :cancel_controller, :cost, :usage, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -165,6 +169,12 @@ module Samagotchi
       #   (docs/plugins.md); zero and known with no session
       def cost = @host.cost&.call || SessionMetrics::Cost.zero
 
+      # @return [SessionMetrics::Usage] the session's work so far, read now:
+      #   #turns, #tool_calls, #tool_calls_by_tool, #steps, #active_ms
+      #   (#active_minutes) and #tool_ms_by_tool (docs/plugins.md); zero
+      #   with no session
+      def usage = @host.usage&.call || SessionMetrics::Usage.zero
+
       # @return [String, nil] the name of the session's toolkit ("full" for
       #   one from before toolkits; nil with no session)
       def toolkit = @host.toolkit&.call
@@ -182,6 +192,23 @@ module Samagotchi
       # @raise [ArgumentError] a toolkit no one declared
       def use_toolkit(name) = !!@host.use_toolkit&.call(name.to_s)
 
+      # Load tools the session reaches but doesn't declare, so the model
+      # calls them by name (docs/plugins.md): built-in names, MCP tools'
+      # acts_as (mcp_fs_read) or <group>/<tool>. A hint, not access: the
+      # tools stay behind the same guardrails, and only a host that takes
+      # tool changes (api: anthropic) gets one; elsewhere nothing is sent.
+      # Called from before_turn, they load for that turn; anywhere else,
+      # from the next turn's start. Idempotent: a declared tool, one loaded
+      # before, a removed or unknown one is skipped.
+      # @param names [Array<String>]
+      # @return [Array<String>] the names staged (wire names)
+      # @raise [ArgumentError] +names+ isn't an Array
+      def load_tools(names)
+        raise ArgumentError, "load_tools takes an Array of tool names" unless names.is_a?(Array)
+
+        Array(@host.load_tools&.call(names.map(&:to_s), @bundle))
+      end
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/prompt.rb

@@ -5,6 +5,7 @@ require_relative "prompt_literal_guard"
 require_relative "vision_context"
 require_relative "tool_response"
 require_relative "steer"
+require_relative "tool_loads"
 
 module Samagotchi
   # Formats a message list into a prompt string ready for the /completion endpoint.
@@ -48,6 +49,8 @@ module Samagotchi
     #   the model's answer (Thinking.native: Qwen's empty thought)
     # @return [Array(String, Array<String>)]
     def self.format_with_images(messages, profile: ModelProfile.default, vision: nil, prefill: "")
+      # A plugin's tool change (ToolLoads) is for a Messages host only.
+      messages = messages.reject { |message| ToolLoads.entry?(message) }
       plan = ImagePlan.new(messages, vision, data: :base64)
       images = []
       suffixes = messages.each_with_index.map { |m, index| image_lines(plan.items(m, index), profile, images) }

data/lib/samagotchi/session_metrics/usage.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionMetrics
+    # The session's work so far (SessionMetrics#usage, what a bundle's
+    # ctx.usage reads), across its turns and workers: the same numbers
+    # /stats and `chi sessions stats` show.
+    # +turns+: finished turns plus the running one. +tool_calls+ and
+    # +tool_calls_by_tool+ (canonical names: an alias counts under the tool
+    # it resolved to, a call_tool call under the inner tool): every call,
+    # running ones included. +steps+: the loop rounds that dispatched tools
+    # (the snapshot's iterations_total). +active_ms+: work time, the
+    # generations' time plus the finished tool calls' time (approval waits
+    # left out; ask_user_question's, a wait on the user, not counted),
+    # never a question's wait between them; +tool_ms_by_tool+ is the tool
+    # part by tool (the same names), so a reader can leave a waiting tool's
+    # time (task_wait, a blocking delegate) out.
+    # Bundles use its methods only, never this constant's name.
+    Usage = Data.define(:turns, :tool_calls, :tool_calls_by_tool, :steps, :active_ms, :tool_ms_by_tool) do
+      def self.zero = new(turns: 0, tool_calls: 0, tool_calls_by_tool: {}, steps: 0, active_ms: 0, tool_ms_by_tool: {})
+
+      # Data freezes itself, not its hashes: these are copied and frozen.
+      def initialize(tool_calls_by_tool:, tool_ms_by_tool:, **)
+        super(tool_calls_by_tool: tool_calls_by_tool.dup.freeze, tool_ms_by_tool: tool_ms_by_tool.dup.freeze, **)
+      end
+
+      # @return [Float] active_ms in minutes
+      def active_minutes = active_ms / 60_000.0
+    end
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -14,6 +14,7 @@ require_relative "session"
 require_relative "session_metrics/totals"
 require_relative "session_metrics/model_segment"
 require_relative "session_metrics/cost"
+require_relative "session_metrics/usage"
 require_relative "session_metrics/side_totals"
 require_relative "side_usage"
 
@@ -53,6 +54,10 @@ module Samagotchi
     SPEED_MIN_TOKENS = 8
     SPEED_MIN_MS = 100
 
+    # The tools whose time is a wait on the user, not work (#usage).
+    USER_WAIT_TOOLS = %w[ask_user_question].freeze
+    private_constant :USER_WAIT_TOOLS
+
     # The session's token totals as a saved analytics.json has them (zeros
     # where an older file lacks a count), with how full the context was.
     # A generation's decode speed (tokens per second) and where it came
@@ -377,6 +382,23 @@ module Samagotchi
       @mutex.synchronize { Cost.of(@totals.with_running(@turn), @side) }
     end
 
+    # The session's work now (ctx.usage): turns, tool calls (by tool), steps
+    # and active (work) time, earlier workers' loaded records and the
+    # running turn included. Safe from any thread.
+    # @return [Usage]
+    def usage
+      @mutex.synchronize do
+        turn = @turn
+        totals = @totals.with_running(turn)
+        calls, by_tool = tool_call_counts(turn)
+        tool_ms = @tool_tallies[:ms]
+        # Finished calls only: a running call's approval wait isn't known
+        # until it completes (waited_ms), so its time counts then.
+        Usage.new(turns: turn_count(turn), tool_calls: calls, tool_calls_by_tool: by_tool, steps: totals.iterations,
+                  active_ms: (totals.gen_ms + tool_ms.values.sum).round, tool_ms_by_tool: tool_ms.transform_values(&:round))
+      end
+    end
+
     # Event sink. Safe to call from any thread; errors are isolated by the
     # caller (SessionObserver / TerminalUI) but we still guard internally.
     # @param event [Hash]
@@ -542,10 +564,10 @@ module Samagotchi
     def build_snapshot(records_mode)
       turn = @turn
       totals = @totals.with_running(turn)
-      in_flight = turn ? turn.tool_calls_by_id.values : []
+      calls, by_tool = tool_call_counts(turn)
       {
         session_id: @session_id,
-        turns: @turn_records.size + (turn ? 1 : 0),
+        turns: turn_count(turn),
         cancellations: totals.cancellations,
         tokens: totals.tokens_block,
         # The tokens, cost and speeds per model, in order (ModelSegment.rows:
@@ -557,8 +579,8 @@ module Samagotchi
         profile_source: @profile_source,
         served_model: @served_model,
         served_model_for: @served_model_for,
-        tool_calls_total: @tool_records.size + in_flight.size,
-        tool_calls_by_tool: tally_into(@tool_tallies[:by_tool].dup, in_flight),
+        tool_calls_total: calls,
+        tool_calls_by_tool: by_tool,
         # The calls the model made under an alias's name (bash run as
         # execute), by its own spelling; only when there are any.
         **(@tool_tallies[:aliased].empty? ? {} : { tool_calls_aliased: @tool_tallies[:aliased].dup }),
@@ -582,6 +604,17 @@ module Samagotchi
       }
     end
 
+    # The finished turns and the running one. Caller holds the mutex.
+    def turn_count(turn) = @turn_records.size + (turn ? 1 : 0)
+
+    # Every tool call (loaded records, this process's, the running ones)
+    # and the calls by tool, a copy. Caller holds the mutex.
+    # @return [Array(Integer, Hash)]
+    def tool_call_counts(turn)
+      in_flight = turn ? turn.tool_calls_by_id.values : []
+      [@tool_records.size + in_flight.size, tally_into(@tool_tallies[:by_tool].dup, in_flight)]
+    end
+
     # The model segments with the running turn in: the last one's when it
     # runs on that model or names none yet, else a new one. Caller holds
     # the mutex.
@@ -1199,7 +1232,8 @@ module Samagotchi
       @totals = Totals.zero
       @segments = []
       @last_model_ref = nil
-      @tool_tallies = { by_tool: {}, aliased: {}, errors: 0 }
+      # ms: the finished calls' time by tool (#usage's active_ms).
+      @tool_tallies = { by_tool: {}, aliased: {}, errors: 0, ms: {} }
     end
 
     def count_turn(record)
@@ -1219,6 +1253,15 @@ module Samagotchi
       tally_into(@tool_tallies[:by_tool], [record])
       called_as = record[:called_as].to_s
       @tool_tallies[:aliased][called_as] = @tool_tallies[:aliased].fetch(called_as, 0) + 1 unless called_as.empty?
+      count_tool_ms(record)
+    end
+
+    def count_tool_ms(record)
+      name = record[:tool].to_s
+      ms = record[:duration_ms]
+      return if name.empty? || !ms.is_a?(Numeric) || USER_WAIT_TOOLS.include?(name)
+
+      @tool_tallies[:ms][name] = @tool_tallies[:ms].fetch(name, 0) + ms
     end
 
     def tally_into(counts, tools)

data/lib/samagotchi/testing/bundle.rb

@@ -352,6 +352,8 @@ module Samagotchi
       def questions = @recorder.questions
       def model_requests = @recorder.model_requests
       def toolkit_uses = @recorder.toolkit_uses
+      # Every ctx.load_tools call (ToolLoad: names, bundle).
+      def tool_loads = @recorder.tool_loads
       # Queue ask_model answers: a String, an exception, or a callable.
       def model_answers = @recorder.model_answers
 

data/lib/samagotchi/testing/host.rb

@@ -3,6 +3,7 @@
 require_relative "../cancellation_controller"
 require_relative "../plugin/context"
 require_relative "../session_metrics/cost"
+require_relative "../session_metrics/usage"
 require_relative "recorder"
 
 module Samagotchi
@@ -47,8 +48,10 @@ module Samagotchi
           toolkit: -> { recorder[:toolkit] },
           declared_tools: -> { recorder[:declared_tools] || tool_names.call },
           use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
+          load_tools: ->(names, bundle) { recorder.load_tools(names, bundle) },
           cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
-          cost: -> { cost(recorder[:cost]) }
+          cost: -> { cost(recorder[:cost]) },
+          usage: -> { usage(recorder[:usage]) }
         )
       end
 
@@ -74,6 +77,33 @@ module Samagotchi
         else raise ArgumentError, "cost: a number, a Hash or a callable, not #{value.inspect}"
         end
       end
+
+      # The parts a test may give bundle.set(usage: {...}).
+      USAGE_PARTS = %i[turns tool_calls tool_calls_by_tool steps active_ms tool_ms_by_tool].freeze
+
+      # The SessionMetrics::Usage ctx.usage returns for the recorder's
+      # +usage+ value (Recorder::DEFAULTS): zeros for the parts not given;
+      # tool_calls defaults to the sum of tool_calls_by_tool, active_ms to
+      # the sum of tool_ms_by_tool.
+      # @return [SessionMetrics::Usage]
+      def usage(value)
+        value = value.call while value.respond_to?(:call)
+        case value
+        when nil then SessionMetrics::Usage.zero
+        when SessionMetrics::Usage then value
+        when Hash
+          parts = value.transform_keys(&:to_sym)
+          unknown = parts.keys - USAGE_PARTS
+          raise ArgumentError, "unknown usage parts: #{unknown.join(", ")}" unless unknown.empty?
+
+          by_tool = parts.fetch(:tool_calls_by_tool, {}).transform_keys(&:to_s)
+          ms_by_tool = parts.fetch(:tool_ms_by_tool, {}).transform_keys(&:to_s)
+          SessionMetrics::Usage.new(turns: parts.fetch(:turns, 0), tool_calls: parts.fetch(:tool_calls, by_tool.values.sum),
+                                    tool_calls_by_tool: by_tool, steps: parts.fetch(:steps, 0),
+                                    active_ms: parts.fetch(:active_ms, ms_by_tool.values.sum), tool_ms_by_tool: ms_by_tool)
+        else raise ArgumentError, "usage: a Hash or a callable, not #{value.inspect}"
+        end
+      end
     end
 
     # The hook runtime (Hooks::Runtime: event[:notify] and the other

data/lib/samagotchi/testing/recorder.rb

@@ -12,6 +12,8 @@ module Samagotchi
     Notice = Data.define(:text, :level, :hook, :fallback_for)
     # Text put into the running turn (ctx.steer, event[:steer]).
     Steer = Data.define(:text, :hook)
+    # A ctx.load_tools call: the names given, and the bundle.
+    ToolLoad = Data.define(:names, :bundle)
     # A stop_turn or stop_generation (+kind+ :turn or :generation).
     Stop = Data.define(:kind, :reason, :hook)
     # An ask_model request: the request Context built (SideQuestion), its
@@ -32,13 +34,17 @@ module Samagotchi
       DEFAULTS = {
         session_id: "test-session", cwd: nil, messages: [], messages_partial: false, model_name: "test:model",
         model_key: "model", toolkit: "full", declared_tools: nil, frontend: :worker, scratch: false, setup: nil,
-        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true,
+        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true, load_tools_staged: nil,
         # ctx.cost: nil (zero), a Float (reported USD), a Hash of the parts
         # (reported:, estimated:, side:, known:) or a callable giving one.
-        cost: nil
+        cost: nil,
+        # ctx.usage: nil (zero), a Hash of the parts (turns:, tool_calls:,
+        # tool_calls_by_tool:, steps:, active_ms:, tool_ms_by_tool:) or a
+        # callable giving one.
+        usage: nil
       }.freeze
 
-      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :answers,
+      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,
                   :model_answers, :values
 
       def initialize(**values)
@@ -53,6 +59,7 @@ module Samagotchi
         @questions = []
         @model_requests = []
         @toolkit_uses = []
+        @tool_loads = []
         @answers = []
         @model_answers = []
         @mutex = Mutex.new
@@ -127,6 +134,14 @@ module Samagotchi
         answer.respond_to?(:call) ? answer.call(entry) : answer
       end
 
+      # ctx.load_tools: recorded; every name is staged unless the test set
+      # load_tools_staged: (a list: those only).
+      def load_tools(names, bundle)
+        record(@tool_loads, ToolLoad.new(names: names, bundle: bundle))
+        staged = self[:load_tools_staged]
+        staged ? names & Array(staged) : names
+      end
+
       # ctx.use_toolkit: +known+ the toolkits chi and the plugins declare.
       # Staged (toolkit_staged:, true by default), the session is on it at
       # once, as chi saves it on the session (ToolkitBinding#use).

data/lib/samagotchi/tool_loads.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The tools plugins load (ctx.load_tools), staged until a turn's messages
+  # are built (Engine#turn_messages): then each bundle's names go into the
+  # conversation as one system entry of kind KIND, which a host that takes
+  # tool changes (LLM::AnthropicMessages#tool_changes?) receives as a
+  # tool_addition by reference. The names are wire names a request declares
+  # deferred (Tools::DeferredTools): a built-in's, a source tool's acts_as.
+  # Staging is idempotent: a name already staged is staged once.
+  class ToolLoads
+    KIND = "tool_change"
+    # The entry's key for what it adds: {add: [names], by: bundle}.
+    KEY = :tool_change
+
+    def initialize
+      @mutex = Mutex.new
+      @staged = {}
+    end
+
+    # Stage +names+ for bundle +by+.
+    # @return [Array<String>] the names newly staged
+    def stage(names, by:)
+      @mutex.synchronize do
+        taken = @staged.values.flatten
+        fresh = names.uniq - taken
+        (@staged[by.to_s] ||= []).concat(fresh) unless fresh.empty?
+        fresh
+      end
+    end
+
+    def any? = @mutex.synchronize { @staged.any? }
+
+    # The staged names per bundle, cleared.
+    # @return [Hash{String => Array<String>}]
+    def take
+      @mutex.synchronize do
+        staged = @staged
+        @staged = {}
+        staged
+      end
+    end
+
+    # The conversation entry for bundle +by+'s +names+.
+    def self.entry(names, by:)
+      { role: "system", kind: KIND, content: "[tools loaded: #{names.join(", ")} (#{by})]",
+        KEY => { add: names, by: by } }
+    end
+
+    # Whether +entry+ is one of #entry's (string or symbol keys).
+    def self.entry?(entry) = entry.is_a?(Hash) && (entry[:kind] || entry["kind"]).to_s == KIND
+
+    # The names +messages+' tool change entries added.
+    # @return [Array<String>]
+    def self.added(messages)
+      Array(messages).select { |entry| entry?(entry) }.flat_map do |entry|
+        change = entry[KEY] || entry[KEY.to_s] || {}
+        Array(change[:add] || change["add"]).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_response.rb

@@ -14,6 +14,8 @@ module Samagotchi
     # run's chi-owned id, ToolIds, and a strategy's edits by id,
     # LLMContextEdit); the prompt never renders them.
     SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_refs tool_ids edits].freeze
+    # The tools a chat result loaded (#single), saved with it.
+    LOADED = :loaded
     # A run's "[name]" lead: the name, then a newline, a space or the end.
     LEAD = /\A\[([^\]\s]+)\](?:\n| |\z)/
 
@@ -90,7 +92,8 @@ module Samagotchi
 
     # The chat loop's entry for one call: its capped output, paired with the
     # call by +tool_call_id+, and its chi-owned id (a one-id +ids+, as
-    # #joined's tool_ids).
+    # #joined's tool_ids); a find_tools hit's +loaded+ names (saved on every
+    # chat backend: a wire that loads tools renders them, LLM::AnthropicWire).
     def single(run, tool_call_id:, ids:)
       entry = { role: "tool_response", content: run.capped_output, tool_call_id: tool_call_id }
       entry[:images] = run.images if run.images&.any?
@@ -99,6 +102,7 @@ module Samagotchi
       entry[:tool_diffs] = run.diff if run.diff
       entry[:tool_refs] = run.refs if run.refs
       entry[:tool_ids] = ids
+      entry[LOADED] = run.loaded if run.loaded&.any?
       entry
     end
 

data/lib/samagotchi/tool_runner.rb

@@ -17,11 +17,13 @@ require_relative "memory_bundle/index_size"
 module Samagotchi
   # One call's result from ToolRunner#run, read by ToolResponse (the loops'
   # tool_response entries) and the loops' activity list. Fields a call didn't
-  # produce (images, shown_params, shown_label, refs, diff, output_file) are nil.
+  # produce (images, shown_params, shown_label, refs, diff, output_file,
+  # loaded) are nil. +loaded+: the tools a find_tools hit loads
+  # (Tools::ToolIndex::FoundText#loaded), by their wire names.
   ToolRun = Data.define(:output, :capped_output, :truncated, :activity, :images, :shown_params, :shown_label, :refs, :diff,
-                        :output_file) do
+                        :output_file, :loaded) do
     def initialize(output: nil, capped_output: nil, truncated: nil, activity: nil, images: nil, shown_params: nil,
-                   shown_label: nil, refs: nil, diff: nil, output_file: nil)
+                   shown_label: nil, refs: nil, diff: nil, output_file: nil, loaded: nil)
       super
     end
   end
@@ -150,7 +152,8 @@ module Samagotchi
       ToolRun.new(output: output, capped_output: capped, truncated: truncated, activity: result[:activity],
                   images: images&.any? ? images : nil,
                   shown_params: params && plugin_tool?(call[:name]) ? params : nil,
-                  shown_label: label, refs: refs.empty? ? nil : refs, diff: diff, output_file: output_file)
+                  shown_label: label, refs: refs.empty? ? nil : refs, diff: diff, output_file: output_file,
+                  loaded: result[:loaded])
     end
 
     private
@@ -317,29 +320,48 @@ module Samagotchi
     def layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
 
     # The call its tool's entry unwraps it to (call_tool on a built-in),
-    # else the call as it is. One that fails runs as it is: call_tool then
-    # refuses a built-in (fail closed).
+    # else the call as it is. On a host that loads tools, a direct call of
+    # a source's tool by its acts_as runs as the call_tool call first
+    # (Registry::Index#wrap): call_tool's row, rules and approvals. One
+    # that fails runs as it is: call_tool then refuses a built-in (fail
+    # closed).
     def unwrapped(call)
       registry = tools
       return call unless registry.respond_to?(:offered) && !call[:name].nil?
 
+      call = wrapped(registry, call)
       registry.offered(call[:name], layers: layers)&.unwrap&.call(call, layers) || call
     rescue StandardError => e
       Log.warn(:turn, "tool_unwrap_failed", tool: call[:name].to_s, error: "#{e.class}: #{e.message}")
       call
     end
 
+    # +call+ as the call_tool call it runs as when it names a deferred
+    # source tool, on a host that loads tools; else as it is.
+    def wrapped(registry, call)
+      wrap = registry.respond_to?(:index) ? registry.index&.wrap : nil
+      return call unless wrap && loads_tools? && !registry.key?(call[:name])
+
+      wrap.call(call) || call
+    end
+
     # A call that can't run in this turn as it is, by its name: a real tool
     # the session's toolkit leaves out, or one reached through call_tool
-    # (via:) that the toolkit doesn't reach that way (a hook's rewrite).
+    # (via:) that the toolkit doesn't reach that way (a hook's rewrite). On
+    # a host that loads tools, a built-in the toolkit reaches runs by its
+    # own name (KernelLoop#dispatch takes it too).
     def left_out?(call)
       registry = tools
       return false unless registry.respond_to?(:left_out) && !call[:name].nil?
       return registry.indexed(call[:name], layers: layers).nil? if call[:via]
+      return false if loads_tools? && registry.indexed(call[:name], layers: layers)
 
       !registry.left_out(call[:name], layers: layers).nil?
     end
 
+    # Whether the turn's host loads tools (TurnSettings#loads_tools).
+    def loads_tools? = @kernel.respond_to?(:turn_settings) && @kernel.turn_settings&.loads_tools == true
+
     # A tool the registry has from a plugin (not core, not unknown).
     def plugin_tool?(name)
       entry = tools && !name.nil? ? tools[name] : nil

data/lib/samagotchi/tools/builtin_calls.rb

@@ -166,6 +166,22 @@ module Samagotchi
         build(name, saved_args(call[:args]["args"])).merge(via: VIA)
       end
 
+      # A saved direct call of a deferred source tool (an MCP tool by its
+      # acts_as, on a host that loads tools) as the call_tool call it ran as
+      # (ToolIndex#wrap): a name that is no built-in, object args, and a
+      # result that leads with "[call_tool]". Any other call as it is. The
+      # tool is named by its acts_as (the call tool takes it as well).
+      # @param call [Hash] as #build gives it
+      # @param output [String, nil]
+      # @return [Hash]
+      def wrap_saved(call, output)
+        name = call[:name].to_s
+        return call if name.empty? || name == VIA || row(name) || !call[:args].is_a?(Hash)
+        return call unless output.to_s[SAVED_LEAD, 1] == VIA
+
+        build(VIA, { "tool" => name, "args" => call[:args] })
+      end
+
       def ran_as?(output, name)
         lead = output[SAVED_LEAD, 1]
         lead ? lead == name : output.start_with?("Error: #{name} ")

data/lib/samagotchi/tools/deferred_tools.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../tool_declarations"
+
+module Samagotchi
+  module Tools
+    # The tools a request declares deferred (defer_loading: true) on a host
+    # that loads tools (LLM::AnthropicMessages#loads_tools?): every tool the
+    # session reaches but doesn't declare, so a find_tools hit can load it
+    # and the model calls it by its own name. In order:
+    # 1. the built-ins the toolkit leaves out but doesn't remove
+    #    (Registry#reachable_names), in registry order;
+    # 2. the tool index's source tools (an MCP server's, by acts_as), only
+    #    while call_tool is declared (ToolIndex#deferrable: sorted by name);
+    # 3. every other name the conversation loaded (a find result's
+    #    loaded:, a tool change's add:) that isn't declared: a stub (its
+    #    source is gone, or hasn't published yet), so the reference in the
+    #    history stays valid. The runner refuses its calls as any other.
+    # The list goes after the declared tools, outside the cached prefix's
+    # marks: a tool joining it (a late server) keeps the cache.
+    module DeferredTools
+      # One deferred tool: its wire name, description and input schema.
+      Deferred = Data.define(:name, :description, :schema)
+
+      STUB_DESCRIPTION = "Not available right now; find_tools finds it when it is."
+      STUB_SCHEMA = { "type" => "object", "properties" => {} }.freeze
+
+      module_function
+
+      # @param registry [Registry]
+      # @param conversation [Array<Hash>, nil] the request's (engine format)
+      # @param layers [Array<Symbol>] the turn's LLM context layers
+      # @return [Array<Deferred>]
+      def list(registry, conversation, layers: [])
+        deferred = builtins(registry, layers) + sourced(registry, layers)
+        taken = deferred.map(&:name)
+        loaded_names(conversation).each do |name|
+          next if taken.include?(name) || registry.offered(name, layers: layers)
+
+          taken << name
+          deferred << Deferred.new(name: name, description: STUB_DESCRIPTION, schema: STUB_SCHEMA)
+        end
+        deferred
+      end
+
+      # The names +conversation+ loaded, first reference first: a find
+      # result's loaded: (ToolResponse::LOADED), a tool change's add:.
+      # @return [Array<String>]
+      def loaded_names(conversation)
+        Array(conversation).flat_map do |entry|
+          names = entry[:loaded] || entry["loaded"]
+          change = entry[:tool_change] || entry["tool_change"]
+          names = change[:add] || change["add"] if change.is_a?(Hash)
+          Array(names).map(&:to_s)
+        end.uniq
+      end
+
+      def builtins(registry, layers)
+        return [] unless registry.respond_to?(:reachable_names)
+
+        registry.reachable_names(layers: layers).map do |name|
+          schema = ToolDeclarations.chat_schemas([registry[name].schema]).first
+          Deferred.new(name: name, description: schema[:description].to_s, schema: schema[:parameters])
+        end
+      end
+
+      def sourced(registry, layers)
+        index = registry.respond_to?(:index) ? registry.index : nil
+        return [] unless index&.deferrable && registry.offered(index.call_name, layers: layers)
+
+        index.deferrable.call.map do |tool|
+          Deferred.new(name: tool.acts_as, description: tool.description, schema: tool.schema)
+        end
+      end
+
+      private_class_method :builtins, :sourced
+    end
+  end
+end

data/lib/samagotchi/tools/registry.rb

@@ -41,8 +41,13 @@ module Samagotchi
       # What Tools::ToolIndex#declare registered: the entries of +source+
       # are the index's search and call tools, +call_name+ the call tool's
       # name, and +sourced+ whether a source (an MCP server's bundle)
-      # registered when the plugins loaded.
-      Index = Data.define(:source, :call_name, :sourced)
+      # registered when the plugins loaded. +deferrable+ (→ the sources'
+      # tools a host that loads tools may declare deferred) and +wrap+
+      # (call → the call_tool call a direct call of one of them runs as, or
+      # nil) are nil when nothing reaches them.
+      Index = Data.define(:source, :call_name, :sourced, :deferrable, :wrap) do
+        def initialize(source:, call_name:, sourced:, deferrable: nil, wrap: nil) = super
+      end
 
       def initialize
         @entries = {}