samagotchi 0.65.0 → 0.66.0

data/lib/samagotchi/engine.rb

@@ -31,6 +31,7 @@ require_relative "llm/backend"
 require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
+require_relative "toolkit"
 require_relative "answer_tail"
 require_relative "archive_store"
 require_relative "session_observer"
@@ -184,6 +185,9 @@ module Samagotchi
       # plugins' tool sets from chi.replace_tools until the turn thread
       # applies them (#apply_staged_tools!). Built before the plugins load.
       @plugin_tasks = build_plugin_tasks
+      # The toolkits plugins declare (chi.toolkit), beside the built-in and
+      # config ones (#toolkit_kits).
+      @plugin_kits = []
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
@@ -1295,6 +1299,7 @@ module Samagotchi
         llm_context: llm_context_summary,
         thinking: thinking_explained&.summary,
         reasoning_history: reasoning_history_explained&.summary,
+        toolkit: toolkit_summary,
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1563,11 +1568,12 @@ module Samagotchi
     # (Web::Capabilities#editor), for a UI or a viewer that can't. A UI that
     # does leaves the line out; the others, the log among them, show it. An
     # unknown value is dropped, so the line shows everywhere.
-    def hook_notify(text, level, hook, fallback_for: nil)
+    # +extra+: more fields for the UIs (a toolkit change's summary).
+    def hook_notify(text, level, hook, fallback_for: nil, extra: {})
       level = (level || :info).to_sym
       level = :info unless %i[info warn].include?(level)
       notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level,
-                 fallback_for: notice_fallback(fallback_for, hook) }.compact
+                 fallback_for: notice_fallback(fallback_for, hook) }.compact.merge(extra)
       return @extension_load.hold(notice) && nil if @extension_load.loading?
 
       in_turn, sink = @turn_state.in_turn_sink
@@ -2019,8 +2025,11 @@ module Samagotchi
       # at its first request).
       start_init_tasks!
       await_init_tasks(turn.controller, turn.on_event)
-      # Plugins' tool sets that changed since the last turn.
+      # Plugins' tool sets that changed since the last turn, then the
+      # session's toolkit (a /toolkit change since the last turn): what the
+      # prompt built next declares, unchanged until the next turn's start.
       apply_staged_tools!
+      apply_toolkit!(session, turn.on_event)
       # A Stop during the wait above: the turn ends here,
       # before the hooks run or a reminder is used up.
       return false if turn.controller.cancelled?
@@ -2666,7 +2675,8 @@ module Samagotchi
         init: lambda { |bundle, label, plugin_label, provides_tools:, quiet:, timeout:, failed: nil, &block|
           add_init_task(bundle: bundle, label: label, plugin_label: plugin_label, provides_tools: provides_tools,
                         quiet: quiet, timeout: timeout, failed: failed, &block)
-        }
+        },
+        toolkits: @plugin_kits
       )
       # What plugins show while they load (an MCP server that didn't
       # start) waits for the first turn, beside the load warnings: no UI
@@ -2689,6 +2699,101 @@ module Samagotchi
     end
     public :apply_staged_tools!
 
+    # The kits a session's toolkit resolves against: the built-ins, config's
+    # toolkit.kits, the plugins' (Toolkit.kits). Config's are read once per
+    # process, like the plugins': an edit to toolkit.kits never changes a
+    # live session's tools mid-session (a new worker reads it).
+    # @param errors [Array<String>] gets a line per config kit left out
+    # @return [Hash{String => Toolkit::Kit}]
+    def toolkit_kits(errors = [])
+      @config_kits = Toolkit.config_kits unless defined?(@config_kits)
+      Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
+    end
+
+    # The session's toolkit resolved (Toolkit::Resolved): what its next
+    # turn declares. A plain full toolkit is nil, the Registry's "every tool".
+    def resolved_toolkit(session, errors = [])
+      resolved = Toolkit.of(session&.toolkit).resolve(toolkit_kits(errors))
+      resolved.everything? ? nil : resolved
+    end
+
+    # The tools this session registered (Tools::Registry), declared or not.
+    attr_reader :tools
+
+    # +toolkit+ (the session's by default) as its next turn would declare
+    # it (/toolkit, the UIs' chip).
+    # @return [Toolkit::Explained]
+    def toolkit_explained(toolkit = nil)
+      toolkit ||= Toolkit.of(@session&.toolkit)
+      resolved = toolkit.resolve(toolkit_kits)
+      filter = resolved.everything? ? nil : resolved
+      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: @tools.entries(toolkit: filter),
+                             left_out: @tools.left_out_names(toolkit: filter), pending: filter != @tools.toolkit)
+    end
+
+    # The session's toolkit for the UIs (the snapshot, command_ran): nil on
+    # full, or with no session.
+    def toolkit_summary
+      @session && toolkit_explained.summary
+    end
+    public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
+
+    # A plugin's ctx.use_toolkit: put the session on toolkit +name+, saved,
+    # when it has no model reply yet and no turn runs (D3: no confirm from
+    # plugins), and tell the user as /toolkit would; it applies at the next
+    # turn's start.
+    # @return [Boolean] whether it was staged
+    # @raise [ArgumentError] an unknown toolkit
+    def use_toolkit(name)
+      raise ArgumentError, "no toolkit named #{name}" unless toolkit_kits.key?(name)
+      return false if @session.nil? || turn_running? || history?
+
+      toolkit = Toolkit.new(name: name)
+      return true if @session.toolkit == toolkit
+
+      @session.toolkit = toolkit
+      @session.save(state_dir: session_state_dir)
+      hook_notify("toolkit: #{name} from the next turn's start", :info, "toolkit", extra: { toolkit: toolkit_summary })
+      true
+    end
+    public :use_toolkit
+
+    # Resolve the session's toolkit into the Registry, on the turn thread at
+    # a turn's start (before its prompt is built), and build the prompts
+    # again when what it declares 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.
+    # @return [Boolean] whether the declared tools changed
+    def apply_toolkit!(session, on_event = nil)
+      errors = []
+      resolved = Toolkit.of(session&.toolkit).resolve(toolkit_kits(errors))
+      warn_toolkit(session, resolved, errors, on_event)
+      resolved = nil if resolved.everything?
+      return false if resolved == @tools.toolkit
+
+      @tools.toolkit = resolved
+      @prompt_builder&.reset!
+      true
+    end
+    private :apply_toolkit!
+
+    # The toolkit's load warnings, each once per process: a name that
+    # didn't resolve, config kits left out.
+    def warn_toolkit(session, resolved, errors, on_event)
+      lines = errors.dup
+      if resolved.fallback
+        lines << "#{Toolkit.of(session&.toolkit).label}: #{resolved.fallback}; this session declares every tool (full) " \
+                 "until it resolves"
+      end
+      @toolkit_warned ||= []
+      (lines - @toolkit_warned).each do |line|
+        @toolkit_warned << line
+        Log.warn(:config, "toolkit_unresolved", message: line)
+        emit_event(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
+      end
+    end
+    private :warn_toolkit
+
     # The tools changed (a plugin's chi.tools_changed!): the system prompts,
     # which declare them, are built again on the next turn.
     def tools_changed!
@@ -2715,6 +2820,9 @@ module Samagotchi
         steer: ->(text, label) { steer(text, source: hook_source(label)) },
         stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
         stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
+        toolkit: -> { @session && Toolkit.of(@session.toolkit).name },
+        declared_tools: -> { toolkit_explained.declared.map(&:name) },
+        use_toolkit: ->(name) { use_toolkit(name) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
           ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller)
         },

data/lib/samagotchi/kernel_loop.rb

@@ -1067,9 +1067,17 @@ module Samagotchi
     # The error an unknown tool name gets back. A shell-like name with
     # `execute` offered this turn points at `execute`; every other unknown
     # name lists what is offered. Neither echoes the wrong name.
+    #
+    # A tool the session's toolkit leaves out is a real one, so its error
+    # does name it (deliberately, against the rule above): the model learns
+    # it exists and that only the user can load it.
     def unknown_tool_error(name, layers)
       names = @tools.names(layers: layers)
-      if SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
+      if @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
+        toolkit = @tools.toolkit&.name
+        "Error: #{name} isn't loaded in this session#{" (toolkit #{toolkit})" if toolkit} and can't be loaded from " \
+          "here; only the user can (/toolkit add #{name}). Available: #{names.join(", ")}"
+      elsif SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
         "Error: no such tool. Shell commands run with `execute` (same arguments)."
       else
         "Error: no such tool. Available: #{names.join(", ")}"

data/lib/samagotchi/llm/anthropic_assembly.rb

@@ -102,9 +102,11 @@ module Samagotchi
       end
 
       # The usage so far as an OpenAI-shaped `usage` object, nil when the
-      # server sent no counts.
+      # server sent no counts, or only zeros (Fireworks' message_start: its
+      # counts come in the last message_delta; a 0 read as an empty context
+      # in the web's ctx meter while the answer streamed).
       def usage_payload
-        return nil if @usage.empty?
+        return nil if @usage.values.none?(&:positive?)
 
         read = @usage["cache_read_input_tokens"].to_i
         write = @usage["cache_creation_input_tokens"].to_i

data/lib/samagotchi/plugin/api.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../toolkit"
 require_relative "../log"
 require_relative "../hooks/registry"
 require_relative "../tools/args"
+require_relative "../commands/registry"
 require_relative "service"
 require_relative "tool_result"
 
@@ -16,6 +18,8 @@ module Samagotchi
       COMMAND_NAME = %r{\A/[a-z][a-z0-9_-]{0,31}\z}
       TOOL_NAME = /\A[a-z][a-z0-9_]{0,47}\z/
       PARAM_NAME = /\A[a-z_][a-z0-9_]*\z/i
+      ANNOTATION_LABEL_MAX = 40
+      ANNOTATIONS_MAX = 5
 
       # @param bundle [String]
       # @param label [String] "<file> (bundle <name>)": what hooks and
@@ -29,9 +33,11 @@ module Samagotchi
         @context = context
         @hooks = []
         @commands = []
+        @annotations = []
         @tools = []
         @services = []
         @inits = []
+        @toolkits = []
         @committed = false
       end
 
@@ -63,6 +69,35 @@ module Samagotchi
         nil
       end
 
+      # A pill in the web's selection bar: it prepares +command+ (a command
+      # line) with +template+ filled from the selected text on the lines
+      # under it ({quote}: the labelled quote block Annotate makes, {text}:
+      # the selection alone, {source}: answer, thinking, step, tool or
+      # user), and fills the composer with it, or sends it at once with
+      # +send+ (docs/plugins.md). Web only.
+      # @param label [String] the pill's text, 1–40 characters
+      # @param command [String] "/name" or "/name words": a command this
+      #   plugin registers (checked once #register returns, so the order
+      #   doesn't matter; another's is a load error)
+      # @param template [String] what goes under the command line
+      # @param send [Boolean] send at once instead of filling the composer
+      def annotation(label, command:, template: "{quote}", send: false)
+        label = label.to_s.strip
+        unless label.length.between?(1, ANNOTATION_LABEL_MAX)
+          raise ArgumentError, "annotation label #{label.inspect} must be 1 to #{ANNOTATION_LABEL_MAX} characters"
+        end
+
+        line = command.to_s.strip
+        name = line.split(/\s/, 2).first.to_s
+        raise ArgumentError, "annotation #{label}: command #{line.inspect} must start with a /name" unless name.match?(COMMAND_NAME)
+        raise ArgumentError, "annotation #{label}: template must be a non-blank String" unless template.is_a?(String) && !template.strip.empty?
+        raise ArgumentError, "at most #{ANNOTATIONS_MAX} annotations per plugin" if @annotations.size >= ANNOTATIONS_MAX
+
+        @annotations << { name: name, annotation: Commands::Registry::Annotation.new(label: label, line: line, template: template,
+                                                                                     sends: send ? true : false) }
+        nil
+      end
+
       # A tool the model can call: the block gets the call's arguments (a
       # frozen Hash, string keys, typed by the schema: see Tools::Args) and
       # the Context, and returns the result text ("Error: …" marks a
@@ -215,12 +250,40 @@ module Samagotchi
         nil
       end
 
-      # Register what was staged. Called by Loader after #register.
+      TOOLKIT_NAME = /\A[a-z][a-z0-9_-]{0,31}\z/
+
+      # A named toolkit sessions can be put on (/toolkit NAME, chi --toolkit,
+      # toolkit.default, ctx.use_toolkit): +base+'s tools (a toolkit chi or
+      # a bundle has) with +add+ declared and +remove+ left out. A name chi
+      # (full, lean, child) or another bundle has is a load error; a base
+      # that doesn't resolve leaves the sessions on it with every tool
+      # (Toolkit#resolve).
+      def toolkit(name, base:, add: [], remove: [])
+        name = name.to_s
+        raise ArgumentError, "toolkit name #{name.inspect} must be a-z, 0-9, _ and -" unless name.match?(TOOLKIT_NAME)
+        raise ArgumentError, "this chi has no toolkits (plugins: false)" unless @registries.toolkits
+        if Toolkit::BUILTIN_KITS.key?(name)
+          raise ArgumentError, "toolkit #{name} is chi's own"
+        elsif (taken = @registries.toolkits.find { |kit| kit.name == name })
+          raise ArgumentError, "toolkit #{name} is already declared (#{taken.source})"
+        end
+        raise ArgumentError, "toolkit #{name} is declared twice" if @toolkits.any? { |kit| kit.name == name }
+
+        @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, source: @bundle)
+        nil
+      end
+
+      # Register what was staged. Called by Loader after #register. What
+      # can only be checked now (an annotation's command) is checked before
+      # anything is registered: a raise here leaves the registries as they were.
       def commit!
+        check_annotations!
         context = @context
         @commands.each do |cmd|
           block = cmd[:block]
-          @registries.commands.register(cmd[:name], cmd[:description], anytime: cmd[:anytime], source: @bundle) do |args|
+          annotations = @annotations.select { |item| item[:name] == cmd[:name] }.map { |item| item[:annotation] }
+          @registries.commands.register(cmd[:name], cmd[:description], anytime: cmd[:anytime], source: @bundle,
+                                                                       annotations: annotations) do |args|
             block.call(args, context)
           end
         end
@@ -243,12 +306,24 @@ module Samagotchi
             block.call(context)
           end
         end
+        @registries.toolkits&.concat(@toolkits)
         @committed = true
       end
 
       # @return [Hash] how many of each it registered (for the log)
-      def counts = { commands: @commands.size, tools: @tools.size, hooks: @hooks.size, services: @services.size,
-                     inits: @inits.size }
+      def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
+                     services: @services.size, inits: @inits.size, toolkits: @toolkits.size }
+
+      # Each annotation's command is one #command staged.
+      def check_annotations!
+        names = @commands.map { |cmd| cmd[:name] }
+        @annotations.each do |item|
+          next if names.include?(item[:name])
+
+          raise ArgumentError, "annotation #{item[:annotation].label}: #{item[:name]} is not a command this plugin registers"
+        end
+      end
+      private :check_annotations!
 
       # A checked tool declaration (#tool's arguments: Api#tool and
       # ToolSet#tool pass theirs on, so a new keyword is added here).
@@ -281,9 +356,7 @@ module Samagotchi
       def self.apply_tools(registry, bundle, specs, context)
         wanted = specs.to_h { |spec| [spec[:name], spec] }
         changed = false
-        registry.entries.each do |entry|
-          next unless entry.source == bundle
-
+        registry.by_source(bundle).each do |entry|
           if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
             entry_fields(spec, context).slice(:handler, :preview, :targets, :refs).each { |key, value| entry[key] = value }
             next

data/lib/samagotchi/plugin/context.rb

@@ -29,9 +29,13 @@ module Samagotchi
     # (reason, label), each true when it acted on a running turn.
     # +frontend+ returns the Engine's interface (:repl, :worker,
     # :non_interactive), which ctx.frontend names for plugins.
+    # +toolkit+ returns the session's toolkit name, +declared_tools+ the
+    # tool names its next turn declares, +use_toolkit+ takes a name and
+    # returns whether it staged it (Engine#use_toolkit).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
-                      :steer, :stop_turn, :stop_generation, :frontend, keyword_init: true)
+                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
+                      keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -109,6 +113,23 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # @return [String, nil] the name of the session's toolkit ("full" for
+      #   one from before toolkits; nil with no session)
+      def toolkit = @host.toolkit&.call
+
+      # @return [Array<String>] the tools the session's next turn declares
+      #   (its toolkit resolved: a kit name says less than this)
+      def declared_tools = Array(@host.declared_tools&.call)
+
+      # Put the session on toolkit +name+ (a plugin's chi.toolkit, or
+      # chi's): only before the session's first model reply and never while
+      # a turn runs, since the declared tools start every request; it then
+      # applies at the next turn's start, and the user is told. Otherwise
+      # nothing changes and the plugin can say to run /toolkit NAME.
+      # @return [Boolean] whether it was staged
+      # @raise [ArgumentError] a toolkit no one declared
+      def use_toolkit(name) = !!@host.use_toolkit&.call(name.to_s)
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/plugin/loader.rb

@@ -16,9 +16,10 @@ module Samagotchi
     # (the Engine's system prompts); +services+ (Plugin::Services) is what
     # Engine#shutdown stops; +stage_tools+ is (bundle, specs, context),
     # chi.replace_tools' set, which the Engine applies on its turn thread;
-    # +init+ adds a chi.init task (Engine#add_init_task).
+    # +init+ adds a chi.init task (Engine#add_init_task); +toolkits+ is the
+    # Engine's list of the plugins' toolkits (chi.toolkit: Toolkit::Kit).
     Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
-                            keyword_init: true)
+                            :toolkits, keyword_init: true)
 
     # Loads installed bundles' plugins (manifest plugin: {file:, sha256:})
     # into an Engine's registries (docs/plugins.md).

data/lib/samagotchi/send_command.rb

@@ -39,7 +39,7 @@ module Samagotchi
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... [--cut | --queue] (ID|PREFIX)...
-             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [-m TEXT] [--image PATH]...
+             chi send --new [--dir DIR] [--model M] [--llm-context LAYERS] [--thinking LEVEL] [--toolkit NAME] [-m TEXT] [--image PATH]...
              chi send --new --continues (ID|PREFIX|last:ID) [-m TEXT] [--image PATH]...
              chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
              chi send --queue --wait [--timeout S] [--format json] [-m TEXT] ID
@@ -63,8 +63,8 @@ module Samagotchi
                     the current one
         --continues ID
                     (--new) start the next link of that session's chain:
-                    in its folder, on its model, LLM context and
-                    thinking level, with a note carrying its recap; it
+                    in its folder, on its model, LLM context,
+                    thinking level and toolkit, with a note carrying its recap; it
                     is archived. last:ID names the chain's latest link.
                     Without -m the new session waits idle. Refused for a
                     session continued already (naming the next link) or
@@ -77,6 +77,11 @@ module Samagotchi
                     (--new) its own thinking level (off, low, medium,
                     high; default: none of its own), above a process
                     default such as SAMAGOTCHI_THINKING_LEVEL
+        --toolkit NAME, --tool NAME, --no-tool NAME
+                    (--new) its toolkit, the tools its prompts declare
+                    (full, lean, child, a config or bundle one; default
+                    config's toolkit.default), and tools declared on top
+                    of it or left out (repeatable, a comma list too)
         --wait      wait for the answer and print it (one session); the
                     other lines go to stderr. Exit 3: it waits for an
                     answer from you: the question, its options and the
@@ -126,6 +131,9 @@ module Samagotchi
       f.value "--llm-context-apply", key: :llm_apply
       f.value "--llm-context-budget", key: :llm_budget
       f.value "--thinking"
+      f.value "--toolkit"
+      f.value "--tool", key: :tools, repeat: true
+      f.value "--no-tool", key: :no_tools, repeat: true
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.switch "--cut"
@@ -262,7 +270,8 @@ module Samagotchi
       return usage_error("at most #{MAX_IMAGES} images") if options[:images].size > MAX_IMAGES
       return new_options(options) if options[:new]
 
-      %i[dir model continues thinking].each { |key| return usage_error("--#{key} needs --new") if options[key] }
+      %i[dir model continues thinking toolkit].each { |key| return usage_error("--#{key} needs --new") if options[key] }
+      TOOLKIT_FLAGS.each { |key, flag| return usage_error("#{flag} needs --new") unless Array(options[key]).empty? }
       LLM_CONTEXT_FLAGS.each { |key, flag| return usage_error("#{flag} needs --new") if options[key] }
       return usage_error("give session ids") if options[:ids].empty?
 
@@ -273,15 +282,19 @@ module Samagotchi
     LLM_CONTEXT_FLAGS = { llm_strategy: "--llm-context", llm_apply: "--llm-context-apply",
                           llm_budget: "--llm-context-budget" }.freeze
     LLM_CONTEXT_FIELDS = { llm_strategy: :strategy, llm_apply: :apply, llm_budget: :budget_tokens }.freeze
+    # --tool / --no-tool's option keys.
+    TOOLKIT_FLAGS = { tools: "--tool", no_tools: "--no-tool" }.freeze
 
     def new_options(options)
       return usage_error("--new takes no session ids: it starts one session") unless options[:ids].empty?
 
       if options[:continues]
         taken = [("--dir" if options[:dir]), ("--model" if options[:model])] +
-                LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] } + [("--thinking" if options[:thinking])]
+                LLM_CONTEXT_FLAGS.filter_map { |key, flag| flag if options[key] } + [("--thinking" if options[:thinking])] +
+                [("--toolkit" if options[:toolkit])] + TOOLKIT_FLAGS.filter_map { |key, flag| flag unless Array(options[key]).empty? }
         unless taken.compact.empty?
-          return usage_error("--continues takes the previous session's folder, model, LLM context and thinking level; " \
+          return usage_error("--continues takes the previous session's folder, model, LLM context, thinking level and " \
+                             "toolkit; " \
                              "leave out #{taken.compact.join(", ")}")
         end
       end
@@ -301,6 +314,8 @@ module Samagotchi
 
         options[:thinking] = Thinking.session_level(word)
       end
+      toolkit = Toolkit.from_flags(name: options[:toolkit], add: options[:tools], remove: options[:no_tools])
+      options[:toolkit_value] = toolkit if toolkit
 
       if options[:dir]
         options[:dir] = File.expand_path(options[:dir])
@@ -348,7 +363,8 @@ module Samagotchi
                     SessionManager.spawn_session(**start, working_directory: options[:dir],
                                                           model_name: options[:model],
                                                           setup: SessionSetup.new(llm_context: options[:llm_context],
-                                                                                  thinking: options[:thinking]),
+                                                                                  thinking: options[:thinking],
+                                                                                  toolkit: options[:toolkit_value]),
                                                           state_dir: @state_dir)
                   end
       rescue SessionContinue::Refused, SessionManager::ArchiveRefused, SessionManager::OwnedByTUI => e

data/lib/samagotchi/session.rb

@@ -184,6 +184,19 @@ module Samagotchi
     # couldn't read; nil when there is neither.
     def reasoning_history_file = @reasoning_history&.to_s || @reasoning_history_unread
 
+    # The session's toolkit (Toolkit: the tools its prompts declare), as
+    # given when it was created; nil for a session from before toolkits,
+    # which is on Toolkit::FULL (Toolkit.of). Saved and never resolved
+    # again from config, so a respawned worker declares the same tools; a
+    # continue and a fork copy it (SessionSetup.of), a delegate child gets
+    # toolkit.child (SessionManager.spawn_session).
+    attr_reader :toolkit
+
+    # @param value [Toolkit, Hash, String, nil] the session file's form too
+    def toolkit=(value)
+      @toolkit = value.is_a?(Toolkit) ? value : Toolkit.from_file(value)
+    end
+
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
     # left), e.g. "loop-guard"; nil when it ended otherwise.
     def stopped_by
@@ -213,7 +226,7 @@ module Samagotchi
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   interrupted_turn: nil)
+                   toolkit: nil, interrupted_turn: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -242,6 +255,7 @@ module Samagotchi
       self.thinking = thinking
       self.reasoning_history = reasoning_history
       self.appended_prompt_files = appended_prompt_files
+      self.toolkit = toolkit
       self.interrupted_turn = interrupted_turn
       @turn_checkpoint = nil
       @archived = false
@@ -336,6 +350,7 @@ module Samagotchi
         thinking: setup.thinking,
         reasoning_history: setup.reasoning_history,
         appended_prompt_files: setup.appended_prompt_files,
+        toolkit: setup.toolkit,
         continues: continues
       )
     end
@@ -400,6 +415,7 @@ module Samagotchi
       "thinking" => nil,
       "reasoning_history" => nil,
       "appended_prompt_files" => [],
+      "toolkit" => nil,
       "interrupted_turn" => nil
     }.freeze
 
@@ -527,6 +543,7 @@ module Samagotchi
                 when "llm_context" then llm_context_file
                 when "thinking" then thinking_file
                 when "reasoning_history" then reasoning_history_file
+                when "toolkit" then @toolkit&.to_file
                 when "prompt_notes" then @prompt_notes.map(&:to_file)
                 when "last_turn" then @last_turn&.to_file
                 when "used_memory_names", "preloaded_memory_names", "muted_memory_names", "appended_prompt_files"

data/lib/samagotchi/session_commands.rb

@@ -12,6 +12,7 @@ require_relative "tools/peers"
 require_relative "commands/registry"
 require_relative "llm_context_command"
 require_relative "thinking_command"
+require_relative "toolkit_command"
 require_relative "reasoning_history_command"
 
 module Samagotchi
@@ -32,6 +33,7 @@ module Samagotchi
     HELP_COMMAND = "/help"
     LLM_CONTEXT_COMMAND = LLMContextCommand::NAME
     THINKING_COMMAND = ThinkingCommand::NAME
+    TOOLKIT_COMMAND = ToolkitCommand::NAME
     REASONING_HISTORY_COMMAND = ReasoningHistoryCommand::NAME
     # A remote catalog has hundreds of ids (OpenRouter ~380): plain /models
     # shows this many per host; /models <text> lists every match.
@@ -48,7 +50,7 @@ module Samagotchi
 
     # The commands that ask before a change that restarts the prompt cache
     # (CacheConfirm): #run passes them its confirm flag.
-    CONFIRMING = %i[thinking reasoning_history].freeze
+    CONFIRMING = %i[thinking reasoning_history toolkit].freeze
 
     # @!attribute status [Symbol] :ok, or :error when the line was refused
     # @!attribute output [String, nil] what to tell the user
@@ -103,6 +105,9 @@ module Samagotchi
       registry.register(REASONING_HISTORY_COMMAND, "show or set which of its reasoning this session's model gets back (drop|turn|all|default)",
                         id: :reasoning_history, mid_turn: show_mid_turn(REASONING_HISTORY_COMMAND),
                         match: ->(text) { text.match?(%r{\A/reasoning-history(?:\s+.*)?\z}) }) { |text| reasoning_history(text) }
+      registry.register(TOOLKIT_COMMAND, "show or change the tools this session declares (NAME, add TOOL, remove TOOL)",
+                        id: :toolkit, mid_turn: show_mid_turn(TOOLKIT_COMMAND),
+                        match: ->(text) { text.match?(%r{\A/toolkit(?:\s+.*)?\z}) }) { |text| toolkit(text) }
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       registry.register("/recap", "show the session's recap", local: true)
@@ -467,6 +472,16 @@ module Samagotchi
       reply(e.message, status: :error)
     end
 
+    # /toolkit (ToolkitCommand); :toolkit in changed when it set the
+    # session's toolkit.
+    def toolkit(text, confirm: true)
+      output, changed, ask = ToolkitCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
+                                           .run(text.delete_prefix(TOOLKIT_COMMAND), confirm: confirm)
+      reply(output, changed: changed ? [:toolkit] : [], confirm: ask)
+    rescue ArgumentError => e
+      reply(e.message, status: :error)
+    end
+
     # A session setting changed (/llm-context, /thinking, /reasoning-history):
     # saved with its model.
     def save_setup(session)

data/lib/samagotchi/session_manager.rb

@@ -140,7 +140,9 @@ module Samagotchi
     # @param title [String, nil] what the lists show before the first turn
     #   (the prompt's preview by default, else the seed's first user message)
     # @param setup [SessionSetup] the session's own settings (chi
-    #   --llm-context; a fork and a continue copy their session's)
+    #   --llm-context; a fork and a continue copy their session's); without
+    #   a toolkit the session is stored on config's toolkit.default, a
+    #   delegate child always on toolkit.child (Toolkit.configured)
     # @param continues [String, nil] the session this one continues (a
     #   session field; SessionContinue)
     # @param note [String, nil] a context note the session starts with,
@@ -177,6 +179,7 @@ module Samagotchi
         setup: setup,
         continues: continues
       )
+      session.toolkit = Toolkit.configured(delegate: delegate) if delegate || session.toolkit.nil?
       session.model_warning = model_warning
       # With no prompt there is no first turn to run (an attaching UI sends
       # the prompts), so the session starts idle.