samagotchi 0.65.0 → 0.67.0

data/lib/samagotchi/send_command.rb

@@ -39,8 +39,8 @@ 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 --continues (ID|PREFIX|last:ID) [-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) [--model M] [-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
              chi send --wait [--timeout S] [--format json] ID
@@ -63,9 +63,11 @@ 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
-                    is archived. last:ID names the chain's latest link.
+                    in its folder, on its model (or --model's; one whose
+                    host is gone falls back to the default, with a
+                    warning), 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
                     with delegates still open
@@ -77,6 +79,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 +133,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 +272,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 +284,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])]
+        taken = [("--dir" if options[:dir])] +
+                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, LLM context, thinking level and " \
+                             "toolkit; " \
                              "leave out #{taken.compact.join(", ")}")
         end
       end
@@ -301,6 +316,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])
@@ -343,12 +360,14 @@ module Samagotchi
       begin
         start = through_worker ? { prompt: nil, title: prompt } : { prompt: prompt }
         session = if options[:continues]
-                    SessionManager.continue_session(options[:continues], **start, state_dir: @state_dir)
+                    SessionManager.continue_session(options[:continues], **start, model: options[:model],
+                                                                             state_dir: @state_dir)
                   else
                     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
@@ -372,15 +391,22 @@ module Samagotchi
                                  timeout: options[:timeout])
     end
 
-    # --continues: the model the new link will run (the previous link's),
-    # for the images check; [nil, nil] without --continues.
+    # The model the new session will run, for the images check: --model
+    # (nil: the default), or with --continues the one the new link will run
+    # (SessionContinue.model_for: --model's, else the previous link's, else
+    # the default it falls back to).
     # @return [Array, false] [model_name, model_typed], or false after the
-    #   error line (no such session)
+    #   error line (no such session, a model it can't start on)
     def continued_model(options)
       return [options[:model], nil] unless options[:continues]
 
       previous = Session.load(SessionChain.resolve(options[:continues], state_dir: @state_dir), state_dir: @state_dir)
-      [previous.model_name, previous.model_typed]
+      choice = SessionContinue.model_for(previous, options[:model])
+      inherited = options[:model].to_s.strip.empty? && choice.warning.nil?
+      inherited ? [previous.model_name, previous.model_typed] : [choice.model, nil]
+    rescue ModelProfile::MissingModel => e
+      error_line("chi send: could not start a session: #{e.message}")
+      false
     rescue ArgumentError => e
       error_line("chi send: #{e.message}")
       false

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_continue.rb

@@ -56,11 +56,21 @@ module Samagotchi
     # moved the chain's end while it waited for the lock.
     TRIES = 3
 
+    # The model a new link runs on (#model_for): the name to spawn it with,
+    # and why it isn't the previous link's (nil when it is, or was given).
+    ModelChoice = Data.define(:model, :warning)
+    # What #check! decided before anything changes: the delegates to move
+    # (ChildMove::Plan) and the new link's model (ModelChoice).
+    Checked = Data.define(:plan, :choice)
+
     # Start the next link of a chain: a new session that continues
     # +id_or_ref+ (Session#continues) in its folder, on its model (the name
     # it was typed as, so an alias holds) and with its own setup (SessionSetup),
     # starting with a context note from chi: the link and the previous
-    # link's recap (SessionChain.note_text). The previous link is archived
+    # link's recap (SessionChain.note_text). +model+, when given, is the
+    # new link's model instead; an inherited one whose host can't run it any
+    # more (gone, disabled, an alias naming another host) falls back to the
+    # default with a warning (#model_for). The previous link is archived
     # first, with its finished delegates (archive_session's rules: a turn
     # running, a prompt queued or the step-limit question refuse; an idle
     # worker is stopped), so a refusal starts nothing. Its open delegates
@@ -81,7 +91,7 @@ module Samagotchi
     # @raise [Refused] continued already, delegates open that can't
     #   move, or its folder is gone
     # @raise [ArchiveRefused, OwnedByTUI] as archive_session
-    def self.run(id_or_ref, prompt: nil, title: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
+    def self.run(id_or_ref, prompt: nil, title: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
       sd = state_dir || Session.default_state_dir
       TRIES.times do |try|
         id = SessionChain.resolve(id_or_ref, state_dir: sd)
@@ -89,7 +99,7 @@ module Samagotchi
           follow = id_or_ref.to_s.strip.start_with?(SessionChain::LAST_PREFIX) && try < TRIES - 1
           next :moved if follow && SessionChain.next_of(id, state_dir: sd)
 
-          run_locked(id, prompt: prompt, title: title, state_dir: sd, recap_wait: recap_wait,
+          run_locked(id, prompt: prompt, title: title, model: model, state_dir: sd, recap_wait: recap_wait,
                          archive_wait: archive_wait)
         end
         return result unless result == :moved
@@ -105,9 +115,10 @@ module Samagotchi
       end
     end
 
-    private_class_method def self.run_locked(id, prompt:, title:, state_dir:, recap_wait:, archive_wait:)
+    private_class_method def self.run_locked(id, prompt:, title:, model:, state_dir:, recap_wait:, archive_wait:)
       previous = Session.load(id, state_dir: state_dir)
-      plan = check!(previous, state_dir)
+      checked = check!(previous, state_dir, model: model)
+      plan = checked.plan
       # archive_session's refusals that can be known now, before the wait.
       SessionManager.archivable!(id, state_dir, except: plan.move)
       recap_before_archive(id, state_dir, wait: recap_wait)
@@ -120,7 +131,8 @@ module Samagotchi
       archive = SessionManager.archive_session(id, state_dir: state_dir, wait: archive_wait, except: plan.move)
       archived = archive[:archived] - already
       begin
-        spawn_continuation(previous, prompt: prompt, title: title, state_dir: state_dir, move: plan.move)
+        spawn_continuation(previous, prompt: prompt, title: title, choice: checked.choice, state_dir: state_dir,
+                                     move: plan.move)
       rescue StandardError
         # Nothing started: the delegates go back, what this archived goes
         # back to the lists, and a new link saved before its worker failed
@@ -181,7 +193,7 @@ module Samagotchi
 
     # The new link, holding off any worker but its own (ChildMove.starting?)
     # while +move+ goes to it.
-    private_class_method def self.spawn_continuation(previous, prompt:, title:, state_dir:, move:)
+    private_class_method def self.spawn_continuation(previous, prompt:, title:, choice:, state_dir:, move:)
       recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
       start = prompt.to_s.strip.empty? ? nil : prompt
       title = previous.first_preview if title.to_s.strip.empty? && start.nil?
@@ -191,33 +203,64 @@ module Samagotchi
       end
       link = SessionManager.spawn_session(
         prompt: start, title: title, working_directory: previous.working_directory,
-        model_name: previous.model_typed || previous.model_name, setup: SessionSetup.of(previous),
+        model_name: choice.model, setup: SessionSetup.of(previous),
         continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
         note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn
       )
       link.moved_children = move
+      # The fallback's warning first: spawn_session set its own.
+      warnings = [choice.warning, link.model_warning].compact
+      link.model_warning = warnings.join("; ") unless warnings.empty?
       link
     end
 
+    # The model a new link of +previous+'s chain runs on: +given+ when
+    # there is one (its host checked: ModelProfile::UnknownHost as for a new
+    # session), else the previous link's, as typed (so an alias holds). An
+    # inherited one whose host can't run it any more (gone from config.yml,
+    # disabled, an alias naming another host: UnknownHost) falls back to the
+    # default, with a warning naming why. `chi send --new --continues`
+    # judges images by it before #run decides the same.
+    # @param previous [Session]
+    # @param given [String, nil] blank: inherit
+    # @return [ModelChoice]
+    # @raise [ModelProfile::MissingModel] a +given+ model it can't run, or
+    #   a fallback with no default configured (or the default's host can't run it)
+    def self.model_for(previous, given)
+      unless given.to_s.strip.empty?
+        return ModelChoice.new(model: ModelProfile.check_host!(ModelProfile.required_model_name(given.strip)),
+                               warning: nil)
+      end
+
+      inherited = ModelProfile.required_model_name(previous.model_typed || previous.model_name)
+      begin
+        ModelChoice.new(model: ModelProfile.check_host!(inherited), warning: nil)
+      rescue ModelProfile::UnknownHost => e
+        default = ModelProfile.check_host!(ModelProfile.required_model_name(nil))
+        ModelChoice.new(model: default, warning: "#{inherited} can't run (#{e.message}); started on #{default}")
+      end
+    end
+
     # The refusals that come before anything changes: continued already (no
     # forks in a chain), an open delegate that can't move to the new link
     # (ChildMove.plan), the folder gone (the worker would run elsewhere), a
-    # model whose host config.yml no longer has.
-    # @return [ChildMove::Plan]
+    # given model whose host config.yml doesn't have, or an inherited one
+    # that can't run with no default to fall back to (#model_for).
+    # @return [Checked]
     # @raise [Refused, ModelProfile::MissingModel]
-    private_class_method def self.check!(previous, state_dir)
+    private_class_method def self.check!(previous, state_dir, model: nil)
       if (following = SessionChain.next_of(previous.id, state_dir: state_dir))
         raise Refused.new(previous.id, :continued, ids: [following])
       end
 
       plan = move_plan!(previous.id, state_dir)
-      # Its model's host, as SessionManager.spawn_session checks it: before
-      # the archive stops the previous link's worker.
-      ModelProfile.check_host!(ModelProfile.required_model_name(previous.model_typed || previous.model_name))
+      # The new link's model, its host checked as SessionManager.spawn_session
+      # checks it: before the archive stops the previous link's worker.
+      choice = model_for(previous, model)
       dir = previous.working_directory.to_s
       raise Refused.new(previous.id, :folder_gone, detail: dir) unless File.directory?(dir)
 
-      plan
+      Checked.new(plan: plan, choice: choice)
     end
 
     # A child still open below a session (#open_children); why: running,

data/lib/samagotchi/session_inbox.rb

@@ -236,15 +236,6 @@ module Samagotchi
       UNREADABLE_INPUT
     end
 
-    # Whether an unclaimed input file carries images (a mid-turn drain
-    # leaves it for its own turn).
-    def self.input_has_images?(input_file)
-      data = JSON.parse(File.read(input_file))
-      data.is_a?(Hash) && Array(data["images"]).any?
-    rescue JSON::ParserError, SystemCallError
-      false
-    end
-
     # Whether a mid-turn drain leaves this unclaimed input file for a turn
     # of its own instead of merging it at a step boundary: a queued message
     # (`delivery: queue`) or an image message (steering merges text only).
@@ -258,10 +249,6 @@ module Samagotchi
       false
     end
 
-    # Whether an input file carrying +enqueued_id+ still waits unclaimed in
-    # input/ (no worker has taken it for a turn or a step yet).
-    def self.input_waiting?(session_dir, enqueued_id) = !waiting_input(session_dir, enqueued_id).nil?
-
     # How the unclaimed input file carrying +enqueued_id+ waits: :turn_end
     # (a queue or an image message: it runs as a turn of its own, never
     # merged, #waits_for_turn_end?), :merges (a running turn's drain may

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.

data/lib/samagotchi/session_setup.rb

@@ -3,6 +3,7 @@
 require_relative "llm_context_override"
 require_relative "reasoning_history"
 require_relative "thinking"
+require_relative "toolkit"
 
 module Samagotchi
   # A session's own settings that come before its model's, carried as one
@@ -12,27 +13,33 @@ module Samagotchi
   # +thinking+ a level Symbol (Thinking.session_level) or nil,
   # +reasoning_history+ a level Symbol (ReasoningHistory.session_level) or nil,
   # +appended_prompt_files+ the absolute paths chi --append-system-prompt
-  # named (their text goes into the system prompt; [] with none).
+  # named (their text goes into the system prompt; [] with none),
+  # +toolkit+ a Toolkit or nil (SessionManager.spawn_session gives the
+  # session config's toolkit.default then).
   #
   # It doesn't save itself: the session keeps each setting in its own field
   # and file key, and resolves it on its own. A delegate child starts
   # without one; a continue and a fork copy their session's (.of).
-  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files) do
-    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [])
+  SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files, :toolkit) do
+    def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [], toolkit: nil)
       super(llm_context: llm_context, thinking: thinking, reasoning_history: reasoning_history,
-            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze)
+            appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze, toolkit: toolkit)
     end
 
-    def empty? = llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty?
+    def empty?
+      llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty? && toolkit.nil?
+    end
 
-    # A session's own setup, for a session that starts from it.
+    # A session's own setup, for a session that starts from it. Its
+    # toolkit always: one from before toolkits is full (Toolkit.of), not
+    # whatever config's default is now.
     # @param session [Session, nil]
     # @return [SessionSetup]
     def self.of(session)
       return new if session.nil?
 
       new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history,
-          appended_prompt_files: session.appended_prompt_files)
+          appended_prompt_files: session.appended_prompt_files, toolkit: Toolkit.of(session.toolkit))
     end
   end
 end

data/lib/samagotchi/system_prompt.rb

@@ -317,7 +317,7 @@ module Samagotchi
         "Project memories:\n#{indexes[:project]}",
         "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
-      stable = [thinking_token + base, rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
+      stable = [thinking_token + base, not_loaded_line(layers), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
                 project_specific_description, appended_section, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [current_model, project_location, current_session].compact
@@ -328,6 +328,21 @@ module Samagotchi
       with_tail_declarations(prompt, chat: chat, layers: layers)
     end
 
+    # 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.
+    def not_loaded_line(layers)
+      registry = @tools_lookup.call
+      return nil unless registry.respond_to?(:left_out_names)
+
+      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>)."
+    end
+
     def with_tail_declarations(prompt, chat:, layers:)
       chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(layers)
     end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -46,17 +46,23 @@ module Samagotchi
       # @param thinking [String, nil] --thinking as typed: a new session
       #   starts with it as its own level; a resumed or attached one's
       #   worker gets a /thinking, after those
+      # @param toolkit [Toolkit, nil] --toolkit/--tool/--no-tool: a new
+      #   session's toolkit (config's toolkit.default without); an existing
+      #   session keeps its own
+      # @param toolkit_flags [Array<String>] which of those were given, for
+      #   the line an existing session's run prints
       # @param state_dir [String, nil] where the sessions are (the default
       #   state dir by default): the worker's, for the attached loop too
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], state_dir: nil)
+              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
+              toolkit_flags: [], state_dir: nil)
         state_dir ||= Session.default_state_dir
         client = connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
                          memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking,
-                         appended_prompt_files: appended_prompt_files)
+                         appended_prompt_files: appended_prompt_files, toolkit: toolkit, toolkit_flags: toolkit_flags)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
@@ -123,10 +129,12 @@ module Samagotchi
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
-                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], err: $stderr)
+                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], toolkit: nil,
+                  toolkit_flags: [], err: $stderr)
         sd = state_dir || Session.default_state_dir
         if attach || resume
-          warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files)
+          warn_memory_flags_ignored(attach || resume, memories, muted_memories, err, appended_prompt_files: appended_prompt_files,
+                                                                                     toolkit_flags: toolkit_flags)
         end
         if attach
           live = connect_existing(attach, sd)
@@ -143,7 +151,8 @@ module Samagotchi
                                                  memories: memories, muted_memories: muted_memories,
                                                  setup: SessionSetup.new(llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context),
                                                                          thinking: Thinking.session_level(thinking),
-                                                                         appended_prompt_files: appended_prompt_files))
+                                                                         appended_prompt_files: appended_prompt_files,
+                                                                         toolkit: toolkit))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")
@@ -159,14 +168,15 @@ module Samagotchi
       end
 
       # An existing session's prompt is built from its own session fields:
-      # --memory/--mute/--append-system-prompt given with --attach or
-      # --resume are ignored, with a line saying so (printed before the live
-      # region opens).
-      def warn_memory_flags_ignored(session_id, memories, muted_memories, err, appended_prompt_files: [])
+      # --memory/--mute/--append-system-prompt and the toolkit flags given
+      # with --attach or --resume are ignored, with a line saying so (printed
+      # before the live region opens).
+      def warn_memory_flags_ignored(session_id, memories, muted_memories, err, appended_prompt_files: [], toolkit_flags: [])
         flags = []
         flags << "--memory" unless Array(memories).empty?
         flags << "--mute" unless Array(muted_memories).empty?
         flags << "--append-system-prompt" unless Array(appended_prompt_files).empty?
+        flags.concat(toolkit_flags)
         return if flags.empty?
 
         verb = flags.size == 1 ? "applies" : "apply"

data/lib/samagotchi/terminal_ui.rb

@@ -97,10 +97,15 @@ module Samagotchi
     # @param appended_prompt_files [Array<String>] --append-system-prompt's
     #   files (absolute): a new session saves them; a resumed one's own come
     #   first, and the merge goes only to the Engine (as --memory's does)
+    # @param toolkit [Toolkit, nil] --toolkit/--tool/--no-tool: a new
+    #   session's toolkit (config's toolkit.default without); a resumed one
+    #   keeps its own, with a line naming +toolkit_flags+ (the flags given)
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
                    spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil,
-                   appended_prompt_files: [])
+                   appended_prompt_files: [], toolkit: nil, toolkit_flags: [])
       @scratch        = scratch
+      @toolkit        = toolkit
+      @toolkit_flags  = toolkit_flags
       @thinking_word  = thinking
       @prompt         = prompt
       @llm_context_words = llm_context
@@ -269,7 +274,7 @@ module Samagotchi
         preloaded_memory_names: @requested_memories,
         muted_memory_names: @muted_memory_names,
         scratch: @scratch,
-        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files)
+        setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files, toolkit: @toolkit || Toolkit.configured)
       ))
       # --llm-context*: the session's own values, over a resumed one's.
       # Saved at once on a resumed one: leaving before a turn keeps them.
@@ -279,6 +284,7 @@ module Samagotchi
         session.thinking = Thinking.session_level(@thinking_word) if @thinking_word
         session.save if @resume_session
       end
+      warn_toolkit_flags_ignored(session) if @resume_session
       claim_session!(session.id) unless @owner_lock
       # A turn a worker died in (TurnCheckpoint): ended as canceled, with its
       # note, before this REPL's first turn appends after it.
@@ -714,6 +720,16 @@ module Samagotchi
       end
     end
 
+    # The toolkit flags are a new session's: a resumed one keeps its own
+    # toolkit (as attached mode says it, AttachLauncher).
+    def warn_toolkit_flags_ignored(session)
+      return if @toolkit_flags.empty?
+
+      names = @toolkit_flags.size > 1 ? "#{@toolkit_flags[0..-2].join(", ")} and #{@toolkit_flags.last}" : @toolkit_flags.first
+      warn "(#{names} #{@toolkit_flags.size == 1 ? "applies" : "apply"} to a new session; #{session.id}'s prompt is already built)"
+    end
+    private :warn_toolkit_flags_ignored
+
     private
 
     # Interactive REPL loop. Session seed + messages are built by #run and

data/lib/samagotchi/tool_call_parser.rb

@@ -36,7 +36,7 @@ module Samagotchi
     #              <|channel>thought......<channel|>
     class Gemma
       # Digits after the first character: plugin tools may have them
-      # (Plugin::Api::TOOL_NAME).
+      # (Plugin::ToolSpec::TOOL_NAME).
       TOOL_CALL_BODY_RE = /\Acall:([a-z_][a-z0-9_]{0,49})\{/
       THOUGHT_CHANNEL_OPEN  = ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN
       THOUGHT_CHANNEL_CLOSE = ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE