samagotchi 0.67.0 → 0.69.0

data/lib/samagotchi/guardrails/targets.rb

@@ -3,6 +3,7 @@
 require_relative "../tools/tool_path"
 require_relative "../tools/memory"
 require_relative "../tool_declarations"
+require_relative "../tools/tool_index"
 require_relative "../log"
 require_relative "model_size"
 require_relative "outside"
@@ -147,14 +148,20 @@ module Samagotchi
 
       # +name+ as the acts_as of +entry+'s calls: nil for none, and for a
       # core tool or a tool another bundle registered (logged); the tool's
-      # own name is no alias either.
+      # own name is no alias either. chi's tool index (call_tool, source
+      # ToolIndex::SOURCE) skips the other-bundle check: its call_targets
+      # only name a tool one of its sources published (or a source-prefixed
+      # name, ToolIndex#claimed), so the registry is the wrong owner test,
+      # and a bundle tool sharing an MCP tool's name would otherwise take
+      # call_tool calls of that tool out of its mcp_* rules.
       def self.acts_as_of(name, entry, registry)
         name = name.to_s.strip
         return nil if name.empty? || name == entry.name
 
         other = registry[name]
         whose = if CORE_TOOLS.include?(name) || other&.core? then "a core tool"
-                elsif other && other.source != entry.source then "bundle #{other.source}'s tool"
+                elsif other && other.source != entry.source && entry.source != Tools::ToolIndex::SOURCE
+                  "bundle #{other.source}'s tool"
                 end
         return name unless whose
 

data/lib/samagotchi/host_config.rb

@@ -10,9 +10,7 @@ require_relative "reasoning_history"
 module Samagotchi
   # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
   # holds them by lowercased name; HostRegistry builds its HostEntry from
-  # one). #to_env_h writes every field in the shape of the
-  # SAMAGOTCHI_HOSTS_JSON override (ConfigFile.hosts_json_for_env), and
-  # .parse reads it back to an equal HostConfig.
+  # one).
   #
   # name: the lowercased entry name; host, port, scheme: where it is (from
   # url: when given); url: the configured url, nil when host/port; transport,
@@ -179,31 +177,5 @@ module Samagotchi
       nil
     end
     private_class_method :invalid
-
-    # The entry as a SAMAGOTCHI_HOSTS_JSON override carries it (string keys,
-    # unset fields left out); .parse(name, to_env_h) gives it back. A url
-    # entry travels as its url (host/port come from it); the API key stays
-    # in the environment.
-    # @return [Hash{String => Object}]
-    def to_env_h
-      location = url ? { "url" => url } : { "host" => host, "port" => port }
-      location.merge("transport" => transport&.to_s, "api" => api&.to_s, "api_key_env" => api_key_env,
-                     "auth" => (AUTH_SCHEMES.key(auth) if auth), "dialect" => dialect,
-                     "profile" => profile, "first_token_timeout" => first_token_timeout,
-                     "vision" => vision, "sampling" => sampling, "thinking" => thinking&.to_s,
-                     "reasoning_history" => reasoning_history&.to_s, "remote" => remote, "window_tokens" => window_tokens,
-                     "steer_cut_after" => steer_cut_after,
-                     "llm_context_strategy" => llm_context_strategy&.map(&:to_s),
-                     "llm_context_apply" => llm_context_apply&.to_s,
-                     "llm_context_budget_tokens" => llm_context_budget_tokens,
-                     "models" => models_config).compact
-    end
-
-    private
-
-    # hosts.<name>.models as written back (HostModel#to_config), nil when none.
-    def models_config
-      models.values.to_h { |m| [m.id, m.to_config] } unless models.nil? || models.empty?
-    end
   end
 end

data/lib/samagotchi/host_model.rb

@@ -103,13 +103,6 @@ module Samagotchi
                          .map { |info| HostModel::Row.new(id: info.id.to_s, configured: false, info: info) }
       end
     end
-
-    # The entry as written back to config (HostConfig#to_env_h): nil for a
-    # bare id.
-    def to_config
-      config = { "price" => price&.to_config, "served" => served }.compact
-      config unless config.empty?
-    end
   end
 
   # A listing row (HostModel.rows): id as the host lists it, else as

data/lib/samagotchi/kernel_loop.rb

@@ -21,6 +21,7 @@ require_relative "steer"
 require_relative "reasoning_history"
 require_relative "thought_stream_splitter"
 require_relative "tools/builtins"
+require_relative "tools/builtin_calls"
 require_relative "muted_memories"
 require_relative "tool_activity"
 require_relative "tool_runner"
@@ -1070,12 +1071,22 @@ module Samagotchi
     #
     # 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)
+    # it exists, and how to reach it (call_tool, when the toolkit reaches
+    # it that way) or that only the user can load it. A call reached
+    # through call_tool (+via+) of a tool the toolkit declares is told to
+    # call it directly: the model's call_tool(tool: "chi/read") with read
+    # declared, or a hook's rewrite (a direct call can't carry via:).
+    def unknown_tool_error(name, layers, via: nil)
       names = @tools.names(layers: layers)
-      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 " \
+      toolkit = @tools.toolkit&.name
+      in_toolkit = " in this session#{" (toolkit #{toolkit})" if toolkit}"
+      if via && @tools.offered(name, layers: layers)
+        "Error: #{name} is declared#{in_toolkit}; call it directly. Available: #{names.join(", ")}"
+      elsif !via && @tools.respond_to?(:indexed) && @tools.indexed(name, layers: layers)
+        "Error: #{name} isn't declared#{in_toolkit}; call it with #{Tools::BuiltinCalls::VIA}(tool: \"chi/#{name}\", args: {…}) " \
+          "(find_tools gives its inputSchema). Available: #{names.join(", ")}"
+      elsif @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
+        "Error: #{name} isn't loaded#{in_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)."
@@ -1085,9 +1096,15 @@ module Samagotchi
     end
 
     def dispatch(call)
-      entry = @tools.offered(call[:name], layers: llm_context_layers)
+      # A built-in reached through call_tool runs only while the toolkit
+      # reaches it that way (Registry#indexed); any other call by its name.
+      entry = if call[:via]
+                @tools.respond_to?(:indexed) ? @tools.indexed(call[:name], layers: llm_context_layers) : nil
+              else
+                @tools.offered(call[:name], layers: llm_context_layers)
+              end
       unless entry
-        result = unknown_tool_error(call[:name], llm_context_layers)
+        result = unknown_tool_error(call[:name], llm_context_layers, via: call[:via])
         return {
           output: result,
           activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)

data/lib/samagotchi/level_setting_command.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "cache_confirm"
+
+module Samagotchi
+  # A command for a session's own level of a setting (/thinking,
+  # /reasoning-history): with no argument, the level the next turn runs at
+  # and where it came from; with a level, sets the session's own (the
+  # setting's unset word unsets it). A change takes effect at the next
+  # turn's start (the REPL and the worker run it between turns), and the
+  # reply says what it costs the prompt cache. A costly change asks first
+  # (CacheConfirm); --yes (or -y) applies it.
+  #
+  # A subclass gives its Spec (#spec): what differs between the settings.
+  class LevelSettingCommand
+    # name: the command; label: the reply's ("thinking: low (session)");
+    # usage: the usage line an unknown word gets;
+    # parse: word → [known?, the session's own level (nil unsets)];
+    # own: engine → the session's own level now;
+    # explained: (engine, own) → SettingExplained, nil when it can't be resolved;
+    # set: (engine, own) → sets the session's own;
+    # cache_cost: (engine, from_level, to_level) → a cost_notes key, nil for none;
+    # cost_notes: {cost => the reply's line};
+    # follows: what the session follows with no own level;
+    # extra_line: engine → one more listing line, nil for none.
+    Spec = Data.define(:name, :label, :usage, :parse, :own, :explained, :set, :cache_cost, :cost_notes, :follows,
+                       :extra_line)
+
+    # @param engine [Engine] the session's (#session, #history? and the spec's readers)
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows the command (--yes anywhere)
+    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
+    #   false applies it at once (chi send, a delegate, a start flag)
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
+    #   whether the level changed, and the confirm it asks for (nothing
+    #   changed then)
+    # @raise [ArgumentError] a word that isn't a level (with the usage)
+    def run(args, confirm: true)
+      word, yes = CacheConfirm.split(args)
+      return [listing(explained), false, nil] if word.empty?
+
+      known, own = spec.parse.call(word)
+      raise ArgumentError, "unknown #{spec.label} level #{word}\n#{spec.usage}" unless known
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = explained
+      ask = confirm && !yes ? ask(before, own, word) : nil
+      return ask if ask
+
+      spec.set.call(@engine, own)
+      @save.call(session)
+      after = explained
+      [[listing(after), *notes(before, after)].join("\n"), true, nil]
+    end
+
+    # The level, where it came from, and what the session sets itself.
+    def listing(explained)
+      return "#{spec.label}: can't be resolved for this model" unless explained
+
+      lines = ["#{spec.label}: #{explained.label}"]
+      lines << "  this session's own: none (follows #{spec.follows})" unless explained.own
+      extra = spec.extra_line&.call(@engine)
+      lines << extra if extra
+      lines.join("\n")
+    end
+
+    private
+
+    def spec = self.class::SPEC
+
+    def explained(own: spec.own.call(@engine)) = spec.explained.call(@engine, own)
+
+    # The reply that asks before a costly change, nil when it needn't.
+    def ask(before, own, word)
+      would = explained(own: own)
+      return nil unless before && would
+
+      cost = spec.cache_cost.call(@engine, before.level, would.level)
+      return nil unless CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: would.level != before.level)
+
+      step = CacheConfirm.confirm(spec.name, word)
+      [[listing(before), "Switching to #{would.level} restarts the prompt cache: #{spec.cost_notes[cost]}", step.text].join("\n"),
+       false, step]
+    end
+
+    def notes(before, after)
+      return [] unless before && after
+      return ["(no change to what the next turn runs under)"] if before.level == after.level
+
+      cost = spec.cache_cost.call(@engine, before.level, after.level)
+      ["From the next turn's start (a running turn keeps its own).", spec.cost_notes[cost]].compact
+    end
+  end
+end

data/lib/samagotchi/llm/errors.rb

@@ -20,7 +20,8 @@ module Samagotchi
     # asking again could help.
     #
     #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted,
-    #                    ConnectionRefused
+    #                    ConnectionRefused, TLSError (a handshake that can't
+    #                    work: certificate, host name, http vs https)
     #   RateLimited      429, with retry_after when the server says
     #   CreditsHeld      402 "… in-flight requests": credit reserved by other
     #                    requests; a RateLimited, retried after 20 s
@@ -271,6 +272,51 @@ module Samagotchi
       def summary = "can't reach host #{host}#{" at #{address}" if address} (connection refused) — is the server running?"
     end
 
+    # A TLS handshake that can't work however often it is tried: a
+    # certificate chi doesn't trust, a certificate for another name, or a
+    # server that doesn't speak TLS there (an https:// base_url on a plain
+    # HTTP port). Not retried. Any other OpenSSL::SSL::SSLError (an
+    # unexpected eof or a reset mid-handshake) is a network blip, retried.
+    class TLSError < ConnectionError
+      # problem => [pattern of the OpenSSL message, what to check]. The
+      # first match wins, so the host name comes before the general
+      # certificate check ("certificate verify failed (hostname mismatch)").
+      PROBLEMS = {
+        hostname: [/hostname mismatch|does not match the server certificate/i,
+                   "the certificate is for another name: check the host's base_url"],
+        certificate: [/certificate verify failed/i,
+                      "is its CA trusted? set SSL_CERT_FILE to a CA bundle that has it"],
+        scheme: [/wrong version number|packet length too long/i,
+                 "the server doesn't answer TLS there: should the host's base_url start with http://?"]
+      }.freeze
+
+      attr_reader :address, :problem, :reason
+
+      # The permanent problem an OpenSSL::SSL::SSLError's +message+ names
+      # (:hostname, :certificate, :scheme), or nil for a transient one.
+      def self.problem_for(message)
+        PROBLEMS.find { |_problem, (pattern, _hint)| pattern.match?(message.to_s) }&.first
+      end
+
+      # The OpenSSL reason without Ruby's "SSL_connect returned=1 errno=0
+      # peeraddr=… state=…: " prefix.
+      def self.reason_for(message)
+        message.to_s[/\bstate=[^:]*:\s*(.+)\z/m, 1] || message.to_s
+      end
+
+      def initialize(host:, problem:, reason:, address: nil, attempts: 1)
+        @address = address
+        @problem = problem
+        @reason = reason
+        super("#{host}: TLS failed#{" at #{address}" if address}: #{reason}", host: host, retryable: false,
+                                                                            attempts: attempts)
+      end
+
+      def summary
+        "can't reach host #{host}#{" at #{address}" if address} over TLS (#{reason}) — #{PROBLEMS.fetch(problem).last}"
+      end
+    end
+
     # A stream that showed nothing (no text, reasoning or tool call) within
     # the host's first-token limit. A queued request can stay open for many
     # minutes on keep-alive comments alone, which reset the read timeout.

data/lib/samagotchi/llm/http.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "openssl"
 require "uri"
 require_relative "../config"
 require_relative "../version"
@@ -31,9 +32,13 @@ module Samagotchi
       # the user, who can try again later.
       MAX_RETRY_AFTER = 60.0
 
+      # Errors that mean the request didn't get through (the probe treats
+      # them as "unreachable"). #retrying retries them, except a refused
+      # connection and a TLS error that can't work (.tls_problem).
       NETWORK_ERRORS = [
-        Timeout::Error, EOFError, SocketError, IO::TimeoutError,
-        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ETIMEDOUT
+        Timeout::Error, EOFError, SocketError, IO::TimeoutError, OpenSSL::SSL::SSLError,
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ENETDOWN,
+        Errno::ETIMEDOUT, Errno::EPIPE, Errno::EADDRNOTAVAIL
       ].freeze
 
       # Requests of these purposes are the ones a turn waits on (or, for the
@@ -77,6 +82,13 @@ module Samagotchi
         NETWORK_ERRORS.any? { |klass| error.is_a?(klass) }
       end
 
+      # The permanent TLS problem +error+ is (TLSError::PROBLEMS: :certificate,
+      # :hostname, :scheme), or nil: not a TLS error, or a transient one
+      # (an unexpected eof or a reset mid-handshake) worth retrying.
+      def self.tls_problem(error)
+        error.is_a?(OpenSSL::SSL::SSLError) ? TLSError.problem_for(error.message) : nil
+      end
+
       # The ProviderError an SSE line carries (llama.cpp's `error:` event, a
       # `data:` line with an `error` object), or nil.
       def self.sse_error(line, host:)
@@ -278,6 +290,12 @@ module Samagotchi
             if e.is_a?(Errno::ECONNREFUSED)
               raise ConnectionRefused.new(host: @label, address: current[:address], attempts: attempts)
             end
+            # Nor is a handshake that can't work (an untrusted certificate,
+            # another name's, a plain HTTP server): it fails the same way.
+            if (problem = self.class.tls_problem(e))
+              raise TLSError.new(host: @label, address: current[:address], problem: problem,
+                                 reason: TLSError.reason_for(e.message), attempts: attempts)
+            end
 
             delay = current[:streamed] ? nil : @retry_policy.delay_for(attempts)
             raise RetryExhausted.new(attempts: attempts, last_error: e, label: @label) if delay.nil?

data/lib/samagotchi/llm_context_stale.rb

@@ -191,11 +191,17 @@ module Samagotchi
         id = entry[:tool_call_id].to_s
         matches = id.empty? ? [] : batch.select { |call_id, _| call_id.to_s == id }
         call = matches.one? ? matches.first.last : nil
+        call &&= Tools::BuiltinCalls.unwrap_saved(call, entry[:content])
         texts = call && refs.size == 1 ? ToolResponse.runs_named(entry[:content], [call[:name]]) : nil
         return texts ? [[refs.first, call, texts.first.text]] : []
       end
 
+      # A call_tool of a built-in ran as it: its run's lead names the
+      # built-in (BuiltinCalls.unwrap_saved).
       calls = batch.map(&:last)
+      calls = calls.zip(ToolResponse.runs(entry[:content], calls.size)).map do |call, run|
+        Tools::BuiltinCalls.unwrap_saved(call, run&.text)
+      end
       texts = ToolResponse.runs_named(entry[:content], calls.map { |call| call[:name] })
       return [] unless texts && texts.size == refs.size
 

data/lib/samagotchi/llm_context_strategy.rb

@@ -211,17 +211,12 @@ module Samagotchi
     def for_session(session, registry: nil)
       return nil if session.nil?
 
-      require_relative "config"
-      require_relative "model_profile"
-      registry ||= begin
-        require_relative "host_registry"
-        HostRegistry.new
-      end
-      name = session.model_name.to_s.strip.empty? ? ModelProfile.required_model_name(nil) : session.model_name
-      target = registry.resolve(name)
-      names = registry.lookup_names(session.model_typed || name, resolved: name, target: target)
+      # Here, not at the top: config.rb requires this file before ConfigFile
+      # exists, and effective_model.rb requires config.rb (via host_registry.rb).
+      require_relative "effective_model"
+      registry ||= HostRegistry.new
       own = session.llm_context
-      explain(target, names: names, **(own&.resolve_args || {})).summary(own)
+      EffectiveModel.of_session(session, registry: registry).llm_context_explained(own&.resolve_args || {})&.summary(own)
     rescue StandardError
       nil
     end

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -24,6 +24,9 @@ module Samagotchi
     #     file: plugin.rb
     #     sha256: sha256:0a1b...
     #   requires_chi: ">= 0.1.28"   # optional — a Gem::Requirement for chi's VERSION
+    #   requires_chi_next: true     # optional, shipped bundles — ignored here:
+    #                          #   `rake release:bump` raises requires_chi to
+    #                          #   the released chi (docs/releasing.md)
     #   needs:                 # optional — outside commands the memories rely on
     #     - command: gh        #   (checked on PATH, never installed; docs/memory.md)
     #       why: reads PRs     #   optional

data/lib/samagotchi/model_price.rb

@@ -15,8 +15,8 @@ module Samagotchi
 
       values = raw.is_a?(Hash) ? raw.transform_keys(&:to_s).slice(*ModelPrice::KEYS) : nil
       valid = values && values.key?("input") && values.key?("output") &&
-              # YAML's .inf and .nan are Floats too: JSON can't carry them
-              # (hosts_json_for_env would drop every host) and NaN poisons the sums.
+              # YAML's .inf and .nan are Floats too: an infinite price
+              # isn't one, and NaN poisons the sums.
               values.values.all? { |v| v.is_a?(Numeric) && v.finite? && !v.negative? }
       unless valid
         warn_once "Warning: #{where}.price needs input and output, each a number >= 0 (USD per 1M tokens); ignored"
@@ -45,8 +45,6 @@ module Samagotchi
       ((uncached * input) + (cached_tokens * cache_read) + (cache_write_tokens * cache_write) +
        (completion_tokens * output)) / 1e6
     end
-
-    def to_config = to_h.transform_keys(&:to_s)
   end
 
   # The keys a price may hold (config validation checks them too).

data/lib/samagotchi/reasoning_history_command.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "cache_confirm"
+require_relative "level_setting_command"
 require_relative "reasoning_history"
 
 module Samagotchi
   # /reasoning-history, the session's own reasoning_history level
-  # (Session#reasoning_history): with no argument, the level the next turn
-  # runs under and where it came from; `/reasoning-history drop|turn|all`
-  # sets the session's own (an explicit turn too), `/reasoning-history
-  # default` unsets it (the session follows SAMAGOTCHI_REASONING_HISTORY,
-  # the model, its host, then turn). A change takes effect at the next
-  # turn's start; a native host ignores the level (its loop keeps the
-  # running turn's reasoning), but the session keeps it for a chat model.
-  # A change that rewrites the earlier replies asks first (CacheConfirm);
-  # --yes (or -y) applies it.
-  class ReasoningHistoryCommand
+  # (Session#reasoning_history): `/reasoning-history drop|turn|all` sets it
+  # (an explicit turn too), `/reasoning-history default` unsets it (the
+  # session follows SAMAGOTCHI_REASONING_HISTORY, the model, its host, then
+  # turn). Resolved on any host: a native one ignores the level (its loop
+  # keeps the running turn's reasoning), but the session keeps it for a
+  # chat model. A change that rewrites the earlier replies asks first. See
+  # LevelSettingCommand.
+  class ReasoningHistoryCommand < LevelSettingCommand
     NAME = "/reasoning-history"
     USAGE = "usage: #{NAME} [#{(ReasoningHistory::LEVELS + [ReasoningHistory::UNSET]).join("|")}]".freeze
     NATIVE_NOTE = "  (ignored on this host: the native loop keeps the running turn's reasoning)"
@@ -24,84 +22,25 @@ module Samagotchi
                "from the first earlier thought."
     }.freeze
 
-    # @param engine [Engine] #reasoning_history_explained,
-    #   #reasoning_history_override(=), #session, #chat_model?,
-    #   #reasoning_history_cache_cost, #history?
-    # @param save [#call] saves the session after a change
-    def initialize(engine:, save:)
-      @engine = engine
-      @save = save
-    end
-
-    # @param args [String] what follows /reasoning-history (--yes anywhere)
-    # @param confirm [Boolean] ask before a costly change (CacheConfirm);
-    #   false applies it at once
-    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
-    #   whether the level changed, and the confirm it asks for (nothing
-    #   changed then)
-    # @raise [ArgumentError] a word that isn't a level (with USAGE)
-    def run(args, confirm: true)
-      word, yes = CacheConfirm.split(args)
-      return [listing(explained), false, nil] if word.empty?
-
-      level = ReasoningHistory.session_level(word)
-      raise ArgumentError, "unknown reasoning history level #{word}\n#{USAGE}" unless level || word == ReasoningHistory::UNSET
-
-      session = @engine.session or raise ArgumentError, "no session yet"
-      before = explained
-      ask = confirm && !yes ? ask(before, level, word) : nil
-      return ask if ask
-
-      @engine.reasoning_history_override = level
-      @save.call(session)
-      after = explained
-      [[listing(after), *notes(before, after)].join("\n"), true, nil]
-    end
-
-    # The level, where it came from, and what the session sets itself.
-    def listing(explained)
-      return "reasoning history: can't be resolved for this model" unless explained
-
-      lines = ["reasoning history: #{explained.label}"]
-      unless explained.own
-        lines << "  this session's own: none (follows #{ReasoningHistory::ENV_NAME}, the model, its host, then turn)"
-      end
-      lines << NATIVE_NOTE unless chat?
-      lines.join("\n")
-    end
-
-    private
-
-    # Resolved on any host: a native one ignores it, but /reasoning-history
-    # still shows what a chat model would get.
-    def explained(own: @engine.reasoning_history_override)
-      @engine.reasoning_history_explained(native: true, own: own)
-    end
-
-    # The reply that asks before a costly change, nil when it needn't.
-    def ask(before, own, word)
-      would = explained(own: own)
-      return nil unless before && would
-
-      cost = @engine.reasoning_history_cache_cost(before.level, would.level)
-      return nil unless CacheConfirm.needed?(cost: cost, history: @engine.history?, changed: would.level != before.level)
-
-      step = CacheConfirm.confirm(NAME, word)
-      [[listing(before), "Switching to #{would.level} restarts the prompt cache: #{COST_NOTES[cost]}", step.text].join("\n"), false, step]
-    end
-
-    def chat?
-      @engine.chat_model?
-    rescue StandardError
-      false
-    end
-
-    def notes(before, after)
-      return [] unless before && after
-      return ["(no change to what the next turn runs under)"] if before.level == after.level
-
-      cost = @engine.reasoning_history_cache_cost(before.level, after.level)
-      ["From the next turn's start (a running turn keeps its own).", COST_NOTES[cost]].compact
-    end
+    SPEC = Spec.new(
+      name: NAME, label: "reasoning history", usage: USAGE, cost_notes: COST_NOTES,
+      parse: lambda { |word|
+        level = ReasoningHistory.session_level(word)
+        [!level.nil? || word == ReasoningHistory::UNSET, level]
+      },
+      own: lambda(&:reasoning_history_override),
+      explained: ->(engine, own) { engine.reasoning_history_explained(native: true, own: own) },
+      set: ->(engine, own) { engine.reasoning_history_override = own },
+      cache_cost: ->(engine, from, to) { engine.reasoning_history_cache_cost(from, to) },
+      follows: "#{ReasoningHistory::ENV_NAME}, the model, its host, then turn",
+      extra_line: lambda { |engine|
+        chat = begin
+          engine.chat_model?
+        rescue StandardError
+          false
+        end
+        chat ? nil : NATIVE_NOTE
+      }
+    )
   end
 end

data/lib/samagotchi/session.rb

@@ -259,6 +259,8 @@ module Samagotchi
       self.interrupted_turn = interrupted_turn
       @turn_checkpoint = nil
       @archived = false
+      # #save's lock: one snapshot-and-write at a time (see #save).
+      @save_lock = Mutex.new
     end
 
     # A `delegate` child: its turns report to its parent (ChildReports). A
@@ -513,18 +515,30 @@ module Samagotchi
     end
 
     # Persist the session atomically. Updates +updated_at+ in place.
+    #
+    # One save at a time per Session: a worker saves its session from the
+    # loop/turn thread (TurnCheckpoint, Engine's turn end, WorkerInbound),
+    # from Bridge threads (QuestionDesk, commands run mid-turn) and from a
+    # signal's thread. AtomicFile keeps each write whole, but two
+    # unserialized saves could rename an older snapshot over a newer one (a
+    # lost update); under the lock the last rename is the latest snapshot.
+    # Never call it from a trap handler (Mutex#lock raises ThreadError
+    # there; WorkerSignals saves on a thread of its own) or from inside a
+    # save (the lock isn't re-entrant).
     def save(state_dir: self.class.default_state_dir)
-      @updated_at = Time.now.iso8601(3)
-      # Persist with current metadata version so new flag is written
-      @metadata_version = METADATA_VERSION
-      FileUtils.mkdir_p(state_dir)
+      @save_lock.synchronize do
+        @updated_at = Time.now.iso8601(3)
+        # Persist with current metadata version so new flag is written
+        @metadata_version = METADATA_VERSION
+        FileUtils.mkdir_p(state_dir)
 
-      path = self.class.session_file(@id, state_dir: state_dir)
+        path = self.class.session_file(@id, state_dir: state_dir)
 
-      # Auto-compute first_preview if not yet cached and messages contain a user entry.
-      compute_first_preview!
+        # Auto-compute first_preview if not yet cached and messages contain a user entry.
+        compute_first_preview!
 
-      AtomicFile.write(path, JSON.pretty_generate(to_h) + "\n")
+        AtomicFile.write(path, JSON.pretty_generate(to_h) + "\n")
+      end
       self
     end
 

data/lib/samagotchi/session_metrics.rb

@@ -852,6 +852,9 @@ module Samagotchi
 
         called_as = event.dig(:activity, :called_as)
         active[:called_as] = called_as.to_s if called_as
+        # Reached through call_tool: the reloaded row says so (not an alias).
+        via = event.dig(:activity, :via)
+        active[:via] = via.to_s if via
         # A grep that found nothing (ok): the reloaded web row says "no match".
         active[:no_match] = true if event.dig(:activity, :no_match)
         finish_tool_record(active, status.empty? ? "ok" : status, waited_ms: event[:waited_ms].to_i)
@@ -861,7 +864,7 @@ module Samagotchi
     # Caller holds the mutex.
     def finish_tool_record(active, status, waited_ms: 0)
       record = active.slice(
-        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :no_match, :started_at
+        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :started_at
       ).merge(
         status: status,
         completed_at: now.iso8601(3),