samagotchi 0.67.0 → 0.69.0

data/lib/samagotchi/session_setting.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "effective_model"
+
+module Samagotchi
+  # One per-session setting (the session's own value, before its model's):
+  # what the UIs show as a chip and the commands set. +key+ is the Session
+  # attribute and the chip's key everywhere (the session state, /stats, a
+  # :command_ran, the web's session JSON); +changed_by+ the commands'
+  # `changed` entries that move the chip; +snapshot_fallback+ how the web
+  # treats a worker snapshot's value: :or (a nil value falls back to the
+  # session file's) or :key (a key present stands, nil included: a worker
+  # says nil on a native host, which ignores reasoning_history; an older
+  # worker has no key). +chip+ the chip from an EffectiveModel and the
+  # session's own value; nil for the toolkit, which resolves against the
+  # worker's kits (Engine#toolkit_summary), not the model. +live+ the
+  # chip as an Engine's public readers give it (a :command_ran's).
+  SessionSetting = Data.define(:key, :changed_by, :snapshot_fallback, :chip, :live) do
+    # The session's own value, nil without a session or one.
+    def own(session) = session&.public_send(key)
+
+    # Sets the session's own value (nil unsets it); the caller saves.
+    def set(session, value) = session.public_send(:"#{key}=", value)
+
+    # Whether a command that changed +changed+ moves this chip.
+    def changed_by?(changed) = changed.intersect?(changed_by)
+
+    # Whether the chip comes from the model (not the toolkit).
+    def model? = !chip.nil?
+
+    # The chip for +session+ on +model+ (EffectiveModel, nil when it
+    # doesn't resolve: nil then).
+    def chip_for(model, session) = model && chip.call(model, own(session))
+
+    # The chip as +engine+ (a worker's) gives it now.
+    def summary(engine) = live.call(engine)
+
+    # The chip for a saved session no worker runs (Web::App, the session
+    # lists): resolved from its file, config and the registry (no network);
+    # nil when it can't be.
+    def saved_summary(session, registry:)
+      return saved_toolkit(session.toolkit) unless model?
+
+      chip_for(EffectiveModel.of_session(session, registry: registry), session)
+    rescue StandardError
+      nil
+    end
+
+    # The web's chip: a worker's snapshot (string keys) per
+    # +snapshot_fallback+, else the block's (the saved one).
+    def snapshot_value(snapshot)
+      name = key.to_s
+      return snapshot[name] if snapshot_fallback == :key && snapshot&.key?(name)
+      return snapshot[name] if snapshot_fallback == :or && snapshot && snapshot[name]
+
+      yield
+    end
+
+    private
+
+    # A toolkit as its file names it ({name:, label:}), nil on full:
+    # without a worker nothing resolves it (a bundle's kits load there).
+    def saved_toolkit(toolkit)
+      toolkit && !toolkit.full? ? { name: toolkit.name, label: toolkit.label } : nil
+    end
+  end
+
+  class SessionSetting
+    LLM_CONTEXT = new(key: :llm_context, changed_by: %i[llm_context model], snapshot_fallback: :or,
+                      chip: ->(model, own) { model.llm_context_explained(own&.resolve_args || {})&.summary(own) },
+                      live: lambda(&:llm_context_summary))
+    THINKING = new(key: :thinking, changed_by: %i[thinking model], snapshot_fallback: :or,
+                   chip: ->(model, own) { model.thinking_explained(own: own)&.summary },
+                   live: ->(engine) { engine.thinking_explained&.summary })
+    # nil on a native host (its loop ignores the level).
+    REASONING_HISTORY = new(key: :reasoning_history, changed_by: %i[reasoning_history model], snapshot_fallback: :key,
+                            chip: ->(model, own) { model.reasoning_history_explained(own: own)&.summary },
+                            live: ->(engine) { engine.reasoning_history_explained&.summary })
+    TOOLKIT = new(key: :toolkit, changed_by: %i[toolkit], snapshot_fallback: :key, chip: nil, live: lambda(&:toolkit_summary))
+
+    # In the order the session state, a :command_ran and the web name them.
+    ALL = [LLM_CONTEXT, THINKING, REASONING_HISTORY, TOOLKIT].freeze
+    # /stats's (no toolkit: its JSON never had one).
+    STATS = [LLM_CONTEXT, THINKING, REASONING_HISTORY].freeze
+  end
+end

data/lib/samagotchi/system_prompt.rb

@@ -331,7 +331,9 @@ module Samagotchi
     # The tools the session's toolkit leaves out, named once right after the
     # base prompt: sessions on another toolkit already differ at the tools,
     # and nothing later (a memory write) moves it. nil when none are (full):
-    # the prompt is what it was before toolkits.
+    # the prompt is what it was before toolkits. The ones call_tool reaches
+    # and the ones the toolkit removes (only the user brings those back)
+    # get a sentence each; with call_tool not declared, one list.
     def not_loaded_line(layers)
       registry = @tools_lookup.call
       return nil unless registry.respond_to?(:left_out_names)
@@ -339,8 +341,22 @@ module Samagotchi
       names = registry.left_out_names(layers: layers)
       return nil if names.empty?
 
-      "Not loaded in this session (toolkit #{registry.toolkit&.name}): #{names.join(", ")}. " \
-        "Only the user can load one (/toolkit add <name>)."
+      toolkit = "(toolkit #{registry.toolkit&.name})"
+      reachable = registry.reachable_names(layers: layers)
+      if reachable.empty?
+        return "Not loaded in this session #{toolkit}: #{names.join(", ")}. Only the user can load one (/toolkit add <name>)."
+      end
+
+      removed = names - reachable
+      # find_tools removed (call_tool still works): the route without it.
+      how = if removed.include?("find_tools") then "Call one with call_tool(tool: \"chi/<name>\", args: {…})."
+            else "Search them with find_tools; call one with call_tool."
+            end
+      line = "Not declared in this session #{toolkit}: #{reachable.join(", ")}. #{how}"
+      return line if removed.empty?
+
+      "#{line} Removed #{toolkit}: #{removed.join(", ")}. Only the user can load #{removed.size == 1 ? "it" : "one"} " \
+        "(/toolkit add <name>)."
     end
 
     def with_tail_declarations(prompt, chat:, layers:)

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -34,7 +34,8 @@ module Samagotchi
       # What a tool line says the call did: the model's description of a
       # command (": List the specs") in place of its cut params, else the
       # params, dim; then, dim, the name the model called it by when that was
-      # an alias's (" (called as bash)").
+      # an alias's (" (called as bash)"), or the tool it was reached through
+      # (" (via call_tool)").
       def tool_params_suffix(activity)
         description = activity[:description].to_s.strip
         params = activity[:params].to_s.strip
@@ -43,7 +44,9 @@ module Samagotchi
                  else ""
                  end
         called_as = activity[:called_as].to_s
-        called_as.empty? ? suffix : "#{suffix}#{paint(" (called as #{called_as})", 90)}"
+        suffix = "#{suffix}#{paint(" (called as #{called_as})", 90)}" unless called_as.empty?
+        via = activity[:via].to_s
+        via.empty? ? suffix : "#{suffix}#{paint(" (via #{via})", 90)}"
       end
 
       # Green ok, yellow stopped (a wait the user's Stop ended), red the rest.

data/lib/samagotchi/thinking_command.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "cache_confirm"
+require_relative "level_setting_command"
 require_relative "thinking"
 
 module Samagotchi
-  # /thinking, the session's own thinking level (Session#thinking): with no
-  # argument, the level the next turn runs at and where it came from;
-  # `/thinking off|low|medium|high` sets the session's own, `/thinking
-  # default` unsets it (the session follows the process default, the
-  # model, its host, then thinking.level). A change takes effect at the
-  # next turn's start (the REPL and the worker run it between turns), and
-  # the reply says what it costs the prompt cache (Thinking.cache_cost).
-  # A costly change asks first (CacheConfirm); --yes (or -y) applies it.
-  class ThinkingCommand
+  # /thinking, the session's own thinking level (Session#thinking):
+  # `/thinking off|low|medium|high` sets it, `/thinking default` unsets it
+  # (the session follows the process default, the model, its host, then
+  # thinking.level). What a change costs the prompt cache:
+  # Thinking.cache_cost. See LevelSettingCommand.
+  class ThinkingCommand < LevelSettingCommand
     NAME = "/thinking"
     SETTABLE = (Thinking::LEVELS - [Thinking::DEFAULT]).freeze
     USAGE = "usage: #{NAME} [#{Thinking::LEVELS.join("|")}]".freeze
@@ -24,71 +21,22 @@ module Samagotchi
       tail: "Only the prompt's tail changes: the cache keeps the rest."
     }.freeze
 
-    # @param engine [Engine] #thinking_explained(own:), #thinking_override(=),
-    #   #session, #thinking_cache_cost, #history?
-    # @param save [#call] saves the session after a change
-    def initialize(engine:, save:)
-      @engine = engine
-      @save = save
-    end
-
-    # @param args [String] what follows /thinking (--yes anywhere)
-    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
-    #   false applies it at once (chi send, a delegate, a start flag)
-    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
-    #   whether the level changed, and the confirm it asks for (nothing
-    #   changed then)
-    # @raise [ArgumentError] a word that isn't a level (with USAGE)
-    def run(args, confirm: true)
-      word, yes = CacheConfirm.split(args)
-      return [listing(@engine.thinking_explained), false, nil] if word.empty?
-
-      level = word.to_sym
-      raise ArgumentError, "unknown thinking level #{word}\n#{USAGE}" unless Thinking::LEVELS.include?(level)
-
-      session = @engine.session or raise ArgumentError, "no session yet"
-      own = SETTABLE.include?(level) ? level : nil
-      before = @engine.thinking_explained
-      ask = confirm && !yes ? ask(before, own, word) : nil
-      return ask if ask
-
-      @engine.thinking_override = own
-      @save.call(session)
-      after = @engine.thinking_explained
-      [[listing(after), *notes(before, after)].join("\n"), true, nil]
-    end
-
-    # The level, where it came from, and what the session sets itself.
-    def listing(explained)
-      return "thinking: can't be resolved for this model" unless explained
-
-      lines = ["thinking: #{explained.label}"]
-      unless explained.own
-        lines << "  this session's own: none (follows chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, " \
-                 "its host, then thinking.level)"
-      end
-      lines.join("\n")
-    end
-
-    private
-
-    # The reply that asks before a costly change, nil when it needn't.
-    def ask(before, own, word)
-      would = @engine.thinking_explained(own: own)
-      return nil unless before && would
-
-      cost = @engine.thinking_cache_cost
-      return nil unless CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: would.level != before.level)
-
-      step = CacheConfirm.confirm(NAME, word)
-      [[listing(before), "Switching to #{would.level} restarts the prompt cache: #{COST_NOTES[cost]}", step.text].join("\n"), false, step]
-    end
-
-    def notes(before, after)
-      return [] unless before && after
-      return ["(no change to what the next turn runs under)"] if before.level == after.level
-
-      ["From the next turn's start (a running turn keeps its own).", COST_NOTES[@engine.thinking_cache_cost]].compact
-    end
+    SPEC = Spec.new(
+      name: NAME, label: "thinking", usage: USAGE, cost_notes: COST_NOTES,
+      parse: lambda { |word|
+        level = word.to_sym
+        if Thinking::LEVELS.include?(level)
+          [true, SETTABLE.include?(level) ? level : nil]
+        else
+          [false, nil]
+        end
+      },
+      own: lambda(&:thinking_override),
+      explained: ->(engine, own) { engine.thinking_explained(own: own) },
+      set: ->(engine, own) { engine.thinking_override = own },
+      cache_cost: ->(engine, _from, _to) { engine.thinking_cache_cost },
+      follows: "chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, its host, then thinking.level",
+      extra_line: nil
+    )
   end
 end

data/lib/samagotchi/thinking_notices.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative "effective_model"
+require_relative "log"
+require_relative "thinking"
+
+module Samagotchi
+  # What the thinking level a turn runs at leads to, said to the user: a
+  # level its host can't do (an effort on a native host, or on a llama.cpp
+  # chat template that takes none), off that the model didn't honour, and a
+  # host refusing the thinking fields or the reasoning sent back. Each
+  # notice once per session and host; the log lines each time.
+  #
+  # Turn thread only (the turn's settings and its stream handler): no lock.
+  # What it needs from the Engine comes through lookups, called at use.
+  class ThinkingNotices
+    # @param session [#call] → Session, nil (its id: once per session)
+    # @param profile [#call] → ModelProfile (a native host's)
+    # @param notify  [#call] (text, level, source) → a notice
+    def initialize(session:, profile:, notify:)
+      @session = session
+      @profile = profile
+      @notify = notify
+      @said = Set.new
+      @turn = nil
+      @generation_thought = nil
+    end
+
+    # [level, HostRegistry::ModelTarget] the turn runs at, nil before one.
+    attr_reader :turn
+
+    # The turn's thinking level on +target+ (its EffectiveModel's), what
+    # the notices after it read; an effort a native host can't do is said
+    # now.
+    def turn_started(level, target)
+      @turn = [level, target]
+      announce_level(level, target)
+    end
+
+    # A generation starts (or a dropped one streams again from the start).
+    def generation_started = @generation_thought = nil
+
+    # Whether this generation's thinking lane said anything: nil while it
+    # streamed none, false while only whitespace (Gemma 4's empty thought
+    # with thinking off), true once a real thought came.
+    def note_thought(thinking)
+      return if thinking.empty?
+
+      @generation_thought ||= thinking.match?(/\S/)
+    end
+
+    # A generation completed: off that the model didn't honour, an effort
+    # its chat template ignores.
+    def generation_completed(event)
+      check_honoured(event)
+      announce_effort_ignored
+    end
+
+    # The host refused the level's request fields (gpt-oss can't turn
+    # thinking off) and the chat loop sent the request without them: said
+    # once per session and host, standing in for the not-honoured notice.
+    def thinking_refused(event)
+      _level, target = @turn
+      return unless target
+
+      Log.warn(:model, "thinking_refused", level: event[:level], host: target.entry.name, model: event[:model],
+                                           detail: event[:detail])
+      @said << [session_id, target.entry.name, :not_honoured]
+      notice_once(:refused, target, :warn,
+                  "#{target.entry.name} refused thinking: #{event[:level]} for #{event[:model]} (#{event[:detail]}); " \
+                  "sent without it, so thinking stays as the model has it")
+    rescue StandardError => e
+      failed(:thinking_refused, e)
+    end
+
+    # The host refused a sampling field (the empty-answer retry's
+    # temperature on a model that takes none) and the chat loop asked again
+    # without them, as it will for the model from now on: a log line.
+    def sampling_refused(event)
+      Log.info(:model, "sampling_refused", model: event[:model], detail: event[:detail])
+    rescue StandardError => e
+      failed(:sampling_refused, e)
+    end
+
+    # The host refused the model's reasoning sent back (reasoning_history)
+    # and the chat loop asked the step again without it, as it will from
+    # now on: logged, and said once per session and host.
+    def reasoning_history_refused(event)
+      _level, target = @turn
+      return unless target
+
+      Log.warn(:model, "reasoning_history_refused", level: event[:level], host: target.entry.name, model: event[:model],
+                                                    detail: event[:detail])
+      return unless @said.add?([session_id, target.entry.name, :reasoning_history_refused])
+
+      @notify.call("#{target.entry.name} refused reasoning sent back (reasoning_history: #{event[:level]}) for " \
+                   "#{event[:model]} (#{event[:detail]}); sent without it from now on", :warn, "reasoning history")
+    rescue StandardError => e
+      failed(:reasoning_history_refused, e)
+    end
+
+    private
+
+    # An effort on a native host, which has no knob for it: said once per
+    # session and host.
+    def announce_level(level, target)
+      return if target.entry.chat?
+
+      profile = @profile.call
+      return if Thinking.native(level, profile).honoured
+
+      notice_once(:unsupported, target, :info,
+                  "#{level} isn't supported by native #{profile.name} on #{target.entry.name}; " \
+                  "thinking stays as the model has it")
+    rescue StandardError => e
+      failed(:announce_level, e)
+    end
+
+    # An effort on a llama.cpp chat host whose chat template takes none
+    # (its /props says so): said once per session and host, as for a native
+    # host. Read from the /props answer the turn's window probe left in the
+    # cache, so it asks the server nothing.
+    def announce_effort_ignored
+      level, target = @turn
+      return unless target&.entry&.chat? && Thinking::EFFORTS.include?(level)
+
+      props = target.client.cached_server_props(model: target.bare_model)
+      return unless Thinking.effort_ignored?(level, props)
+
+      notice_once(:unsupported, target, :info,
+                  "#{level} isn't supported by #{target.bare_model}'s chat template on #{target.entry.name} " \
+                  "(/props: supports_reasoning_effort false); thinking stays as the model has it")
+    rescue StandardError => e
+      failed(:effort_ignored, e)
+    end
+
+    # Thinking off, and the model thought anyway: logged each time, said
+    # once per session and host. A thinking lane of whitespace alone is no
+    # thought.
+    def check_honoured(event)
+      level, target = @turn
+      chars = event[:thinking_chars].to_i
+      return unless level == :off && chars.positive? && target
+      return if @generation_thought == false
+
+      Log.warn(:model, "thinking_not_honoured", level: level, host: target.entry.name, model: target.bare_model, chars: chars)
+      notice_once(:not_honoured, target, :warn,
+                  "off wasn't honoured by #{target.bare_model} on #{target.entry.name} " \
+                  "(#{chars} chars of thinking); a sampling: override on the host or model may turn it off " \
+                  "(see Thinking in docs/configuration.md)")
+    rescue StandardError => e
+      failed(:check_honoured, e)
+    end
+
+    def notice_once(kind, target, level, text)
+      return unless @said.add?([session_id, target.entry.name, kind])
+
+      @notify.call(text, level, "thinking")
+    end
+
+    def session_id = @session.call&.id
+
+    # A notice that failed: none is said, the turn goes on; a log line
+    # (once per process for the notice, model and error class).
+    def failed(notice, error)
+      EffectiveModel::Unresolved.fallback(:thinking_notice_failed, @turn&.last&.model || notice.to_s, error, nil)
+    end
+  end
+end

data/lib/samagotchi/tool_activity.rb

@@ -56,6 +56,9 @@ module Samagotchi
       # The name the model used when an alias ran a built-in (called_as: "bash"
       # for an execute), for a UI that shows it.
       event[:called_as] = call[:called_as] if call.is_a?(Hash) && call[:called_as]
+      # The tool it was reached through (via: "call_tool", a built-in the
+      # toolkit doesn't declare): not an alias, the model named it.
+      event[:via] = call[:via] if call.is_a?(Hash) && call[:via]
       # The model's own words for a command, which the TUI's tool line
       # shows in place of the cut params.
       description = command_description(tool_name, call)

data/lib/samagotchi/tool_row_fields.rb

@@ -23,7 +23,7 @@ module Samagotchi
   # params and label stay where they are: their sources differ per path
   # (the registry's preview, a plugin's label, the saved shown params).
   module ToolRowFields
-    ACTIVITY_KEYS = %i[title called_as].freeze
+    ACTIVITY_KEYS = %i[title called_as via].freeze
     EVENT_KEYS = %i[view ref refs].freeze
     KEYS = (ACTIVITY_KEYS + EVENT_KEYS).freeze
 
@@ -33,13 +33,15 @@ module Samagotchi
     #   relative to it when inside it)
     # @return [Hash] title (a few words: a project-relative path, a command
     #   without its "cd … &&"), called_as (the name the model called it by
-    #   when that was an alias's: bash), view (ToolView: the full command)
+    #   when that was an alias's: bash), via (the tool it was reached
+    #   through: call_tool), view (ToolView: the full command)
     #   and ref (FileRef: the file a file tool touched), each only when
     #   there is one
     def for(tool_name, call, cwd:)
       {
         title: ToolActivity.tool_title(tool_name, call, cwd: cwd),
         called_as: call[:called_as],
+        via: call[:via],
         view: ToolView.for(tool_name, call)&.to_h,
         ref: FileRef.for(tool_name, call, cwd: cwd)&.to_h
       }.compact

data/lib/samagotchi/tool_runner.rb

@@ -47,6 +47,10 @@ module Samagotchi
     #   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:)
+      # 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)
       # 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
@@ -60,7 +64,7 @@ module Samagotchi
       started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
                   tool: call[:name], call: call.dup, params: params }
       started[:label] = label if label
-      # Its row fields (ToolRowFields: title, called_as, view, ref, and a
+      # Its row fields (ToolRowFields: title, called_as, via, view, ref, and a
       # plugin tool's refs); the worker runs in its session's working
       # directory.
       fields = ToolRowFields.for(call[:name], call, cwd: Dir.pwd)
@@ -268,12 +272,29 @@ module Samagotchi
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 
-    # A real tool the session's toolkit leaves out of this turn.
+    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).
+    def unwrapped(call)
+      registry = tools
+      return call unless registry.respond_to?(:offered) && !call[:name].nil?
+
+      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
+
+    # 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).
     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]
 
-      layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
       !registry.left_out(call[:name], layers: layers).nil?
     end
 

data/lib/samagotchi/toolkit.rb

@@ -25,17 +25,19 @@ module Samagotchi
     # The plain form the snapshot and the web carry.
     def to_h = { name: name, add: add, remove: remove }
 
-    # This toolkit with +tool+ declared (/toolkit add): a tool it removed
-    # comes out of +remove+ (back to its kit's), any other goes into +add+.
+    # This toolkit with +tool+ declared (/toolkit add): out of +remove+
+    # and into +add+, whatever its kit says (an add after a remove
+    # declares it).
     def adding(tool)
       tool = tool.to_s
-      remove.include?(tool) ? with(remove: remove - [tool]) : with(add: (add + [tool]).uniq)
+      with(remove: remove - [tool], add: (add + [tool]).uniq)
     end
 
-    # This toolkit with +tool+ left out (/toolkit remove), the other way.
+    # This toolkit with +tool+ removed (/toolkit remove), the other way: a
+    # remove is hard (call_tool can't reach it either), also after an add.
     def removing(tool)
       tool = tool.to_s
-      add.include?(tool) ? with(add: add - [tool]) : with(remove: (remove + [tool]).uniq)
+      with(add: add - [tool], remove: (remove + [tool]).uniq)
     end
 
     # How the UIs name it: "lean", "lean +web_fetch -memory_write".
@@ -66,21 +68,31 @@ module Samagotchi
 
     # A toolkit as a session's next turn would declare it (Engine
     # #toolkit_explained): +toolkit+ as saved, +resolved+, the Registry
-    # +declared+ entries and the names it leaves out (+left_out+), and
-    # whether that isn't what the Registry declares now (+pending+: it
+    # +declared+ entries and the names it leaves out (+left_out+): the ones
+    # call_tool reaches (+reachable+) and the ones it removes (+removed+);
+    # and whether that isn't what the Registry declares now (+pending+: it
     # applies at the next turn's start).
-    Explained = Data.define(:toolkit, :resolved, :declared, :left_out, :pending) do
-      # What the prompt carries of it: the declared names and, when it
-      # leaves tools out, the kit name the not-loaded line gives. Two equal
+    Explained = Data.define(:toolkit, :resolved, :declared, :left_out, :reachable, :removed, :pending) do
+      def initialize(toolkit:, resolved:, declared:, left_out:, pending:, reachable: [], removed: [])
+        super
+      end
+
+      # What the prompt carries of it: the declared names, the reachable
+      # and removed ones (the not-loaded line, find_tools' chi line) and,
+      # when either list has any, the kit name the line gives. Two equal
       # keys build the same prompt (/toolkit's "no change", its cost).
-      def prompt_key = [declared.map(&:name), left_out.empty? ? nil : resolved.name]
+      def prompt_key
+        [declared.map(&:name), reachable, removed, reachable.empty? && removed.empty? ? nil : resolved.name]
+      end
 
       # What the UIs show (the snapshot, command_ran): nil when it declares
       # every tool on full (full, full +delegate), which has no chip.
+      # +left_out+ is +reachable+ and +removed+ together.
       def summary
         return nil if toolkit.name == Toolkit::FULL && left_out.empty? && resolved.fallback.nil?
 
-        { name: toolkit.name, label: toolkit.label, left_out: left_out, fallback: resolved.fallback }
+        { name: toolkit.name, label: toolkit.label, left_out: left_out, reachable: reachable, removed: removed,
+          fallback: resolved.fallback }
       end
     end
 
@@ -111,8 +123,9 @@ module Samagotchi
       Kit.new(name: FULL, tools: :all),
       Kit.new(name: LEAN, tools: LEAN_TOOLS),
       # A delegate child: it reports to its parent (send_note; the
-      # delegated-by line names it) and leaves memory writes to it.
-      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write])
+      # delegated-by line names it) and leaves memory writes to it, and
+      # starts no children of its own (removed: not even through call_tool).
+      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write delegate delegate_result])
     ].to_h { |kit| [kit.name, kit] }.freeze
 
     # What a toolkit declares, the Registry's filter: every built-in

data/lib/samagotchi/toolkit_binding.rb

@@ -17,14 +17,17 @@ module Samagotchi
     # @param can_stage    [#call] → whether a plugin may change the toolkit now
     #   (no turn runs, no model reply yet)
     # @param reset_prompt [#call] → build the system prompts again
+    # @param refresh_index [#call] → the tool index's search tool described
+    #   for the Registry's toolkit (Tools::ToolIndex#refresh!)
     # @param emit         [#call] (sink, event) → emits to a turn's sink + observers
     # @param notify       [#call] (text, level, source, extra:) → a notice
-    def initialize(tools:, session:, state_dir:, can_stage:, reset_prompt:, emit:, notify:)
+    def initialize(tools:, session:, state_dir:, can_stage:, reset_prompt:, emit:, notify:, refresh_index: -> {})
       @tools = tools
       @session = session
       @state_dir = state_dir
       @can_stage = can_stage
       @reset_prompt = reset_prompt
+      @refresh_index = refresh_index
       @emit = emit
       @notify = notify
       # The toolkits plugins declare (chi.toolkit), beside the built-in and
@@ -63,7 +66,9 @@ module Samagotchi
       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), pending: filter != tools.toolkit)
+                             left_out: tools.left_out_names(toolkit: filter),
+                             reachable: tools.reachable_names(toolkit: filter),
+                             removed: tools.removed_names(toolkit: filter), pending: filter != tools.toolkit)
     end
 
     # The session's toolkit for the UIs (the snapshot, command_ran): nil on
@@ -114,6 +119,7 @@ module Samagotchi
       return false if resolved == tools.toolkit
 
       tools.toolkit = resolved
+      @refresh_index.call
       @reset_prompt.call
       true
     end