samagotchi 0.119.0 → 0.121.0

data/lib/samagotchi/toolkit.rb

@@ -84,7 +84,8 @@ module Samagotchi
       # names, reachable and removed ones (the not-loaded line, find_tools'
       # chi line), and, when either list has any, the kit name the line gives.
       def tools_key
-        [declared.map(&:name), reachable, removed, reachable.empty? && removed.empty? ? nil : resolved.name]
+        [declared.map(&:name), reachable, removed, resolved.groups,
+         reachable.empty? && removed.empty? ? nil : resolved.name]
       end
 
       # What the prompt carries of it, including the kit's prompt text. Two
@@ -92,14 +93,16 @@ module Samagotchi
       def prompt_key = [*tools_key, resolved.prompt]
 
       # What the UIs show (the snapshot, command_ran): nil when it declares
-      # every tool on full (full, full +delegate), which has no chip.
+      #   every tool on full (full, full +delegate), which has no chip unless
+      #   its groups are filtered.
       # +left_out+ is +reachable+ and +removed+ together; +prompt+ (the
       # kit's text) only when the kit has one.
       def summary
-        return nil if toolkit.name == Toolkit::FULL && left_out.empty? && resolved.fallback.nil?
+        return nil if toolkit.name == Toolkit::FULL && left_out.empty? && resolved.fallback.nil? &&
+                      resolved.groups == :all
 
         summary = { name: toolkit.name, label: toolkit.label, left_out: left_out, reachable: reachable,
-                    removed: removed, fallback: resolved.fallback }
+                    removed: removed, fallback: resolved.fallback, groups: resolved.groups }
         resolved.prompt ? summary.merge(prompt: resolved.prompt) : summary
       end
     end
@@ -107,17 +110,31 @@ module Samagotchi
     # Tool names as a list of unique, stripped strings.
     def self.tool_names(names) = Array(names).map { |tool| tool.to_s.strip }.reject(&:empty?).uniq
 
+    # Group names/globs as a stable list, or :all. Selectors match against
+    # the source's declaration-time group snapshot.
+    def self.group_names(groups)
+      return :all if groups == :all
+
+      Array(groups).map { |group| group.to_s.strip }.reject(&:empty?).uniq.sort.freeze
+    end
+
+    def self.group_matches?(selectors, name)
+      selectors == :all || selectors.any? { |selector| File.fnmatch?(selector, name.to_s) }
+    end
+
     # A named list of declared tools: +tools+ (:all, every built-in; or the
     # built-in names) when it has no +base+, else its +base+'s with +add+
     # and +remove+. +source+: "core", "config", or the bundle that declared
     # it (chi.toolkit). +prompt+: text the sessions on it get in their
     # system prompt, verbatim (stripped); nil inherits the base's, "" clears
-    # it.
-    Kit = Data.define(:name, :base, :tools, :add, :remove, :source, :prompt) do
-      def initialize(name:, base: nil, tools: nil, add: [], remove: [], source: "core", prompt: nil)
+    #   it. +groups+: :all or a sorted list of source group names/globs; nil
+    #   inherits the base's.
+    Kit = Data.define(:name, :base, :tools, :add, :remove, :source, :prompt, :groups) do
+      def initialize(name:, base: nil, tools: nil, add: [], remove: [], source: "core", prompt: nil, groups: nil)
         super(name: name.to_s, base: base&.to_s, tools: tools == :all ? :all : Toolkit.tool_names(tools),
               add: Toolkit.tool_names(add), remove: Toolkit.tool_names(remove), source: source.to_s,
-              prompt: prompt.is_a?(String) ? prompt.strip.freeze : nil)
+              prompt: prompt.is_a?(String) ? prompt.strip.freeze : nil,
+              groups: groups.nil? ? nil : Toolkit.group_names(groups))
       end
     end
 
@@ -150,13 +167,13 @@ module Samagotchi
     REVIEW_TOOLS = %w[read memory_read].freeze
 
     BUILTIN_KITS = [
-      Kit.new(name: FULL, tools: :all),
-      Kit.new(name: LEAN, tools: LEAN_TOOLS),
+      Kit.new(name: FULL, tools: :all, groups: :all),
+      Kit.new(name: LEAN, tools: LEAN_TOOLS, groups: :all),
       # A delegate child: it reports to its parent (send_note; the
       # 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]),
-      Kit.new(name: REVIEW, tools: REVIEW_TOOLS)
+      Kit.new(name: REVIEW, tools: REVIEW_TOOLS, groups: [])
     ].to_h { |kit| [kit.name, kit] }.freeze
 
     # What a toolkit declares, the Registry's filter: every built-in
@@ -165,16 +182,19 @@ module Samagotchi
     # +added+ declares any registered tool. +fallback+: why the session's
     # own toolkit couldn't be resolved (this is FULL then), nil when it was.
     # +prompt+: the kit's prompt text (its own or its base's), nil without.
-    Resolved = Data.define(:name, :all_core, :core, :added, :removed, :fallback, :prompt) do
-      def initialize(name:, all_core: false, core: [], added: [], removed: [], fallback: nil, prompt: nil)
+    # +groups+: :all or the sorted source group names/globs it reaches.
+    Resolved = Data.define(:name, :all_core, :core, :added, :removed, :fallback, :prompt, :groups) do
+      def initialize(name:, all_core: false, core: [], added: [], removed: [], fallback: nil, prompt: nil, groups: :all)
         super(name: name.to_s, all_core: all_core, core: core.dup.freeze, added: added.dup.freeze,
-              removed: removed.dup.freeze, fallback: fallback, prompt: prompt)
+              removed: removed.dup.freeze, fallback: fallback, prompt: prompt, groups: Toolkit.group_names(groups))
       end
 
-      # Every built-in, nothing removed and no prompt text: what no toolkit
-      # declares (the Registry's nil). A kit on full's tools with a prompt
-      # is kept, so its text reaches the system prompt.
-      def everything? = all_core && removed.empty? && prompt.nil?
+      # Whether a declared source group is reached by this toolkit.
+      def reaches_group?(name) = Toolkit.group_matches?(groups, name)
+
+      # Every built-in, nothing removed, no prompt text and no group filter:
+      # what no toolkit declares (the Registry's nil).
+      def everything? = all_core && removed.empty? && prompt.nil? && groups == :all
 
       # @param entry [Tools::Registry::Entry]
       def declares?(entry)
@@ -215,7 +235,7 @@ module Samagotchi
       new(name: name.empty? ? FULL : name)
     end
 
-    # config.yml's toolkit.kits (a map of name => {base:, add:, remove:}),
+    # config.yml's toolkit.kits (a map of name => {base:, add:, remove:, groups:}),
     # nil when it has none.
     def self.config_kits
       section = ConfigFile.section("toolkit")
@@ -260,10 +280,13 @@ module Samagotchi
       base = if kit.base
                resolve_kit(kit.base, kits, seen + [name])
              else
-               Resolved.new(name: name, all_core: kit.tools == :all, core: kit.tools == :all ? [] : kit.tools)
+               Resolved.new(name: name, all_core: kit.tools == :all, core: kit.tools == :all ? [] : kit.tools,
+                            groups: kit.groups || :all)
              end
       prompt = kit.prompt.nil? ? base.prompt : kit.prompt
-      base.changed(add: kit.add, remove: kit.remove).with(name: name, prompt: prompt.to_s.empty? ? nil : prompt)
+      groups = kit.groups.nil? ? base.groups : kit.groups
+      base.changed(add: kit.add, remove: kit.remove)
+          .with(name: name, prompt: prompt.to_s.empty? ? nil : prompt, groups: groups)
     end
 
     # config.yml's toolkit.kits.review, refused: the review kit is the
@@ -272,13 +295,13 @@ module Samagotchi
                       "name your kit something else"
 
     # The keys a config kit entry takes.
-    KIT_KEYS = %w[base add remove prompt].freeze
+    KIT_KEYS = %w[base add remove prompt groups].freeze
 
     # The kits known: the built-ins, then config's toolkit.kits, then the
     # plugins' (chi.toolkit). A config kit with a built-in's name is left
     # out (one it can't redefine; review, the participants' boundary, is
     # reserved) with a line in +errors+, and so is one
-    # that isn't a {base:, add:, remove:, prompt:} map. One with another key
+    #   that isn't a {base:, add:, remove:, prompt:, groups:} map. One with another key
     # (a typo, a tools: list) still loads, with a line naming the key, and
     # so does one whose prompt isn't text or is over PROMPT_MAX characters:
     # without the prompt, with a line saying why.
@@ -295,18 +318,19 @@ module Samagotchi
         elsif kits.key?(name)
           errors << "toolkit.kits.#{name}: #{name} is a built-in toolkit"
         elsif !spec.is_a?(Hash)
-          errors << "toolkit.kits.#{name}: expected {base:, add:, remove:, prompt:}"
+          errors << "toolkit.kits.#{name}: expected {base:, add:, remove:, prompt:, groups:}"
         else
           spec = spec.transform_keys(&:to_s)
           (spec.keys - KIT_KEYS).each do |key|
-            errors << "toolkit.kits.#{name}: unknown key #{key} (a kit takes base:, add:, remove:, prompt:)"
+            errors << "toolkit.kits.#{name}: unknown key #{key} " \
+                      "(a kit takes base:, add:, remove:, prompt:, groups:)"
           end
           if (problem = prompt_error(spec["prompt"]))
             errors << "toolkit.kits.#{name}: #{problem}; the kit loads without it"
             spec.delete("prompt")
           end
           kits[name] = Kit.new(name: name, base: spec["base"] || FULL, add: spec["add"], remove: spec["remove"],
-                               prompt: spec["prompt"], source: "config")
+                               prompt: spec["prompt"], groups: spec["groups"], source: "config")
         end
       end
       plugins.each { |kit| kits[kit.name] ||= kit }

data/lib/samagotchi/toolkit_binding.rb

@@ -116,8 +116,10 @@ module Samagotchi
       errors = []
       resolved = Toolkit.of(session&.toolkit).resolve(kits(errors))
       warn_unresolved(session, resolved, errors, on_event)
+      warn_unknown_groups(resolved, on_event)
       resolved = nil if resolved.everything?
       tools = @tools.call
+      tools.reaching_kit = ->(group) { reaching_kit(group) }
       return false if resolved == tools.toolkit
 
       tools.toolkit = resolved
@@ -126,6 +128,19 @@ module Samagotchi
       true
     end
 
+    # The first kit that resolves and reaches source group +group+, the
+    # user's own (config's, the plugins') before the built-ins, so a hint
+    # names "/toolkit web" rather than "full"; nil when none does.
+    def reaching_kit(group)
+      kits = self.kits
+      builtin = Toolkit::BUILTIN_KITS.keys
+      kits.keys.sort_by.with_index { |name, i| [builtin.include?(name) ? 1 : 0, i] }.find do |name|
+        Toolkit.resolve_kit(name, kits).reaches_group?(group)
+      rescue Toolkit::Unresolved
+        false
+      end
+    end
+
     private
 
     # The toolkit's load warnings, each once per process: a name that
@@ -142,5 +157,22 @@ module Samagotchi
         @emit.call(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
       end
     end
+
+    def warn_unknown_groups(resolved, on_event)
+      return if resolved.groups == :all
+
+      names = @tools.call.index&.groups || []
+      unknown = resolved.groups.reject do |selector|
+        names.any? { |name| Toolkit.group_matches?([selector], name) }
+      end
+      unknown.each do |selector|
+        line = "#{resolved.name}: group selector #{selector.inspect} matches no group declared at load"
+        next if @warned.include?(line)
+
+        @warned << line
+        Log.warn(:config, "toolkit_group_unknown", message: line)
+        @emit.call(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
+      end
+    end
   end
 end

data/lib/samagotchi/toolkit_command.rb

@@ -71,6 +71,15 @@ module Samagotchi
       lines << "  declared (#{declared.size}, ~#{format_tokens(declared.sum { |entry| tokens(entry) })} tokens): " \
                "#{declared.map { |entry| "#{entry.name} ~#{format_tokens(tokens(entry))}" }.join(", ")}"
       lines << prompt_line(explained.resolved.prompt) if explained.resolved.prompt
+      groups = explained.resolved.groups
+      group_names = if groups == :all
+                      "all"
+                    elsif groups.empty?
+                      "none"
+                    else
+                      groups.join(", ")
+                    end
+      lines << "  groups: #{group_names}"
       left_out = explained.left_out
       if explained.reachable.empty?
         lines << "  not loaded: #{left_out.empty? ? "none" : left_out.join(", ")}"
@@ -123,10 +132,24 @@ module Samagotchi
       # The kit's prompt text (Toolkit::Kit#prompt) is in the prompt too.
       text = after.resolved.prompt
       parts << (text ? "sends its kit's prompt text" : "drops the kit's prompt text") if text != before.resolved.prompt
+      parts.concat(group_changes(before.resolved.groups, after.resolved.groups))
       parts << "declares the same tools under its own name" if parts.empty?
       "Switching to #{after.toolkit.label} #{parts.join("; ")}."
     end
 
+    def group_changes(before, after)
+      return [] if before == after
+      return ["reaches all groups"] if after == :all
+      return ["limits groups to #{after.empty? ? "none" : after.join(", ")}"] if before == :all
+
+      added = after - before
+      removed = before - after
+      changes = []
+      changes << "reaches groups #{added.join(", ")}" unless added.empty?
+      changes << "leaves out groups #{removed.join(", ")}" unless removed.empty?
+      changes
+    end
+
     # What the confirm says is read again: from the tools on (the front of
     # every request), or from the kit's prompt text on when only that
     # changes (Explained#tools_key is unchanged: only a kit's prompt text).

data/lib/samagotchi/tools/deferred_tools.rb

@@ -39,7 +39,7 @@ module Samagotchi
           next if taken.include?(name) || registry.offered(name, layers: layers)
 
           taken << name
-          deferred << Deferred.new(name: name, description: STUB_DESCRIPTION, schema: STUB_SCHEMA)
+          deferred << Deferred.new(name: name, description: stub_description(registry, name), schema: STUB_SCHEMA)
         end
         deferred
       end
@@ -74,7 +74,15 @@ module Samagotchi
         end
       end
 
-      private_class_method :builtins, :sourced
+      def stub_description(registry, name)
+        index = registry.respond_to?(:index) ? registry.index : nil
+        tool = index&.unreached_tool(name)
+        return STUB_DESCRIPTION unless tool
+
+        ToolIndex::ToolkitGroupRefusal.for(tool, registry).stub_description
+      end
+
+      private_class_method :builtins, :sourced, :stub_description
     end
   end
 end

data/lib/samagotchi/tools/delegate_relay.rb

@@ -139,6 +139,10 @@ module Samagotchi
       def delivered(response, answer, fields, dismissed)
         return "not delivered (the child's worker is gone)" unless response
 
+        # The child's Bridge asked for a secret this worker didn't send (one
+        # from before the child's chi): not the child's guardrails refusing.
+        return "not delivered (#{BridgeSecret::REFUSED})" if response.secret_refused?
+
         hook = fields[:kind] == HOOK_KIND
         case response.status
         when 200

data/lib/samagotchi/tools/registry.rb

@@ -40,13 +40,18 @@ 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. +deferrable+ (→ the sources'
+      # name, and +groups+ the source groups 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
+      Index = Data.define(:source, :call_name, :groups, :deferrable, :wrap, :unreached) do
+        def initialize(source:, call_name:, groups:, deferrable: nil, wrap: nil, unreached: nil)
+          super(source: source, call_name: call_name, groups: Array(groups).map(&:to_s).uniq.freeze,
+                deferrable: deferrable, wrap: wrap, unreached: unreached)
+        end
+
+        def unreached_tool(name) = unreached&.call(name)
       end
 
       def initialize
@@ -64,6 +69,11 @@ module Samagotchi
       # only there: a request's declared tools never change mid-turn.
       attr_accessor :toolkit
 
+      # Which kit reaches a source group: a lookup (group name → kit name,
+      # nil when none does) the Engine sets with the toolkit; a refusal's
+      # hint names it.
+      attr_accessor :reaching_kit
+
       # @return [Entry]
       def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, refs: nil, source: "core", layer: nil,
                    unwrap: nil)
@@ -181,7 +191,7 @@ module Samagotchi
       # the declared tools stay the same for a session's life. A built-in
       # left out counts only while call_tool can reach it (not removed).
       def index_needed?(toolkit)
-        return true if @index.sourced
+        return true if reached_groups?(toolkit)
         return false if toolkit&.removed&.include?(@index.call_name)
 
         index_reaches?(toolkit)
@@ -191,7 +201,11 @@ module Samagotchi
       # removed or not: a source registered at load, or a built-in the
       # toolkit leaves out without removing it.
       def index_reaches?(toolkit)
-        @index.sourced || @entries.values.any? { |entry| soft?(entry, [], toolkit) }
+        reached_groups?(toolkit) || @entries.values.any? { |entry| soft?(entry, [], toolkit) }
+      end
+
+      def reached_groups?(toolkit)
+        @index.groups.any? { |name| toolkit.nil? || toolkit.reaches_group?(name) }
       end
 
       # Not declared by +toolkit+ under +layers+. An index tool counts only

data/lib/samagotchi/tools/tool_index.rb

@@ -63,6 +63,37 @@ module Samagotchi
         args: { type: "object", description: "the arguments, per the inputSchema #{FIND_NAME} gave" }
       }.freeze
 
+      # The user changes kits; calls and old deferred references cannot
+      # make a source group reachable again.
+      class ToolkitGroupRefusal < StandardError
+        RULE = "toolkit-group"
+
+        # The refusal of +tool+ under +registry+'s toolkit, naming a kit that
+        # reaches its group when the registry can tell (Registry#reaching_kit).
+        def self.for(tool, registry)
+          new(tool, registry.toolkit, kit: registry.respond_to?(:reaching_kit) ? registry.reaching_kit&.call(tool.group) : nil)
+        end
+
+        def initialize(tool, toolkit, kit: nil)
+          @tool = tool
+          @toolkit = toolkit.name
+          @kit = kit
+          super("Error: #{tool.full_name} isn't in this session's toolkit (#{@toolkit}); #{hint}.")
+        end
+
+        def stub_description
+          "Not available in this session's toolkit (#{@toolkit}); #{hint}."
+        end
+
+        private
+
+        def hint
+          return "only the user can switch (/toolkit NAME, or a kit that reaches #{@tool.group})" unless @kit
+
+          "only the user can switch (/toolkit #{@kit}, which reaches #{@tool.group})"
+        end
+      end
+
       # One tool in the index: +group+/+name+ is what the call tool takes,
       # +schema+ its inputSchema, +acts_as+ the name guardrail rules match
       # (mcp_<server>_<tool>; a bare name the call tool looks up too).
@@ -141,7 +172,7 @@ module Samagotchi
       # yet). +prefix+: a bare name with it is taken as an acts_as as given.
       # +label+ is the call tool's row label.
       class Source
-        attr_reader :label, :prefix, :context, :groups, :declared_names, :declared_tokens
+        attr_reader :label, :prefix, :context, :groups, :declared_names, :declared_tokens, :declared_groups
 
         def initialize(label:, call:, acts_as:, wait: nil, prefix: nil, context: nil)
           raise ArgumentError, "tool_source: call must respond to #call" unless call.respond_to?(:call)
@@ -157,6 +188,7 @@ module Samagotchi
           @groups = [].freeze
           @declared_names = []
           @declared_tokens = 0
+          @declared_groups = [].freeze
         end
 
         def inspect = "#<ToolIndex::Source #{@label} groups=#{@groups.map(&:name).join(",")}>"
@@ -184,9 +216,10 @@ module Samagotchi
 
         # What ToolIndex#declare registered: the tools' names and their
         # definitions' estimated tokens (the mcp bundle's /mcp says them).
-        def declared!(names, tokens)
+        def declared!(names, tokens, groups)
           @declared_names = names.dup.freeze
           @declared_tokens = tokens
+          @declared_groups = groups.dup.freeze
         end
       end
 
@@ -196,7 +229,8 @@ module Samagotchi
         @registry = nil
         # The source groups' lines in the search tool's description, as
         # #declare found them (#find_description).
-        @described = [].freeze
+        @described = {}.freeze
+        @declared_group_names = nil
         @dropped = []
         @dropped_mutex = Mutex.new
       end
@@ -216,7 +250,7 @@ module Samagotchi
       # sources'. A source group with a reserved name, or one an earlier
       # group has, is left out of search, lookup and the description (said
       # once per name: a source publishes after load too).
-      def groups
+      def all_groups
         own = registry_groups
         taken = own.map(&:name) | RESERVED_GROUPS
         kept = @sources.flat_map(&:groups).select do |group|
@@ -230,6 +264,17 @@ module Samagotchi
         own + kept
       end
 
+      def reached_groups
+        groups = all_groups
+        toolkit = @registry&.toolkit
+        return groups if toolkit.nil? || toolkit.groups == :all
+
+        declared = @declared_group_names || groups.reject { |group| own?(group) }.map(&:name)
+        groups.select do |group|
+          own?(group) || (declared.include?(group.name) && toolkit.reaches_group?(group.name))
+        end
+      end
+
       # Register the search and call tools in +registry+, once, after the
       # plugins load (or without them: the built-ins a toolkit leaves out
       # are reachable either way); +registry+ declares them per toolkit
@@ -238,7 +283,8 @@ module Samagotchi
       # @return [Array<String>] the names registered
       def declare(registry, failures: nil)
         @registry = registry
-        @described = description_lines(groups.reject { |group| own?(group) }).freeze
+        @described = description_lines(all_groups.reject { |group| own?(group) }).freeze
+        @declared_group_names = @described.keys.freeze
         specs = [find_spec, call_spec]
         declared = specs.filter_map do |spec|
           if (taken = registry[spec.name])
@@ -251,8 +297,9 @@ module Samagotchi
           registry.register(spec.name, source: SOURCE, unwrap: unwrap, **spec.entry_fields(nil))
           spec
         end
-        registry.index = Registry::Index.new(source: SOURCE, call_name: CALL_NAME, sourced: !@sources.empty?,
-                                             deferrable: -> { deferrable }, wrap: ->(call) { wrap(call) })
+        registry.index = Registry::Index.new(source: SOURCE, call_name: CALL_NAME, groups: @declared_group_names,
+                                             deferrable: -> { deferrable }, wrap: ->(call) { wrap(call) },
+                                             unreached: ->(name) { unreached_tool(name) })
         declared!(declared)
         declared.map(&:name)
       end
@@ -293,7 +340,7 @@ module Samagotchi
       def find_description
         "Search tools this session doesn't declare, by keywords. It answers up to #{FIND_RESULTS} tools, each with " \
           "its name (<group>/<tool>) and inputSchema; call one with #{CALL_NAME}. An empty query lists every tool's " \
-          "name.\nGroups:\n#{(description_lines(registry_groups) + @described).join("\n")}"
+          "name.\nGroups:\n#{(description_lines(registry_groups).values + described_groups.values).join("\n")}"
       end
 
       # ── Search ──────────────────────────────────────────────────────────
@@ -372,9 +419,10 @@ module Samagotchi
       # same list in any session and after a respawn.
       # @return [Array<Tool>]
       def deferrable
-        tools = groups.reject { |group| own?(group) }.flat_map(&:tools)
-        counts = tools.map(&:acts_as).tally
-        tools.select do |tool|
+        all = all_groups.reject { |group| own?(group) }.flat_map(&:tools)
+        reached = reached_groups.reject { |group| own?(group) }.flat_map(&:tools)
+        counts = all.map(&:acts_as).tally
+        reached.select do |tool|
           tool.refusal.nil? && counts[tool.acts_as] == 1 && tool.acts_as.match?(DEFERRABLE_NAME) &&
             !@registry&.key?(tool.acts_as)
         end.sort_by(&:acts_as)
@@ -397,6 +445,22 @@ module Samagotchi
         deferrable.any? { |t| t.acts_as == tool.acts_as } ? tool.acts_as : nil
       end
 
+      # Finds a source tool regardless of the active toolkit, without
+      # waiting for a starting group. Used only to refuse a call or explain
+      # a deferred stub for a group the session cannot reach.
+      def unreached_tool(name)
+        name = name.to_s.strip
+        return nil if name.empty?
+
+        groups = all_groups.reject { |group| own?(group) }
+        groups.select! { |group| @declared_group_names.include?(group.name) } if @declared_group_names
+        tool = tool_in(name, groups)
+        return nil unless tool
+        return nil if reached_groups.any? { |group| group.name == tool.group }
+
+        tool
+      end
+
       # What a deferred source tool's wire name may be (Messages' tool
       # name rule).
       DEFERRABLE_NAME = /\A[a-zA-Z0-9_-]{1,128}\z/
@@ -466,7 +530,7 @@ module Samagotchi
       end
 
       def find_in(query, only)
-        all = groups
+        all = reached_groups
         searched = all
         if only && !only.strip.empty?
           searched = all.select { |group| group.name == only.strip }
@@ -502,7 +566,14 @@ module Samagotchi
       def declared!(specs)
         names = specs.map(&:name)
         tokens = specs.sum { |spec| ToolIndex.spec_tokens(spec) }
-        @sources.each { |source| source.declared!(names, tokens) }
+        groups = reached_groups.reject { |group| own?(group) }.map(&:name)
+        @sources.each { |source| source.declared!(names, tokens, groups) }
+      end
+
+      def described_groups
+        return @described unless @registry&.toolkit && @registry.toolkit.groups != :all
+
+        @described.select { |name, _line| @registry.toolkit.reaches_group?(name) }
       end
 
       def own?(group) = RESERVED_GROUPS.include?(group.name)
@@ -536,16 +607,16 @@ module Samagotchi
       # One line per group in the search tool's description: its name, its
       # summary and how many tools it can call.
       def description_lines(groups)
-        groups.map do |group|
+        groups.to_h do |group|
           count = group.callable.size
           line = "- #{group.name}"
           line += ": #{group.summary}" if group.summary
           line += " (#{count} tool#{"s" unless count == 1})" unless group.tools.empty?
-          line
+          [group.name, line]
         end
       end
 
-      # Say once per name that a source's group was left out (#groups).
+      # Say once per name that a source's group was left out (#all_groups).
       def dropped(name, why)
         first = @dropped_mutex.synchronize { @dropped.include?(name) ? false : (@dropped << name) }
         return unless first
@@ -614,7 +685,7 @@ module Samagotchi
       # @return [Tool, String]
       def lookup(name, waited: false)
         name = name.strip
-        all = groups
+        all = reached_groups
         tool = all.lazy.filter_map do |group|
           next unless name.start_with?("#{group.name}/")
 
@@ -632,8 +703,8 @@ module Samagotchi
 
         # A name with a group's <group>/ waits for that group only; any
         # other name (an acts_as) for every one starting.
-        named = all.select { |group| name.start_with?("#{group.name}/") }
-        starting = (named.empty? ? all : named).select { |group| group.state == :starting }
+        named = reached_groups.select { |group| name.start_with?("#{group.name}/") }
+        starting = (named.empty? ? reached_groups : named).select { |group| group.state == :starting }
         unless waited || starting.empty?
           starting.each { |group| source_of(group.name)&.wait(group.name) }
           return lookup(name, waited: true)
@@ -654,6 +725,18 @@ module Samagotchi
         tool.is_a?(Tool) ? tool : nil
       end
 
+      def tool_in(name, groups)
+        named = groups.filter_map do |group|
+          next unless name.start_with?("#{group.name}/")
+
+          group.tools.find { |tool| tool.name == name.delete_prefix("#{group.name}/") }
+        end
+        return named.first if named.one?
+
+        same = groups.flat_map(&:tools).select { |tool| tool.acts_as == name }
+        same.first if same.one?
+      end
+
       # The acts_as and label +name+ stands for, from the name alone:
       # <group>/<tool> of a known group (the one that has the tool, else the
       # first whose name it starts with), its source naming the acts_as; a
@@ -662,7 +745,7 @@ module Samagotchi
       # anything else.
       # @return [Array(String, String), Array(String, nil), nil]
       def claimed(name)
-        all = groups
+        all = all_groups
         if (own = all.select { |g| own?(g) }.find { |g| g.tools.any? { |t| t.acts_as == name } })
           return [name, "#{own.name}: #{name}"]
         end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.119.0"
+  VERSION = "0.121.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end