samagotchi 0.121.0 → 0.122.0

data/lib/samagotchi/system_one/self_protect.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "../paths"
 require_relative "../config"
 require_relative "../memory_paths"
-require_relative "../hooks/loader"
 require_relative "../guardrails/protected_paths"
+require_relative "../guardrails/parent_approvals"
 
 module Samagotchi
   module SystemOne
@@ -23,13 +22,17 @@ module Samagotchi
       # there is one agent approving another's, so the user decides them even
       # when they are listed in `guardrails.system_one.rules`.
       NEVER_AUTO = %w[chi-answer-piped chi-answer-http chi-broadcast].freeze
-      # chi's config file, however the user names it in config.yml.
-      CONFIG_FILE = /\Aconfig[\w-]*\.ya?ml\z/i
-      # The dirs as a shell command may spell them when the settings point
-      # elsewhere: chi's default config dir and default state dir. A path
-      # into the memories dir is not a control file.
-      DEFAULT_CONFIG_TEXT = %r{\B~/\.config/samagotchi(?!/memories)}
+      # chi's default state dir as a shell command may spell it when the
+      # settings point elsewhere (the sessions and the guardrails store live
+      # there).
       DEFAULT_STATE_TEXT = %r{\B~/\.local/state/samagotchi}
+      # The characters that end a shell word: a memories path in a command
+      # ends at the first one.
+      WORD_END = %q{[\s'"`;&|<>(){}:,]}
+      # A `..` segment anywhere in a command: with one, a memories path may
+      # climb back out (`memories/../config.yml`, `cd memories && … ../x`),
+      # so the command's memories text is not taken out.
+      CLIMB = %r{(?:\A|[\s/'"=])\.\.(?:/|[\s'"]|\z)}
 
       module_function
 
@@ -39,47 +42,40 @@ module Samagotchi
       def refuse?(approval)
         return false unless approval.is_a?(Hash)
         return true if NEVER_AUTO.include?(fetch(approval, :rule).to_s)
-
-        dirs = control_dirs
-        paths = Array(fetch(approval, :paths)).map(&:to_s).reject(&:empty?)
-        return true if paths.any? { |path| control_path?(path, dirs) }
+        # The test that makes an ask user_only (ParentApprovals#chi_files?:
+        # chi's dirs, however a command spells them), minus the memories.
+        return true if Guardrails::ParentApprovals.chi_files?(beyond_memories(approval))
 
         command = fetch(approval, :command).to_s
-        !command.empty? && control_text?(command, dirs)
-      end
-
-      # The dirs whose files are chi's own: its hooks, its installed bundles,
-      # the guardrails store (approvals.json and judgments.jsonl).
-      # @return [Array<String>]
-      def control_dirs
-        [Hooks::Loader.hooks_dir, MemoryPaths.bundles_dir, File.join(Paths.state_dir, "guardrails")]
-          .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?)
+        command.match?(DEFAULT_STATE_TEXT)
       end
 
-      def control_path?(path, dirs)
-        real = Guardrails::ProtectedPaths.real(path)
-        return true if dirs.any? { |dir| Guardrails::ProtectedPaths.within?(real, dir) }
-        return true if config_file?(real)
-
-        control_text?(path, dirs)
-      end
-
-      # config.yml in chi's config dir — not the memories beside it.
-      def config_file?(path)
-        Guardrails::ProtectedPaths.within?(path, ConfigFile.config_dir) && File.basename(path).match?(CONFIG_FILE)
-      end
-
-      # A command or path naming one of those dirs, in the spelling this
-      # process uses or the default `~/.config/samagotchi` one.
-      def control_text?(text, dirs)
-        dirs.any? { |dir| text.include?(dir) || text.include?(File.expand_path(dir)) } ||
-          text.match?(config_text) || text.match?(DEFAULT_CONFIG_TEXT) || text.match?(DEFAULT_STATE_TEXT)
+      # The approval's facts without what is in the memories dir (not its
+      # installed bundles): the paths under it, and its spellings in the
+      # command unless the command climbs with `..`.
+      def beyond_memories(approval)
+        memories = Guardrails::ProtectedPaths.real(MemoryPaths.system_dir)
+        bundles = Guardrails::ProtectedPaths.real(MemoryPaths.bundles_dir)
+        paths = Array(fetch(approval, :paths)).map(&:to_s).reject do |path|
+          real = Guardrails::ProtectedPaths.real(path)
+          Guardrails::ProtectedPaths.within?(real, memories) && !Guardrails::ProtectedPaths.within?(real, bundles)
+        end
+        command = fetch(approval, :command).to_s
+        unless command.match?(CLIMB)
+          command = command.gsub(memories_text) { |text| text.include?("/.bundles") ? text : "" }
+        end
+        { paths: paths, command: command }
       end
 
-      # chi's config dir as text — everything under it except the memories,
-      # which the model works with.
-      def config_text
-        Regexp.new("#{Regexp.escape(ConfigFile.config_dir)}(?![/]memories)")
+      # The memories dir as a command spells it: the default
+      # `.config/samagotchi/memories`, or this process's own path, with the
+      # rest of that shell word.
+      def memories_text
+        dir = ConfigFile.config_dir
+        prefixes = [".config/samagotchi", dir, Guardrails::ProtectedPaths.real(dir)]
+                   .map { |prefix| Regexp.escape(prefix.to_s.chomp("/")) }.uniq
+        word = WORD_END.sub("[", "[^")
+        Regexp.new("(?:#{prefixes.join("|")})/memories(?=/|#{WORD_END}|\\z)(?:/#{word}*)?")
       end
 
       def fetch(hash, key)

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -6,6 +6,7 @@ require_relative "../model_profile"
 require_relative "../session_manager"
 require_relative "../thinking_command"
 require_relative "../bridge_client"
+require_relative "../worker_link"
 require_relative "../parent_report"
 require_relative "../cli/exit"
 require_relative "../launch_mode"
@@ -207,8 +208,8 @@ module Samagotchi
                                                                          toolkit: toolkit, settings: settings,
                                                                          parent_answers: parent_answers))
                   end
-        client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
-        client || raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
+        link = WorkerLink.await(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
+        link.live? ? link.client(session.id) : raise(Error, format(LaunchMode::BRIDGE_LATE, session.id))
       rescue SessionManager::OwnedByTUI => e
         raise Error, e.message
       rescue ArgumentError => e
@@ -248,9 +249,13 @@ module Samagotchi
       end
 
       # @return [BridgeClient, nil] the running worker's, or nil when none runs
+      # @raise [Error] its worker is newer than this chi (Skew)
       def connect_existing(session_id, state_dir)
         Session.load(session_id, state_dir: state_dir)
-        BridgeClient.discover(session_id, session_dir: Session.session_dir(session_id, state_dir: state_dir))
+        link = WorkerLink.resolve(Session.session_dir(session_id, state_dir: state_dir), unlink: true)
+        raise Error, link.message(session_id) if link.is_a?(WorkerLink::Skew)
+
+        link.live? ? link.client(session_id) : nil
       end
     end
   end

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -439,7 +439,7 @@ module Samagotchi
 
       # The stream moved to a new worker (a restart): requests go there too.
       def switch_worker(event)
-        @client = @link.switched(event)
+        @client = @link.switched(event) || @client
         @worker_changed = true
         # The new worker's machine may name another default model.
         @default_model_name = nil
@@ -452,9 +452,11 @@ module Samagotchi
       def closed_line(reason)
         id = @client.session_id
         # The worker asked for a secret this terminal's chi doesn't send.
-        return "Lost the session's worker: #{BridgeSecret::REFUSED}" if reason == BridgeSecret::ERROR
+        return "Lost the session's worker: #{BridgeSecret.refused(id, via: via)}" if reason == BridgeSecret::ERROR
         return remote_closed_line(reason, id) if via.remote?
 
+        return "Lost the session's worker: #{@link.failure}" if reason == "worker_newer" && @link.failure
+
         # Here a stopped session has always read as unreachable.
         reason = "unreachable" if reason == "stopped"
         "Lost the session's worker (#{reason}). Resume it with: #{via.command("--shared --resume #{id}")}"

data/lib/samagotchi/terminal_ui/local_link.rb

@@ -3,7 +3,7 @@
 require_relative "attach_link"
 require_relative "../session"
 require_relative "../bridge_client"
-require_relative "../worker_sidecar"
+require_relative "../worker_link"
 require_relative "../delivery"
 require_relative "../session_inbox"
 require_relative "../image_store"
@@ -42,6 +42,8 @@ module Samagotchi
                      installed_version: -> { InstalledVersions.new.newest },
                      children_counts: ->(id) { ChildrenStatus.counts(id, state_dir: state_dir) })
         @client = client
+        @session_id = client.session_id
+        @host = BridgeClient::HOST
         @state_dir = state_dir
         @delete_session = delete_session
         @archive_session = archive_session
@@ -52,30 +54,36 @@ module Samagotchi
       # The sidecar's worker, nil while none runs; gone once the session was
       # stopped (no worker is coming): its stop marker in +state_dir+.
       def live_worker
-        id = @client.session_id
+        id = @session_id
         return [:gone, "stopped"] if Session.stopped_marker?(id, state_dir: @state_dir)
 
+        link = WorkerLink.resolve(session_dir, unlink: true, host: @host)
+        if link.is_a?(WorkerLink::Skew)
+          @failure = link.message(id)
+          return [:gone, "worker_newer"]
+        end
+
         # Kept: the stream moves to this very client (EventStream), and
         # #switched takes it, port and secret, rather than reading again.
-        @found = BridgeClient.discover(id, session_dir: session_dir, host: @client.host)
+        @found = link.live? ? link.client(id, host: @host) : nil
         [@found, nil]
       end
 
       # A new worker's Bridge: the client #live_worker found for the stream
-      # (the event names its port), with that worker's secret. One the event
-      # doesn't name (another worker since) is read from the sidecar for that
-      # port, none when the sidecar names another one by now: that worker is
-      # gone too, and the stream finds the next.
+      # (the event names its port), with that worker's secret. An event that
+      # names another worker is resolved again; a mismatched sidecar never
+      # becomes a secretless client.
       def switched(event)
         port = AttachLink.event_port(event)
         found = @found
-        @client = if found&.port == port
-                    found
-                  else
-                    sidecar = WorkerSidecar.read(session_dir)
-                    sidecar = WorkerSidecar.new(port: port) unless sidecar&.port == port
-                    BridgeClient.for_sidecar(@client.session_id, sidecar, host: @client.host)
-                  end
+        candidate = if found&.port == port
+                      found
+                    else
+                      link = WorkerLink.resolve(session_dir, unlink: true, host: @host)
+                      link.live? && link.port == port ? link.client(@session_id, host: @host) : nil
+                    end
+        @client = candidate if candidate
+        candidate
       end
 
       # No sidecar to read: true, its Bridge answers (a P0-P2 worker refuses
@@ -139,18 +147,19 @@ module Samagotchi
 
       def via = ChiInvocation::HERE
 
-      # The closing line says it all (unreachable, unknown_session).
-      def failure = nil
+      # The closing line says it all (unreachable, unknown_session); a worker
+      # newer than this chi names itself.
+      attr_reader :failure
 
       def close = nil
 
       private
 
-      def session_dir = Session.session_dir(@client.session_id, state_dir: @state_dir)
+      def session_dir = Session.session_dir(@session_id, state_dir: @state_dir)
 
       def feature?(name)
-        sidecar = WorkerSidecar.read(session_dir)
-        sidecar.nil? || sidecar.features.include?(name)
+        link = WorkerLink.resolve(session_dir, unlink: false)
+        !link.live? || link.features.include?(name)
       end
     end
   end

data/lib/samagotchi/terminal_ui.rb

@@ -295,7 +295,8 @@ module Samagotchi
         muted_memory_names: @muted_memory_names,
         scratch: @scratch,
         setup: SessionSetup.new(appended_prompt_files: @appended_prompt_files, toolkit: @toolkit || Toolkit.configured,
-                                settings: @session_settings, parent_answers: @parent_answers)
+                                toolkit_origin: @toolkit ? "chosen" : "default", settings: @session_settings,
+                                parent_answers: @parent_answers)
       ))
       # --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.

data/lib/samagotchi/tool_runner.rb

@@ -14,6 +14,7 @@ require_relative "tools/output_guardrails"
 require_relative "tools/tool_path"
 require_relative "memory_bundle/index_sync"
 require_relative "memory_bundle/index_size"
+require_relative "participant_mode"
 
 module Samagotchi
   # One call's result from ToolRunner#run, read by ToolResponse (the loops'
@@ -388,7 +389,7 @@ module Samagotchi
     end
 
     def unreached_group_refusal(call)
-      return if participant_turn?
+      return if participant_turn? && ParticipantMode.of(nil) == :review
 
       registry = tools
       index = registry&.index if registry.respond_to?(:index)

data/lib/samagotchi/toolkit.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "config"
+require_relative "model_match"
 
 module Samagotchi
   # A session's toolkit: which of the registered tools its prompts declare
@@ -118,8 +119,66 @@ module Samagotchi
       Array(groups).map { |group| group.to_s.strip }.reject(&:empty?).uniq.sort.freeze
     end
 
+    # Whether a source group +name+ is one of +selectors+: fnmatch globs in
+    # the guardrails rules' grammar (ModelMatch::GLOB_FLAGS: any case,
+    # extglob), so `groups: [Chrome]` reaches chrome.
     def self.group_matches?(selectors, name)
-      selectors == :all || selectors.any? { |selector| File.fnmatch?(selector, name.to_s) }
+      selectors == :all || selectors.any? { |selector| File.fnmatch?(selector, name.to_s, ModelMatch::GLOB_FLAGS) }
+    end
+
+    # Why +value+ can't be a kit's groups (a group name or glob, or a list
+    # of them), nil when it can (nil too: its base's groups).
+    def self.groups_error(value)
+      return nil if value.nil? || value.is_a?(String)
+      return nil if value.is_a?(Array) && value.all? { |group| group.is_a?(String) || group.is_a?(Symbol) || group.is_a?(Numeric) }
+
+      "groups must be a list of group names or globs"
+    end
+
+    # config.yml's toolkit.kits.NAME line for a +value+ that can't be its
+    # groups (groups_error), nil when it can: the one wording a worker's
+    # warning and a creation's refusal both start with.
+    def self.config_groups_error(name, value)
+      problem = groups_error(value)
+      problem && "toolkit.kits.#{name}: #{problem}"
+    end
+
+    # A new session refused: its toolkit, or a base it builds on, is a
+    # config.yml kit (toolkit.kits) whose groups: isn't a name or a list of
+    # them. A session never starts on a reach other than the one written
+    # (its base's groups: wider or narrower); the message is the one line
+    # every creation surface shows.
+    class Refused < StandardError
+      # @param toolkit [String] the new session's toolkit name
+      # @param problem [String] config_groups_error's line
+      def self.for(toolkit, problem) = new("#{problem}; fix config.yml to start a session on toolkit #{toolkit}")
+    end
+
+    # Raises Refused when +toolkit+ (a new session's: Session.new_session)
+    # names a config kit, or builds on one through its bases, whose
+    # groups: is invalid (config_groups_error). Only config.yml's kits are
+    # followed: a bundle's (chi.toolkit) refuses at its load, and a name
+    # that doesn't resolve stays the worker's warning.
+    # @param config [Hash, nil] toolkit.kits (config.yml's by default)
+    # @return [Toolkit] +toolkit+
+    # @raise [Refused]
+    def self.check_new!(toolkit, config: config_kits)
+      return toolkit unless toolkit && config.is_a?(Hash)
+
+      name = toolkit.name
+      seen = []
+      until seen.include?(name) || name == REVIEW || BUILTIN_KITS.key?(name)
+        seen << name
+        spec = config[name] || config[name.to_sym]
+        break unless spec.is_a?(Hash)
+
+        spec = spec.transform_keys(&:to_s)
+        problem = config_groups_error(name, spec["groups"])
+        raise Refused.for(toolkit.name, problem) if problem
+
+        name = (spec["base"] || FULL).to_s
+      end
+      toolkit
     end
 
     # A named list of declared tools: +tools+ (:all, every built-in; or the
@@ -129,12 +188,15 @@ module Samagotchi
     # system prompt, verbatim (stripped); nil inherits the base's, "" clears
     #   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)
+    #   +description+: optional classifier text; it is not prompt text.
+    Kit = Data.define(:name, :base, :tools, :add, :remove, :source, :prompt, :groups, :description) do
+      def initialize(name:, base: nil, tools: nil, add: [], remove: [], source: "core", prompt: nil, groups: nil,
+                     description: 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,
-              groups: groups.nil? ? nil : Toolkit.group_names(groups))
+              groups: groups.nil? ? nil : Toolkit.group_names(groups),
+              description: description.is_a?(String) ? description.strip.freeze : nil)
       end
     end
 
@@ -151,6 +213,17 @@ module Samagotchi
       "prompt is over #{PROMPT_MAX} characters" if value.strip.length > PROMPT_MAX
     end
 
+    DESCRIPTION_MAX = 300
+
+    # Why +value+ can't describe a kit (text, at most DESCRIPTION_MAX
+    # characters once stripped), nil when it can (nil too: no description).
+    def self.description_error(value)
+      return nil if value.nil?
+      return "description must be text" unless value.is_a?(String)
+
+      "description is over #{DESCRIPTION_MAX} characters" if value.strip.length > DESCRIPTION_MAX
+    end
+
     # The built-ins `lean` declares: the file and shell tools, memories,
     # the task tools (execute's hand-over, turn notes and task_wait's tail
     # name the trio), questions, web_fetch, and context_read (core notes
@@ -295,16 +368,19 @@ module Samagotchi
                       "name your kit something else"
 
     # The keys a config kit entry takes.
-    KIT_KEYS = %w[base add remove prompt groups].freeze
+    KIT_KEYS = %w[base add remove prompt groups description].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:, groups:} map. One with another key
+    #   that isn't a {base:, add:, remove:, prompt:, groups:, description:} 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.
+    # without the prompt, with a line saying why. One whose groups: isn't
+    # a name or a list (config_groups_error) loads reaching no group, with
+    # a line: a session saved on it before the typo (no new one starts on
+    # it: check_new!) never reaches wider than written.
     # @param config [Hash, nil] toolkit.kits
     # @param plugins [Array<Kit>]
     # @param errors [Array<String>] gets a line per kit left out or unknown key
@@ -318,19 +394,28 @@ 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:, groups:}"
+          errors << "toolkit.kits.#{name}: expected {base:, add:, remove:, prompt:, groups:, description:}"
         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:, groups:)"
+                      "(a kit takes base:, add:, remove:, prompt:, groups:, description:)"
           end
           if (problem = prompt_error(spec["prompt"]))
             errors << "toolkit.kits.#{name}: #{problem}; the kit loads without it"
             spec.delete("prompt")
           end
+          if (problem = description_error(spec["description"]))
+            errors << "toolkit.kits.#{name}: #{problem}; the kit loads without it"
+            spec.delete("description")
+          end
+          if (problem = config_groups_error(name, spec["groups"]))
+            errors << "#{problem}; the kit reaches no tool-index group until it is fixed"
+            spec["groups"] = []
+          end
           kits[name] = Kit.new(name: name, base: spec["base"] || FULL, add: spec["add"], remove: spec["remove"],
-                               prompt: spec["prompt"], groups: spec["groups"], source: "config")
+                               prompt: spec["prompt"], groups: spec["groups"], source: "config",
+                               description: spec["description"])
         end
       end
       plugins.each { |kit| kits[kit.name] ||= kit }

data/lib/samagotchi/toolkit_binding.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "log"
+require_relative "memory_paths"
+require_relative "model_overlay"
+require_relative "muted_memories"
 require_relative "toolkit"
+require "yaml"
 
 module Samagotchi
   # An Engine's session toolkit: the kits it resolves against, what the
@@ -39,15 +43,26 @@ module Samagotchi
     # @return [Array<Toolkit::Kit>] the plugins' kits (Plugin::Registries' toolkits:)
     attr_reader :plugin_kits
 
-    # 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
+    # The kits a session's toolkit resolves against: built-ins, config,
+    # plugins, then project and system memory kits. Config and memory kits
+    # are read once per worker, like the plugins': edits take effect when a
+    # new worker reads them.
+    # @param errors [Array<String>] gets a line per invalid or skipped kit
     # @return [Hash{String => Toolkit::Kit}]
     def kits(errors = [])
       @config_kits = Toolkit.config_kits unless defined?(@config_kits)
-      Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
+      memory_kits, memory_errors = memory_kits_for(@session.call)
+      errors.concat(memory_errors)
+      kits = Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
+      memory_kits.each do |kit|
+        if kits.key?(kit.name)
+          errors << "#{MEMORY_KIT_PREFIX}#{kit.name}.md (#{kit.source}): " \
+                    "toolkit name is already defined; skipping this memory kit"
+        else
+          kits[kit.name] = kit
+        end
+      end
+      kits
     end
 
     # The session's toolkit resolved (Toolkit::Resolved): what its next
@@ -98,9 +113,16 @@ module Samagotchi
       return false if session.nil? || !@can_stage.call
 
       toolkit = Toolkit.new(name: name)
-      return true if session.toolkit == toolkit
+      if session.toolkit == toolkit
+        if session.toolkit_origin != "chosen"
+          session.toolkit_origin = "chosen"
+          session.save(state_dir: @state_dir.call)
+        end
+        return true
+      end
 
       session.toolkit = toolkit
+      session.toolkit_origin = "chosen"
       session.save(state_dir: @state_dir.call)
       @notify.call("toolkit: #{name} from the next turn's start", :info, "toolkit", extra: { toolkit: summary })
       true
@@ -143,6 +165,92 @@ module Samagotchi
 
     private
 
+    MEMORY_KIT_PREFIX = "toolkit_"
+    MEMORY_KIT_KEYS = %w[base add remove groups description].freeze
+    MEMORY_KIT_BLOCK = /\A[ \t]*```yaml[ \t]*\r?\n(.*?)\r?\n```[ \t]*\r?\n?\z/m
+
+    # Read once per (folder, muted names): a call before the session exists
+    # (no project folder yet) never hides the project's kits afterwards.
+    def memory_kits_for(session)
+      key = [session&.working_directory, MutedMemories.normalize_list(session&.muted_memory_names)]
+      @memory_kits = { key => load_memory_kits(*key) } unless @memory_kits&.key?(key)
+      @memory_kits[key]
+    end
+
+    def load_memory_kits(cwd, muted)
+      candidates = []
+      errors = []
+      scopes = []
+      scopes << ["project", MemoryPaths.scope_dir(:project, cwd: cwd)] if cwd
+      scopes << ["system", MemoryPaths.scope_dir(:system, cwd: cwd)]
+      scopes.each do |scope, dir|
+        next unless dir && File.directory?(dir)
+
+        Dir.glob(File.join(dir, "#{MEMORY_KIT_PREFIX}*.md")).sort.each do |path|
+          next if ModelOverlay.overlay_file?(path)
+
+          memory_name = File.basename(path, ".md")
+          next if MutedMemories.muted?(memory_name, muted)
+
+          kit = read_memory_kit(path, scope, errors)
+          candidates << kit if kit
+        end
+      end
+      [candidates, errors]
+    end
+
+    def read_memory_kit(path, scope, errors)
+      memory_name = File.basename(path, ".md")
+      name = memory_name.delete_prefix(MEMORY_KIT_PREFIX)
+      return memory_kit_error(errors, memory_name, scope, "toolkit name is empty") if name.empty?
+
+      body = File.read(path, encoding: "UTF-8")
+      match = body.match(MEMORY_KIT_BLOCK)
+      return memory_kit_error(errors, memory_name, scope, "expected one fenced yaml block") unless match
+
+      spec = YAML.safe_load(match[1], permitted_classes: [], aliases: false)
+      return memory_kit_error(errors, memory_name, scope, "yaml block must be a map") unless spec.is_a?(Hash)
+
+      spec = spec.transform_keys(&:to_s)
+      if spec.key?("prompt")
+        return memory_kit_error(errors, memory_name, scope, "prompt: is not supported in toolkit memories")
+      end
+
+      unknown = spec.keys - MEMORY_KIT_KEYS
+      if unknown.any?
+        return memory_kit_error(errors, memory_name, scope, "unknown key #{unknown.first}")
+      end
+
+      description = spec["description"]
+      unless spec.key?("description") && !description.nil?
+        return memory_kit_error(errors, memory_name, scope, "description is required")
+      end
+      if (problem = Toolkit.description_error(description))
+        return memory_kit_error(errors, memory_name, scope, problem)
+      end
+      return memory_kit_error(errors, memory_name, scope, "description is required") if description.strip.empty?
+      if !spec["base"].nil? && (!spec["base"].is_a?(String) || spec["base"].strip.empty?)
+        return memory_kit_error(errors, memory_name, scope, "base must be a toolkit name")
+      end
+      if %w[add remove].any? { |key| spec.key?(key) && !(spec[key].is_a?(Array) && spec[key].all?(String)) }
+        return memory_kit_error(errors, memory_name, scope, "add and remove must be lists of tool names")
+      end
+      if (problem = Toolkit.groups_error(spec["groups"]))
+        return memory_kit_error(errors, memory_name, scope, problem)
+      end
+
+      Toolkit::Kit.new(name: name, base: spec["base"] || Toolkit::FULL, add: spec.fetch("add", []),
+                       remove: spec.fetch("remove", []), groups: spec["groups"], description: description,
+                       source: "memory:#{scope}")
+    rescue Psych::Exception, SystemCallError, EncodingError => e
+      memory_kit_error(errors, memory_name, scope, e.message.lines.first.to_s.strip)
+    end
+
+    def memory_kit_error(errors, memory_name, scope, message)
+      errors << "#{memory_name} (memory:#{scope}): #{message}"
+      nil
+    end
+
     # The toolkit's load warnings, each once per process: a name that
     # didn't resolve, config kits left out.
     def warn_unresolved(session, resolved, errors, on_event)

data/lib/samagotchi/toolkit_command.rb

@@ -43,8 +43,15 @@ module Samagotchi
       session = @engine.session or raise ArgumentError, "no session yet"
       before = @engine.toolkit_explained
       after = @engine.toolkit_explained(changed(before.toolkit, words.split))
-      # Nothing the prompt carries changes (full +delegate on full): not saved.
-      return [listing(before) + "\n(no change to what the next turn declares)", false, nil] if after.prompt_key == before.prompt_key
+      # Nothing the prompt carries changes (full +delegate on full): only
+      # the origin is saved, so a no-op choice still counts as user-selected.
+      if after.prompt_key == before.prompt_key
+        if session.toolkit_origin != "chosen"
+          session.toolkit_origin = "chosen"
+          @save.call(session)
+        end
+        return [listing(before) + "\n(no change to what the next turn declares)", false, nil]
+      end
 
       cost = Toolkit.cache_cost(before.prompt_key, after.prompt_key)
       if confirm && !yes && CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: !cost.nil?)
@@ -53,6 +60,7 @@ module Samagotchi
       end
 
       session.toolkit = after.toolkit
+      session.toolkit_origin = "chosen"
       @save.call(session)
       [[listing(after), "From the next turn's start (a running turn keeps its tools)."].join("\n"), true, nil]
     end
@@ -88,7 +96,11 @@ module Samagotchi
         lines << "  reachable (#{route}): #{explained.reachable.join(", ")}"
         lines << "  removed: #{explained.removed.empty? ? "none" : explained.removed.join(", ")}"
       end
-      lines << "  toolkits: #{@engine.toolkit_kits.keys.join(", ")}; #{USAGE.delete_prefix("usage: ")} changes it"
+      choices = @engine.toolkit_kits.map do |name, kit|
+        source = kit.source.start_with?("memory:") ? " (#{kit.source})" : ""
+        "#{name}#{source}"
+      end
+      lines << "  toolkits: #{choices.join(", ")}; #{USAGE.delete_prefix("usage: ")} changes it"
       lines.join("\n")
     end