samagotchi 0.154.1 → 0.155.0

data/lib/samagotchi/tool_response.rb

@@ -34,14 +34,15 @@ module Samagotchi
     # own go to +on_stream_event+. An Interrupt (Ctrl-C) mid-batch yields an
     # #interrupted run for every call left (the one it cut short too), so
     # the loop's conversation answers each call, then goes on up: the turn
-    # keeps its progress (Engine#ctrl_c_messages).
+    # keeps its progress (Engine#ctrl_c_messages). +context+: the calls'
+    # turn (TurnContext), each run's (ToolRunner#run).
     # @return [Array<ToolRun>] the runs
-    def run_batch(runner, calls, iteration:, emit:, on_stream_event:, cap:)
+    def run_batch(runner, calls, context:, iteration:, emit:, on_stream_event:, cap:)
       # Before anything can be interrupted: the rescue counts it.
       runs = []
       emit.call({ type: :tool_dispatch_started, iteration: iteration, call_count: calls.length })
       calls.each_with_index do |call, index|
-        runs << runner.run(call, iteration: iteration, call_index: index + 1, call_count: calls.length,
+        runs << runner.run(call, context: context, iteration: iteration, call_index: index + 1, call_count: calls.length,
                                  on_stream_event: on_stream_event, max_tool_output_chars: cap)
         yield runs.last, index if block_given?
       end

data/lib/samagotchi/tool_runner.rb

@@ -14,6 +14,7 @@ require_relative "tool_output_cut"
 require_relative "tool_output_files"
 require_relative "tools/output_guardrails"
 require_relative "tools/tool_path"
+require_relative "tools/tool_surface"
 require_relative "tools/memory"
 require_relative "config"
 require_relative "memory_bundle/index_sync"
@@ -53,14 +54,20 @@ module Samagotchi
     NOT_AN_EDIT = Object.new.freeze
     private_constant :NOT_AN_EDIT
 
-    # @param kernel [KernelLoop] read lazily: Engine sets its hooks after
-    #   the kernel is built.
+    # What a call needs of its turn comes with it: #run's +context:+ (a
+    # TurnContext: the session's folders, the settings' vision, its
+    # ToolSurface, the participant's mode), passed on to the gate and the
+    # kernel's dispatch.
+    #
+    # @param kernel [KernelLoop] its services (KernelLoop::Services: hooks,
+    #   tools, gate) are read per call: a spec's kernel may #attach new ones.
     # @param clock [#call] monotonic seconds, for the approval wait and the
     #   dispatch time (after_tool_call's elapsed_ms)
-    # @param window [#call, nil] → ContextWindow::Resolved or nil: the
-    #   model's window, for memory_read's overflow guard. nil: the kernel's
-    #   own reader (KernelLoop#tool_output_window); a loop whose window comes
-    #   from more than the kernel's client (LLM::ChatLoop's adapter) passes it.
+    # @param window [#call, nil] (settings) → ContextWindow::Resolved or nil:
+    #   the model's window under the turn's LLM::TurnSettings, for
+    #   memory_read's overflow guard. nil: the kernel's own reader
+    #   (KernelLoop#tool_output_window); a loop whose window comes from more
+    #   than the kernel's client (LLM::ChatLoop's adapter) passes it.
     def initialize(kernel, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, window: nil)
       @kernel = kernel
       @clock = clock
@@ -78,29 +85,30 @@ module Samagotchi
     #   RowRefs; saved likewise), and diff: what an edit/write changed in its
     #   file (EditPreview.change; also on tool_call_completed, never in the
     #   model's output)
-    def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
+    # @param context [TurnContext] the call's turn
+    def run(call, context:, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
       # A call_tool of one of chi's own tools runs as that tool, from here
       # on (the gate, the row, the result): rules, approvals and hooks see
       # the real call, with via: (Tools::ToolIndex#unwrap).
-      call = unwrapped(call)
-      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
+      call = unwrapped(call, context)
+      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools, surface: surface(context))
       # The gate runs first, so tool_call_started shows the call that runs.
       # A tool the session's toolkit leaves out skips it: no before_tool_call
       # hook, no approval card for a call that can't run (KernelLoop#dispatch
       # answers it with the not-loaded error).
       original = call.dup
-      refusal = unreached_group_refusal(call)
+      refusal = unreached_group_refusal(call, context)
       verdict = if refusal
                   Guardrails::Verdict.new(call: call).deny!(refusal.message,
                                                             rule: Tools::ToolIndex::ToolkitGroupRefusal::RULE,
                                                             source: "core", decided_by: "core")
-                elsif left_out?(call)
+                elsif left_out?(call, context)
                   Guardrails::Verdict.new(call: call)
                 else
-                  evaluate(call, iteration, params)
+                  evaluate(call, context, iteration, params)
                 end
       call = verdict.call
-      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
+      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools, surface: surface(context))
       label = plugin_label(call[:name])
       # Kept on the raw event for in-worker hooks and metrics, not sent to SSE clients.
       started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
@@ -110,7 +118,7 @@ module Samagotchi
       # plugin tool's refs); the worker runs in its session's working
       # directory.
       fields = ToolRowFields.for(call[:name], call, cwd: Dir.pwd)
-      refs = RowRefs.for(tools && !call[:name].nil? ? tools[call[:name]]&.refs : nil, call, cwd: session_cwd)
+      refs = RowRefs.for(tools && !call[:name].nil? ? tools[call[:name]]&.refs : nil, call, cwd: session_cwd(context))
       fields[:refs] = refs unless refs.empty?
       started.merge!(fields)
       emit(on_stream_event, started)
@@ -121,7 +129,7 @@ module Samagotchi
       waited_ms = nil
       if verdict.ask?
         asked_at = @clock.call
-        settle_ask(verdict)
+        settle_ask(verdict, context)
         waited_ms = ((@clock.call - asked_at) * 1000).round
       end
       before = verdict.deny? ? NOT_AN_EDIT : file_before(call)
@@ -129,10 +137,10 @@ module Samagotchi
       entry_before = before.equal?(NOT_AN_EDIT) ? nil : MemoryBundle::EntrySize.measure_file(Tools::ToolPath.normalize(call[:path]))
       elapsed_ms = nil
       if verdict.deny?
-        result = denied(call, verdict)
+        result = denied(call, verdict, context)
       else
         dispatched_at = @clock.call
-        result = dispatch(call)
+        result = dispatch(call, context)
         elapsed_ms = ((@clock.call - dispatched_at) * 1000).round
       end
       diff = file_change(call, before)
@@ -141,7 +149,7 @@ module Samagotchi
         result = with_entry_note(result, entry_before, call)
       end
       result = approved(result, verdict) if verdict.allow? && verdict.decided_by
-      result, images = attach_images(call, result) if result[:images]
+      result, images = attach_images(call, result, context.settings&.vision) if result[:images]
 
       output = scrub(result[:output].to_s)
       # The tool's own text, for after_tool_call: no "[tool]" lead, no
@@ -149,12 +157,12 @@ module Samagotchi
       tool_text = output.sub(/\A\[#{Regexp.escape(call[:name].to_s)}\](?:\n| )/, "")
       # The gate may have replaced the call (known-names corrects a near
       # miss): one leading line tells the model what actually ran.
-      if (changed = changed_call_line(original, call))
+      if (changed = changed_call_line(original, call, context))
         output = "#{changed}\n#{output}"
       end
-      cap = output_cap(call, max_tool_output_chars)
+      cap = output_cap(call, max_tool_output_chars, context)
       truncated = !cap.nil? && output.length > cap
-      capped, saved = truncated ? cut(call, output, cap, result) : output
+      capped, saved = truncated ? cut(call, output, cap, result, context) : output
       output_file = saved.path if saved.is_a?(ToolOutputFiles::Saved)
 
       # The call's outcome as its activity line has it (worked out from the
@@ -180,7 +188,7 @@ module Samagotchi
                   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,
-                  loaded: result[:loaded], stamp: status == "ok" ? file_stamp(call) : nil)
+                  loaded: result[:loaded], stamp: status == "ok" ? file_stamp(call, context) : nil)
     end
 
     private
@@ -189,8 +197,8 @@ module Samagotchi
     # {path:, mtime_ns:, size:}, the path as FileRef has it (against the
     # session's folder, no realpath). nil for any other tool, a path it
     # can't place and a stat that fails or isn't a file's.
-    def file_stamp(call)
-      ref = FileRef.for(call[:name], call, cwd: session_cwd)
+    def file_stamp(call, context)
+      ref = FileRef.for(call[:name], call, cwd: session_cwd(context))
       return nil unless ref
 
       stat = File.stat(ref.path)
@@ -209,8 +217,9 @@ module Samagotchi
     #   for task_wait and delegate; ref_stderr_path, a task's stderr log
     # @return [Array(String, Object)] the text, and the saved file (or why
     #   there is none) when it was cut that way
-    def cut(call, output, cap, result)
-      ToolOutputCut.apply(output, cap: cap, tool: call[:name], save: ->(text, dry: false) { save_output(call, text, dry: dry) },
+    def cut(call, output, cap, result, context)
+      ToolOutputCut.apply(output, cap: cap, tool: call[:name],
+                                  save: ->(text, dry: false) { save_output(call, text, context.session_dir, dry: dry) },
                                   line: (memory_cut_line(call) if call[:name] == MEMORY_READ),
                                   ref: result[:ref_path], ref_stderr: result[:ref_stderr_path],
                                   head_chars: Tools::OutputGuardrails.config_positive_int("execute.cut_head_chars",
@@ -223,11 +232,11 @@ module Samagotchi
     # for every tool but memory_read, which memory.read_max_chars caps (0:
     # no fixed cap) and, with none set, a known window's half (#window_guard).
     # A nil +cap+ stays nil.
-    def output_cap(call, cap)
+    def output_cap(call, cap, context)
       return cap unless cap && call[:name] == MEMORY_READ
 
       fixed = Config.get("memory.read_max_chars").to_i
-      fixed.positive? ? fixed : window_guard
+      fixed.positive? ? fixed : window_guard(context.settings)
     end
 
     # Half the model's context window in characters, the most one memory_read
@@ -235,9 +244,9 @@ module Samagotchi
     # and a retry repeats the read). nil when the window isn't known (the
     # default isn't a window) or can't be read. It checks this result, not the
     # context already used.
-    def window_guard
+    def window_guard(settings)
       Degrade.call(:memory, "read_window_unknown") do
-        window = @window ? @window.call : (@kernel.tool_output_window if @kernel.respond_to?(:tool_output_window))
+        window = @window ? @window.call(settings) : (@kernel.tool_output_window(settings) if @kernel.respond_to?(:tool_output_window))
         return nil unless window&.tokens&.positive? && window.source != :default
 
         (window.tokens * MemoryBundle::IndexSize.chars_per_token / 2).floor
@@ -254,12 +263,12 @@ module Samagotchi
     end
 
     # The whole output in the session's tool_output folder
-    # (ToolOutputFiles), or why it isn't saved: no session (a bare kernel)
-    # or the error's class. Never fails the call. +dry+: where it would go,
-    # nothing written (ToolOutputFiles.planned).
+    # (ToolOutputFiles; +dir+: the turn's TurnContext#session_dir), or why it
+    # isn't saved: no session (a bare kernel) or the error's class. Never
+    # fails the call. +dry+: where it would go, nothing written
+    # (ToolOutputFiles.planned).
     # @return [ToolOutputFiles::Saved, String]
-    def save_output(call, text, dry: false)
-      dir = session_dir
+    def save_output(call, text, dir, dry: false)
       return "no session" if dir.to_s.empty?
       return ToolOutputFiles.planned(dir, text, tool: call[:name]) if dry
 
@@ -269,15 +278,6 @@ module Samagotchi
       e.class.name
     end
 
-    # The session's folder (KernelLoop#session_dir), nil for a bare kernel
-    # or a lookup that failed.
-    def session_dir
-      @kernel.respond_to?(:session_dir) ? @kernel.session_dir&.call : nil
-    rescue StandardError => e
-      Log.warn(:turn, "tool_output_save_failed", error: e.class.name)
-      nil
-    end
-
     # edit/write only: the file just before the call runs. The row diffs it
     # with the file after, whatever the result says, so an edit that fails
     # after writing still shows its change and one that wrote nothing shows
@@ -351,8 +351,8 @@ module Samagotchi
     # and keeps the text and the other images; for read, whose text only
     # says the image is attached, that line replaces the text.
     # @return [Array(Hash, Array<Hash>)] the result and its refs
-    def attach_images(call, result)
-      vision = @kernel.turn_settings.vision
+    # +vision+: the turn's VisionContext (TurnSettings#vision).
+    def attach_images(call, result, vision)
       reason = if vision.nil? then "images can't be attached here"
                elsif !vision.sendable? then ImagePlan::CANT_SEE
                end
@@ -397,17 +397,19 @@ module Samagotchi
       [result[:output], *notes].join("\n")
     end
 
-    # The session's folder (the Engine's, KernelLoop#session_cwd), else the
+    # The session's folder (the turn's TurnContext#cwd), else the
     # process's: a bare kernel (specs) has none.
-    def session_cwd
-      cwd = @kernel.session_cwd&.call if @kernel.respond_to?(:session_cwd)
+    def session_cwd(context)
+      cwd = context.cwd
       cwd.to_s.empty? ? Dir.pwd : cwd
     end
 
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 
-    def layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
+    # The turn's Tools::ToolSurface (+context+'s), else one computed now
+    # from the kernel's tools (a runner outside an Engine turn).
+    def surface(context) = Tools::ToolSurface.of(context, tools)
 
     # The call its tool's entry unwraps it to (call_tool on a built-in),
     # else the call as it is. On a host that loads tools, a direct call of
@@ -415,12 +417,12 @@ module Samagotchi
     # (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?
+    def unwrapped(call, context)
+      return call if tools.nil? || call[:name].nil?
 
-      call = wrapped(registry, call)
-      registry.offered(call[:name], layers: layers)&.unwrap&.call(call, layers) || call
+      surface = surface(context)
+      call = wrapped(surface, call)
+      surface.declared_entry(call[:name])&.unwrap&.call(call, surface) || call
     rescue StandardError => e
       Log.warn(:turn, "tool_unwrap_failed", tool: call[:name].to_s, error: "#{e.class}: #{e.message}")
       call
@@ -428,11 +430,11 @@ module Samagotchi
 
     # +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])
+    def wrapped(surface, call)
+      wrap = surface.index&.wrap
+      return call unless wrap && surface.loads_tools && !surface.registered?(call[:name])
 
-      wrap.call(call) || call
+      wrap.call(call, surface) || call
     end
 
     # A call that can't run in this turn as it is, by its name: a real tool
@@ -440,23 +442,25 @@ module Samagotchi
     # (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)
+    def left_out?(call, context)
+      return false if tools.nil? || call[:name].nil?
+
+      surface = surface(context)
+      return surface.indexed_entry(call[:name]).nil? if call[:via]
+      return false if surface.loads_tools && surface.indexed_entry(call[:name])
 
-      !registry.left_out(call[:name], layers: layers).nil?
+      surface.left_out?(call[:name])
     end
 
-    def unreached_group_refusal(call)
+    def unreached_group_refusal(call, context)
       # A review turn's boundary denies it first (and words why); a pair
       # turn gets the owner's refusal.
-      return if participant_turn? && participant_mode != ParticipantMode::PAIR
+      return if context.participant? && context.participant_mode != ParticipantMode::PAIR
+      return if tools.nil?
 
-      registry = tools
-      index = registry&.index if registry.respond_to?(:index)
-      return unless index.respond_to?(:unreached_tool)
+      surface = surface(context)
+      index = surface.index
+      return unless index
 
       name = if call[:name] == index.call_name
                args = call[:args].is_a?(Hash) ? call[:args] : {}
@@ -464,24 +468,10 @@ module Samagotchi
              else
                call[:name]
              end
-      tool = index.unreached_tool(name)
-      tool && Tools::ToolIndex::ToolkitGroupRefusal.for(tool, registry)
+      tool = index.unreached_tool(name, surface)
+      tool && Tools::ToolIndex::ToolkitGroupRefusal.for(tool, surface)
     end
 
-    def participant_turn?
-      @kernel.respond_to?(:participant_turn?) && @kernel.participant_turn?
-    end
-
-    # The running participant turn's mode (KernelLoop#participant_mode,
-    # GuardrailWiring#turn_mode), nil without one.
-    def participant_mode
-      lookup = @kernel.respond_to?(:participant_mode) ? @kernel.participant_mode : nil
-      lookup&.call
-    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
@@ -495,29 +485,30 @@ module Samagotchi
     # asked for: "ran as: <tool> <changed args>", or nil when nothing
     # changed. The args are the changed call's activity params, so the line
     # stays short.
-    def changed_call_line(original, call)
+    def changed_call_line(original, call, context)
       return nil if original == call
 
-      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
+      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools, surface: surface(context))
       ["ran as: #{call[:name]}", params].compact.join(" ")
     end
 
-    # The Engine sets the kernel's gate (its context, later the approval
-    # flow); a bare kernel (specs) gets one that only runs the hooks.
+    # The kernel's gate (the Engine's, KernelLoop::Services#gate: its
+    # context, the approval flow); a bare kernel (specs) gets one that only
+    # runs its hooks, built per call from what the kernel holds now.
     def gate
-      @kernel.guardrail_gate || (@gate ||= Guardrails::Gate.new(-> { @kernel.hooks }, tools_lookup: -> { tools }))
+      @kernel.guardrail_gate || Guardrails::Gate.new(hooks: @kernel.hooks, tools: tools)
     end
 
     # A gate that fails denies the call (fail closed).
-    def evaluate(call, iteration, params)
-      gate.evaluate(call, iteration: iteration, params: params)
+    def evaluate(call, context, iteration, params)
+      gate.evaluate(call, context: context, iteration: iteration, params: params)
     rescue StandardError => e
       Guardrails::Verdict.new(call: call).deny!("the guardrail check failed: #{e.class}: #{e.message}",
                                                 decided_by: "core")
     end
 
-    def settle_ask(verdict)
-      gate.settle_ask(verdict)
+    def settle_ask(verdict, context)
+      gate.settle_ask(verdict, context: context)
     rescue StandardError => e
       verdict.settle!(:deny, decided_by: "core", note: "The approval failed (#{e.class}: #{e.message}).")
     end
@@ -531,10 +522,10 @@ module Samagotchi
 
     # A legacy veto keeps its old text; a verdict's deny tells the model
     # who decided and not to route around it.
-    def denied(call, verdict)
+    def denied(call, verdict, context)
       if verdict.rule == Tools::ToolIndex::ToolkitGroupRefusal::RULE
         output = "[#{call[:name]}] #{verdict.reason}"
-        activity = ToolActivity.tool_activity_event(call[:name], call, output, registry: tools)
+        activity = ToolActivity.tool_activity_event(call[:name], call, output, registry: tools, surface: surface(context))
         return { output: output, activity: activity.merge(status: "blocked", guardrail: verdict.to_activity) }
       end
 
@@ -544,14 +535,14 @@ module Samagotchi
                else
                  "[#{call[:name]}] Error: #{verdict.deny_text}"
                end
-      activity = ToolActivity.tool_activity_event(call[:name], call, output, registry: tools)
+      activity = ToolActivity.tool_activity_event(call[:name], call, output, registry: tools, surface: surface(context))
       { output: output, activity: activity.merge(status: "blocked", guardrail: verdict.to_activity) }
     end
 
     # KernelLoop#dispatch turns tool errors into "[name] Error: …" itself;
     # this rescue only catches a failing dispatcher.
-    def dispatch(call)
-      @kernel.dispatch_tool_call(call)
+    def dispatch(call, context)
+      @kernel.dispatch_tool_call(call, context)
     rescue StandardError => e
       { output: "[#{call[:name]}] Error: #{e.class}: #{e.message}", activity: nil }
     end

data/lib/samagotchi/toolkit_binding.rb

@@ -5,6 +5,7 @@ require_relative "memory_paths"
 require_relative "model_overlay"
 require_relative "muted_memories"
 require_relative "toolkit"
+require_relative "tools/tool_surface"
 require "yaml"
 
 module Samagotchi
@@ -13,6 +14,12 @@ module Samagotchi
   # ctx.use_toolkit (#use) and the turn-start apply into the tool Registry
   # (#apply!), with its load warnings said once per process.
   #
+  # Its readers off the turn thread (#explained: /toolkit, the snapshot,
+  # the plugin host's declared_tools; ctx.load_tools) read #published, the
+  # Registry as the turn thread last published it (#publish!: the Engine's
+  # build, a turn's start), never the live one. #kits' lazy reads may run
+  # on any thread: each one stores what any other would.
+  #
   # What it needs from the Engine comes through lookups, called at use.
   class ToolkitBinding
     # @param tools        [#call] → Tools::Registry
@@ -45,6 +52,21 @@ module Samagotchi
     # @return [Array<Toolkit::Kit>] the plugins' kits (Plugin::Registries' toolkits:)
     attr_reader :plugin_kits
 
+    # Publish the Registry as it is now (Tools::Registry#snapshot), on the
+    # turn thread or at the Engine's build only: after the tool index is
+    # declared, after a turn's staged tool sets and its toolkit apply.
+    # One assignment of a frozen value.
+    # @return [Tools::Registry] the snapshot
+    def publish!
+      @published = @tools.call.snapshot
+    end
+
+    # The Registry as last published (#publish!); before the first publish
+    # (a plugin reading while the Engine is built, on its thread), the
+    # Registry read now.
+    # @return [Tools::Registry]
+    def published = @published || @tools.call.snapshot
+
     # The kits a session's toolkit resolves against: built-ins, config,
     # plugins, then project and system memory kits. Config and memory kits
     # are read once per worker, like the plugins': edits take effect when a
@@ -77,17 +99,18 @@ module Samagotchi
     end
 
     # +toolkit+ (the session's by default) as its next turn would declare
-    # it (/toolkit, the UIs' chip).
+    # it (/toolkit, the UIs' chip): the #published Registry read now as a
+    # Tools::ToolSurface under that toolkit.
     # @return [Toolkit::Explained]
     def explained(toolkit = nil)
       toolkit ||= Toolkit.of(@session.call&.toolkit)
       resolved = toolkit.resolve(kits)
       filter = resolved.everything? ? nil : resolved
-      tools = @tools.call
-      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: tools.entries(toolkit: filter),
-                             left_out: tools.left_out_names(toolkit: filter),
-                             reachable: tools.reachable_names(toolkit: filter),
-                             removed: tools.removed_names(toolkit: filter), pending: filter != tools.toolkit)
+      tools = published
+      surface = Tools::ToolSurface.for(tools, toolkit: filter)
+      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: surface.declared,
+                             left_out: surface.left_out.keys, reachable: surface.index_only.map(&:name),
+                             removed: surface.removed, pending: filter != tools.toolkit)
     end
 
     # The session's toolkit for the UIs (the snapshot, command_ran): nil on
@@ -130,7 +153,7 @@ module Samagotchi
       true
     end
 
-    # On mode's suggestion (Engine#settle_toolkit_suggestion), on the turn
+    # On mode's suggestion (TurnStages::ToolkitSuggestion#settle), on the turn
     # thread before #apply!: put +session+ on kit +name+ with origin
     # suggested, saved, and tell the user through #use's notice path. Not
     # when the session's toolkit isn't the default any more (a /toolkit or
@@ -157,8 +180,8 @@ module Samagotchi
       true
     end
 
-    # On mode's ask gave the turn no suggestion to judge (Engine
-    # #settle_toolkit_suggestion: a timeout, no answer): say, as a warn
+    # On mode's ask gave the turn no suggestion to judge
+    # (TurnStages::ToolkitSuggestion#settle: a timeout, no answer): say, as a warn
     # notice, that +session+ runs its default (not once a toolkit was
     # chosen meanwhile). +why+ is fallback_notice's.
     def fell_back(session, why)
@@ -185,6 +208,7 @@ module Samagotchi
     # again when what it declares (or its kit's prompt text) changed. A
     # name that doesn't resolve (a typo, an uninstalled bundle) declares
     # everything for now and says so once; the saved toolkit stays as it is.
+    # Publishes the Registry it leaves (#publish!).
     # @return [Boolean] whether the declared tools (or the kit's prompt text) changed
     def apply!(session, on_event = nil)
       errors = []
@@ -200,6 +224,7 @@ module Samagotchi
         @refresh_index.call
         @reset_prompt.call
       end
+      publish!
       warn_stranded(tools)
       changed
     end
@@ -214,13 +239,14 @@ module Samagotchi
 
     # A notice (by its bundle, once per tool and worker) for each plugin
     # tool that arrived mid-session on a kit that leaves it out without
-    # the tool index to reach it (Tools::Registry#stranded_names).
+    # the tool index to reach it (Tools::ToolSurface#stranded, the
+    # Registry read now under the toolkit #apply! set).
     def warn_stranded(tools)
-      return unless tools.respond_to?(:stranded_names)
-
-      (tools.stranded_names - @stranded).each do |name|
+      surface = Tools::ToolSurface.for(tools)
+      (surface.stranded - @stranded).each do |name|
         @stranded << name
-        @notify.call(self.class.stranded_notice(name, tools.toolkit.name), :warn, tools[name]&.source.to_s, extra: {})
+        @notify.call(self.class.stranded_notice(name, surface.toolkit.name), :warn,
+                     surface.registered[name]&.source.to_s, extra: {})
       end
     end
     private :warn_stranded

data/lib/samagotchi/tools/deferred_tools.rb

@@ -10,7 +10,7 @@ module Samagotchi
     # 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 chi tools (built-ins and plugin tools) the toolkit leaves out
-    #    but doesn't remove (Registry#reachable_names), in registry order;
+    #    but doesn't remove (ToolSurface#index_only), 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
@@ -28,18 +28,17 @@ module Samagotchi
 
       module_function
 
-      # @param registry [Registry]
+      # @param surface [ToolSurface] the turn's (ToolSurface#deferred_for)
       # @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)
+      def list(surface, conversation)
+        deferred = builtins(surface) + sourced(surface)
         taken = deferred.map(&:name)
         loaded_names(conversation).each do |name|
-          next if taken.include?(name) || registry.offered(name, layers: layers)
+          next if taken.include?(name) || surface.declared_entry(name)
 
           taken << name
-          deferred << Deferred.new(name: name, description: stub_description(registry, name), schema: STUB_SCHEMA)
+          deferred << Deferred.new(name: name, description: stub_description(surface, name), schema: STUB_SCHEMA)
         end
         deferred
       end
@@ -56,30 +55,27 @@ module Samagotchi
         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])
+      def builtins(surface)
+        surface.index_only.map do |entry|
+          schema = ToolDeclarations.chat_schemas([entry.schema]).first
+          Deferred.new(name: entry.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)
+      def sourced(surface)
+        index = surface.index
+        return [] unless index&.deferrable && surface.declared_entry(index.call_name)
 
-        index.deferrable.call.map do |tool|
+        index.deferrable.call(surface).map do |tool|
           Deferred.new(name: tool.acts_as, description: tool.description, schema: tool.schema)
         end
       end
 
-      def stub_description(registry, name)
-        index = registry.respond_to?(:index) ? registry.index : nil
-        tool = index&.unreached_tool(name)
+      def stub_description(surface, name)
+        tool = surface.index&.unreached_tool(name, surface)
         return STUB_DESCRIPTION unless tool
 
-        ToolIndex::ToolkitGroupRefusal.for(tool, registry).stub_description
+        ToolIndex::ToolkitGroupRefusal.for(tool, surface).stub_description
       end
 
       private_class_method :builtins, :sourced, :stub_description