samagotchi 0.131.0 → 0.132.0

data/lib/samagotchi/llm_context_command.rb

@@ -4,6 +4,7 @@ require_relative "llm_context_override"
 require_relative "llm_context_strategy"
 require_relative "llm_context_edit"
 require_relative "llm_context_stale"
+require_relative "cache_confirm"
 
 module Samagotchi
   # /llm-context, the session's own LLM context values
@@ -18,7 +19,9 @@ module Samagotchi
   # system prompt (a full cache break); stale turned on stages the reads
   # already superseded as one batch under the apply rule; a layer turned
   # off sends its stubs whole again (the originals stay in the session, so
-  # turning it back on brings them back).
+  # turning it back on brings them back). The two that restart the prompt
+  # cache (forget on or off, stubs sent whole again) ask first
+  # (CacheConfirm, #cache_cost); --yes (or -y) applies them.
   class LLMContextCommand
     NAME = LLMContextOverride::COMMAND
     USAGE = "usage: #{NAME} [strategy <none|stale,forget|default>] [apply <payoff|next_request|turn_end|default>] " \
@@ -33,20 +36,49 @@ module Samagotchi
       @save = save
     end
 
-    # @param args [String] what follows /llm-context
-    # @return [Array(String, Boolean)] the reply and whether the values changed
+    # @param args [String] what follows /llm-context (--yes anywhere)
+    # @param confirm [Boolean] ask before a change that restarts the prompt
+    #   cache (CacheConfirm, #cache_cost); false applies it at once (chi
+    #   send, a delegate, a start flag)
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the reply,
+    #   whether the values changed, and the confirm it asks for (nothing
+    #   changed then)
     # @raise [ArgumentError] a line that isn't one (its message and USAGE)
-    def run(args)
-      args = args.to_s.strip
-      return [listing(@engine.llm_context_explained), false] if args.empty?
+    def run(args, confirm: true)
+      # Before #words: it refuses --yes, and "reset --yes" isn't RESET.
+      args, yes = CacheConfirm.split(args, downcase: false)
+      return [listing(@engine.llm_context_explained), false, nil] if args.empty?
 
       session = @engine.session or raise ArgumentError, "no session yet"
       before = @engine.llm_context_explained
       updated = args.casecmp?(RESET) ? LLMContextOverride.new : LLMContextOverride.update(@engine.llm_context_override, words(args))
+      ask = confirm && !yes ? ask(session, before, updated, args) : nil
+      return ask if ask
+
       @engine.llm_context_override = updated
       @save.call(session)
       after = @engine.llm_context_explained
-      [[listing(after), *notes(session, before&.resolved, after&.resolved)].join("\n"), true]
+      [[listing(after), *notes(session, before&.resolved, after&.resolved)].join("\n"), true, nil]
+    end
+
+    # What a change from +before+ to +after+ (Resolved) costs the prompt
+    # cache, nil for nothing worth asking about: forget on or off changes
+    # the tool list and the system prompt (:full); a layer turned off while
+    # it has applied stubs sends them whole again (:history). Stale turned
+    # on only stages a batch under the apply rule (its break comes later,
+    # as designed), and the apply rule and budget only decide when a break
+    # comes: a switch to next_request with staged edits pending applies
+    # them at the next request, a break the old rule makes by the end of
+    # the next turn anyway.
+    # @return [Symbol, nil]
+    def cache_cost(session, before, after)
+      return nil unless before && after
+
+      was = before.active_layers
+      now = after.active_layers
+      return :full if was.include?(:forget) != now.include?(:forget)
+
+      :history if (was - now).any? { |layer| applied_count(session.messages, layer).positive? }
     end
 
     # The values, where each came from, and what the session sets itself.
@@ -66,6 +98,20 @@ module Samagotchi
 
     private
 
+    # The reply that asks before a costly change (CacheConfirm), nil when
+    # it needn't.
+    def ask(session, before, updated, args)
+      would = @engine.llm_context_explained(own: updated)
+      was = before&.resolved
+      now = would&.resolved
+      cost = cache_cost(session, was, now)
+      step = CacheConfirm.ask(line: "#{NAME} #{args}", cost: cost, changed: !cost.nil?, engine: @engine)
+      return nil unless step
+
+      costs = notes(session, was, now).drop(1).reject { |note| note.start_with?("stale:") }
+      [[listing(before), "This change restarts the prompt cache:", *costs, step.text].join("\n"), false, step]
+    end
+
     # "strategy stale stale forget apply turn_end budget 64k" as fields
     # and their words; a strategy takes the words up to the next field.
     def words(args)

data/lib/samagotchi/llm_context_override.rb

@@ -55,7 +55,8 @@ module Samagotchi
     COMMAND_WORDS = { strategy: "strategy", apply: "apply", budget_tokens: "budget" }.freeze
 
     # The /llm-context line that sets +words+ (field => value as typed,
-    # checked by .update first): what a flag on an existing session runs.
+    # checked by .update first): what a flag on an existing session runs,
+    # with --yes (typing the flag is the choice: no confirm step).
     # @return [String]
     def self.command_line(words)
       parts = words.map do |field, word|
@@ -63,7 +64,7 @@ module Samagotchi
         word = parse_strategy(word).then { |layers| layers.empty? ? "none" : layers.join(",") } if field == :strategy && !word.casecmp?(DEFAULT_WORD)
         "#{COMMAND_WORDS.fetch(field)} #{word}"
       end
-      [COMMAND, *parts].join(" ")
+      [COMMAND, *parts, "--yes"].join(" ")
     end
 
     # A session file's "llm_context" (or an override already): nil when

data/lib/samagotchi/plugin/api.rb

@@ -7,6 +7,7 @@ require_relative "../commands/registry"
 require_relative "service"
 require_relative "tool_result"
 require_relative "tool_spec"
+require_relative "prompt_sections"
 
 module Samagotchi
   module Plugin
@@ -45,7 +46,9 @@ module Samagotchi
         "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0",
         "ctx.usage" => "0.100.0", "ctx.sessions.stop" => "0.34.0", "ctx.turn_author" => "0.106.0",
         "ctx.sessions.review" => "0.107.0", "ctx.sessions.send(delivery:)" => "0.64.0",
-        "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0"
+        "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0",
+        "chi.prompt_section" => "0.132.0", "chi.prompt_changed" => "0.132.0", "ctx.cache_confirm" => "0.132.0",
+        "ctx.model_names" => "0.132.0"
       }.freeze
 
       # @param bundle [String]
@@ -65,6 +68,7 @@ module Samagotchi
         @services = []
         @inits = []
         @toolkits = []
+        @prompt_sections = []
         @peer_sources = []
         @tool_source = nil
         @committed = false
@@ -279,6 +283,42 @@ module Samagotchi
         nil
       end
 
+      # Text this session's system prompt carries (docs/plugins.md, Prompt
+      # sections): the block gets the Context and returns a String (at most
+      # PromptSections::MAX characters) or nil for none. It runs when the
+      # prompt is built (a session's first turn, after /model or a
+      # #prompt_changed!), never per request, on whatever thread builds:
+      # keep it quick (no I/O beyond reading a small file) and give the same
+      # text for the same inputs. A raise, a non-String or text over the
+      # limit keeps the section's last good text (one warn).
+      # @param name [String] a-z, 0-9, _ and -; unique in the bundle
+      def prompt_section(name, &block)
+        raise ArgumentError, "prompt_section #{name.inspect} needs a block" unless block
+
+        name = name.to_s
+        unless name.match?(PromptSections::NAME)
+          raise ArgumentError, "prompt section name #{name.inspect} must be a-z, 0-9, _ and - (at most 32)"
+        end
+        raise ArgumentError, "this chi has no prompt sections (plugins: false)" unless @registries.prompt_sections
+        if @prompt_sections.any? { |item| item[:name] == name } || @registries.prompt_sections.registered?(@bundle, name)
+          raise ArgumentError, "prompt section #{name} is registered twice"
+        end
+
+        @prompt_sections << { name: name, block: block }
+        nil
+      end
+
+      # Say this session's prompt sections would now give other text (a
+      # setting the plugin keeps changed): the system prompt is built again
+      # at its next build (the next turn's start; a running turn keeps the
+      # prompt it started with). That restarts the model server's prompt
+      # cache, so a command that changes a section asks first
+      # (Context#cache_confirm) and calls this only once it applies.
+      def prompt_changed!
+        @registries.prompt_changed&.call
+        nil
+      end
+
       # Publish tools into the session's tool index instead of declaring
       # them one by one (docs/plugins.md, "Publishing tools to the index"):
       # the model searches them with find_tools and calls one with
@@ -393,6 +433,9 @@ module Samagotchi
           end
         end
         @registries.toolkits&.concat(@toolkits)
+        @prompt_sections.each do |item|
+          @registries.prompt_sections.add(bundle: @bundle, name: item[:name], context: context, &item[:block])
+        end
         @registries.tool_index.add(@tool_source) if @tool_source
         @peer_sources.each { |item| @registries.peer_sources.declare(item[:name], label: item[:label], bundle: @bundle) }
         @committed = true
@@ -401,6 +444,7 @@ module Samagotchi
       # @return [Hash] how many of each it registered (for the log)
       def counts = { commands: @commands.size, annotations: @annotations.size, tools: @tools.size, hooks: @hooks.size,
                      services: @services.size, inits: @inits.size, toolkits: @toolkits.size,
+                     prompt_sections: @prompt_sections.size,
                      tool_sources: @tool_source ? 1 : 0, peer_sources: @peer_sources.size }
 
       # Each annotation's command is one #command staged.

data/lib/samagotchi/plugin/context.rb

@@ -8,6 +8,7 @@ require_relative "../session_metrics/usage"
 require_relative "../guardrails/context"
 require_relative "../hook_question"
 require_relative "../idle_client"
+require_relative "../cache_confirm"
 require_relative "service"
 require_relative "side_question"
 
@@ -58,10 +59,15 @@ module Samagotchi
     # plugin handler: +handler+) until the turn has ended.
     # +cost+ returns the session's spend now (SessionMetrics::Cost),
     # +usage+ its work now (SessionMetrics::Usage).
+    # +cache_confirm+ takes (line, changed) and returns a
+    # CacheConfirm::Confirm when the change must ask first (CacheConfirm.ask
+    # with cost :full), else nil. +model_names+ returns the names the
+    # session's model is looked up under (EffectiveModel#names).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
-                      :cancel_controller, :cost, :usage, :turn_author, keyword_init: true)
+                      :cancel_controller, :cost, :usage, :turn_author, :cache_confirm, :model_names,
+                      keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -164,6 +170,14 @@ module Samagotchi
       #   current_model_only names it
       def model_key = @host.model_key&.call
 
+      # The names the session's model is looked up under now, as chi's own
+      # per-model config is (models: maps, ConfigFile.model_setting): as
+      # typed (an alias), the alias's target, the resolved ref ("host:id"),
+      # without the host, the bare id the host serves; deduped, first the
+      # most specific. Compare them downcased, first hit, as chi does.
+      # @return [Array<String>] frozen; [] when the model doesn't resolve
+      def model_names = Array(@host.model_names&.call).map(&:to_s).freeze
+
       # @return [SessionMetrics::Cost] the session's spend so far, read now:
       #   #total, #reported, #estimated, #side (Float USD) and #known?
       #   (docs/plugins.md); zero and known with no session
@@ -215,6 +229,25 @@ module Samagotchi
         Array(@host.load_tools&.call(names.map(&:to_s), @bundle))
       end
 
+      # Whether a change the plugin's command is about to make (its prompt
+      # section's text: chi.prompt_changed!) must ask first. nil: apply it
+      # now (nothing changes, no model reply yet, a sender no one answers
+      # for: chi send, a delegate, chi -p, the line had --yes, or not
+      # inside a command). Else a CacheConfirm::Confirm: change nothing and
+      # return [text, confirm] from the command, so the TUI prefills the
+      # line and the web shows Apply (it sends +line+ with --yes). The cost
+      # is a full re-read (the section is in the system prompt's stable
+      # part); the text says how big and, on api: anthropic, that preserved
+      # thinking is dropped.
+      # @param line [String] the command line that applies it, without --yes
+      # @param changed [Boolean] whether the section's text would change
+      # @return [CacheConfirm::Confirm, nil]
+      def cache_confirm(line, changed:)
+        return nil unless CacheConfirm.asking?
+
+        @host.cache_confirm&.call(line.to_s, changed ? true : false)
+      end
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/plugin/loader.rb

@@ -20,9 +20,12 @@ module Samagotchi
     # +init+ adds a chi.init task (Engine#add_init_task); +toolkits+ is the
     # Engine's list of the plugins' toolkits (chi.toolkit: Toolkit::Kit);
     # +tool_index+ the Engine's Tools::ToolIndex (chi.tool_source);
-    # +peer_sources+ the Engine's PeerSources (chi.peer_source).
+    # +peer_sources+ the Engine's PeerSources (chi.peer_source);
+    # +prompt_sections+ the Engine's PromptSections (chi.prompt_section),
+    # +prompt_changed+ rebuilds its system prompts (chi.prompt_changed!).
     Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
-                            :toolkits, :tool_index, :peer_sources, keyword_init: true)
+                            :toolkits, :tool_index, :peer_sources, :prompt_sections, :prompt_changed,
+                            keyword_init: true)
 
     # Loads installed bundles' plugins (manifest plugin: {file:, sha256:})
     # into an Engine's registries (docs/plugins.md).

data/lib/samagotchi/plugin/prompt_sections.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../log"
+require_relative "../toolkit"
+
+module Samagotchi
+  module Plugin
+    # The system-prompt text plugins add (chi.prompt_section): one per
+    # (bundle, name), each a block given the plugin's Context that returns
+    # a String or nil (no section). SystemPrompt runs them inside a build
+    # only (lazy, once per build key until a reset), never per request, on
+    # whatever thread builds: a block must be quick and thread-safe.
+    #
+    # Prompt-cache contract (docs/internals/prompt-caching.md): sections go
+    # sorted by (bundle, name), so the text is the same for the same
+    # inputs. A block that raises, returns something other than a String
+    # or nil, or text over MAX characters keeps the section's last good
+    # text for this session (a skip on a transient error would break the
+    # cache twice), with one warn; with no good text yet the section is
+    # left out.
+    class PromptSections
+      # As a kit prompt's (Toolkit::PROMPT_MAX): a cached prefix, not a document.
+      MAX = Toolkit::PROMPT_MAX
+      NAME = /\A[a-z][a-z0-9_-]{0,31}\z/
+
+      Section = Data.define(:bundle, :name, :block, :context)
+
+      # A section as one build holds it.
+      Built = Data.define(:bundle, :name, :text) do
+        # "From <bundle> (<name>):\n<text>", as the prompt has it.
+        def prompt_text = "From #{bundle} (#{name}):\n#{text}"
+
+        # /stats' record (Engine#stats_snapshot's prompt_sections).
+        def to_stats = { bundle: bundle, name: name }
+      end
+
+      def initialize
+        @sections = []
+        @mutex = Mutex.new
+        # [session id, bundle, name] => the last good text (nil: none)
+        @last_good = {}
+        @warned = Set.new
+      end
+
+      # @raise [ArgumentError] a (bundle, name) already added
+      def add(bundle:, name:, context:, &block)
+        @mutex.synchronize do
+          if @sections.any? { |section| section.bundle == bundle && section.name == name }
+            raise ArgumentError, "prompt section #{name} is registered twice (bundle #{bundle})"
+          end
+
+          @sections << Section.new(bundle: bundle.to_s, name: name.to_s, block: block, context: context)
+          @sections.sort_by! { |section| [section.bundle, section.name] }
+        end
+        nil
+      end
+
+      # @return [Boolean]
+      def any? = @mutex.synchronize { @sections.any? }
+
+      # Whether +bundle+ already has a section +name+.
+      def registered?(bundle, name)
+        @mutex.synchronize { @sections.any? { |section| section.bundle == bundle.to_s && section.name == name.to_s } }
+      end
+
+      # Run every block for +session_id+ and keep what they gave.
+      # @param session_id [String, nil] whose last good text a failure keeps
+      # @return [Array<Built>] in prompt order, the sections with text
+      def render(session_id)
+        sections = @mutex.synchronize { @sections.dup }
+        sections.filter_map do |section|
+          text = evaluate(section, session_id)
+          Built.new(bundle: section.bundle, name: section.name, text: text) if text
+        end
+      end
+
+      # The prompt text of +built+ (#render), nil without any.
+      # @param built [Array<Built>]
+      # @return [String, nil]
+      def self.text(built)
+        built.empty? ? nil : built.map(&:prompt_text).join("\n\n")
+      end
+
+      private
+
+      def evaluate(section, session_id)
+        key = [session_id, section.bundle, section.name]
+        value = section.block.call(section.context)
+        problem = problem_of(value)
+        if problem
+          keep_last_good(section, key, problem)
+        else
+          text = value.nil? ? nil : value.strip.freeze
+          text = nil if text && text.empty?
+          @mutex.synchronize { @last_good[key] = text }
+          text
+        end
+      rescue StandardError => e
+        keep_last_good(section, key, "#{e.class}: #{e.message}")
+      end
+
+      def problem_of(value)
+        return nil if value.nil?
+        return "returned #{value.class}, not a String or nil" unless value.is_a?(String)
+
+        "is over #{MAX} characters" if value.strip.length > MAX
+      end
+
+      # One warn per section, session and problem; the last good text, or nil.
+      def keep_last_good(section, key, problem)
+        kept = @mutex.synchronize do
+          first = @warned.add?([*key, problem])
+          [@last_good[key], first]
+        end
+        text, first = kept
+        if first
+          Log.warn(:plugins, "prompt_section_failed", bundle: section.bundle, section: section.name,
+                                                      error: problem.to_s[0, 200], kept: !text.nil?)
+        end
+        text
+      end
+    end
+  end
+end

data/lib/samagotchi/run_options.rb

@@ -210,6 +210,7 @@ module Samagotchi
                  chi toolkit report [--days N]   grade toolkit suggestions against the tools sessions used
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
+                 chi home [set [--ruby PATH] | doctor]   the Ruby every chi launch boots
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME
                  chi --remote NAME <send|answer|note|context|sessions|share|review> …   those commands on that machine (or CHI_REMOTE=NAME)
                  chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]   a session on that machine, in this terminal

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit remote].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit remote home].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists

data/lib/samagotchi/session_commands.rb

@@ -5,6 +5,7 @@ require_relative "model_profile"
 require_relative "served_model"
 require_relative "prompt_note"
 require_relative "turn_flow"
+require_relative "cache_confirm"
 require_relative "tools/execute"
 require_relative "tools/builtins"
 require_relative "tools/context_read"
@@ -61,7 +62,7 @@ module Samagotchi
 
     # Commands that may ask before a change that restarts the prompt cache
     # (CacheConfirm): #run passes them its confirm flag.
-    CONFIRMING = %i[thinking reasoning_history toolkit].freeze
+    CONFIRMING = %i[model llm_context 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
@@ -302,7 +303,7 @@ module Samagotchi
       text = line.to_s.strip
       entry = @registry.lookup(text)
       return nil unless entry&.handler
-      return run_bundle_command(entry, text) unless entry.source == "core"
+      return run_bundle_command(entry, text, confirm: confirm) unless entry.source == "core"
 
       # Only commands that may ask take the flag.
       return send(entry.id, text, confirm: confirm) if CONFIRMING.include?(entry.id)
@@ -355,16 +356,32 @@ module Samagotchi
     # The resolved ref (what the session stores and --alias/--default write).
     def model_name = @engine.effective_model_ref
 
-    # A bundle plugin's command: its handler gets the text after the name;
-    # what it returns is the output (nil: nothing to show), and a raise is
-    # an error result.
-    def run_bundle_command(entry, text)
-      output = entry.handler.call(text.delete_prefix(entry.name).strip)
-      reply(output.nil? ? nil : output.to_s)
+    # A bundle plugin's command: its handler gets the text after the name
+    # (--yes kept); what it returns is the output (nil: nothing to show),
+    # or [output, CacheConfirm::Confirm or nil] for a change that asks
+    # first (ctx.cache_confirm), and a raise is an error result. The
+    # sender's +confirm+ (false once the line has --yes) reaches
+    # ctx.cache_confirm through the thread (CacheConfirm.asking).
+    def run_bundle_command(entry, text, confirm: false)
+      args = text.delete_prefix(entry.name).strip
+      _, yes = CacheConfirm.split(args)
+      output, ask = bundle_reply(CacheConfirm.asking(confirm && !yes) { entry.handler.call(args) })
+      reply(output, confirm: ask)
     rescue StandardError => e
       reply("#{entry.name}: #{e.class}: #{e.message}", status: :error)
     end
 
+    # A plugin command's return value as [output, confirm]: a String (or
+    # anything, shown as text) or nil, or [text, Confirm/nil].
+    def bundle_reply(value)
+      if value.is_a?(Array) && value.size == 2 && (value[1].nil? || value[1].is_a?(CacheConfirm::Confirm))
+        text, ask = value
+        return [text.nil? ? nil : text.to_s, ask]
+      end
+
+      [value.nil? ? nil : value.to_s, nil]
+    end
+
     def help_group(entry)
       return 2 if entry.local
 
@@ -583,13 +600,13 @@ module Samagotchi
 
     # /llm-context (LLMContextCommand); :llm_context in changed when it set
     # the session's values.
-    def llm_context(text)
-      output, changed = LLMContextCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
-                                         .run(text.delete_prefix(LLM_CONTEXT_COMMAND))
+    def llm_context(text, confirm: true)
+      output, changed, ask = LLMContextCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
+                                              .run(text.delete_prefix(LLM_CONTEXT_COMMAND), confirm: confirm)
       # What the model has of each item is the next turn's strategy's: the
       # working set goes out again (sent only when it differs).
       @engine.announce_working_set if changed
-      reply(output, changed: changed ? [:llm_context] : [])
+      reply(output, changed: changed ? [:llm_context] : [], confirm: ask)
     rescue ArgumentError => e
       reply(e.message, status: :error)
     end
@@ -672,16 +689,23 @@ module Samagotchi
       @save.call(session)
     end
 
-    def model(text)
-      output, switched = model_command(text)
-      reply(output, changed: switched ? [:model] : [])
+    # /model; a switch to another model asks first (CacheConfirm, cost
+    # :full: the new model has no cache of the conversation), --yes applies.
+    def model(text, confirm: true)
+      suffix, yes = CacheConfirm.split(text.delete_prefix(MODEL_COMMAND), downcase: false)
+      output, switched, ask = model_command("#{MODEL_COMMAND} #{suffix}", confirm: confirm && !yes)
+      reply(output, changed: switched ? [:model] : [], confirm: ask)
     rescue ModelProfile::MissingModel => e
       # A model qualified with an unknown host: nothing switched.
       reply(e.message, status: :error)
     end
 
-    # @return [Array(String, Boolean)] the message, and whether the model changed
-    def model_command(input)
+    # @param input [String] the /model line, --yes taken out
+    # @param confirm [Boolean] a switch to another model asks first
+    # @return [Array(String, Boolean, CacheConfirm::Confirm|nil)] the message,
+    #   whether the model changed, and the confirm it asks for (nothing
+    #   changed then)
+    def model_command(input, confirm: false)
       suffix = input.delete_prefix(MODEL_COMMAND).strip
       if suffix.empty?
         return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{steer_cut_after_note}#{thinking_note}#{reasoning_history_note}#{notes_note}", false] if @default_model.nil? || model_name == @engine.model_ref_for(@default_model)
@@ -735,6 +759,9 @@ module Samagotchi
         invalid = ConfigFile.model_alias_error(alias_name, arg)
         return ["invalid alias: #{invalid}", false] if invalid
 
+        ask = confirm && model_ask(arg, input)
+        return ask if ask
+
         switch_model(arg, persist_default: persist_default)
 
         begin
@@ -756,10 +783,16 @@ module Samagotchi
           return ["--default cannot be combined with clear/default/none/off", false] if persist_default
           raise ModelProfile::MissingModel, "no default model is configured (set default.model in config.yml, or /model <name> --default)" if @default_model.nil?
 
+          ask = confirm && model_ask(@default_model, input)
+          return ask if ask
+
           switch_model(@default_model)
           return ["runtime model reset to #{model_name}#{model_note}#{thinking_note}#{reasoning_history_note}#{notes_note}", true]
         end
 
+        ask = confirm && model_ask(arg, input)
+        return ask if ask
+
         switch_model(arg, persist_default: persist_default)
         if persist_default
           ["runtime model set to #{model_name}#{model_note} and default updated#{thinking_note}#{reasoning_history_note}#{notes_note}", true]
@@ -769,6 +802,20 @@ module Samagotchi
       end
     end
 
+    # The reply that asks before switching to +name+ (CacheConfirm), nil
+    # when it needn't: the name is checked first (a typo errors at once,
+    # MissingModel), and its resolved ref against the current one (the same
+    # model costs nothing; any other restarts the whole cache).
+    # @param line [String] the /model line as typed (its flags too), --yes taken out
+    def model_ask(name, line)
+      ref = @engine.model_switch_ref(name)
+      step = CacheConfirm.ask(line: line, cost: :full, changed: ref != model_name, engine: @engine)
+      return nil unless step
+
+      ["runtime model: #{model_name}\nSwitching to #{ref} restarts the prompt cache: the new model has no cache of " \
+       "this conversation.\n#{step.text}", false, step]
+    end
+
     # Engine owns the switch (alias resolution, profile, kernel, client and
     # the optional default persist); the session keeps the new model.
     def switch_model(name, persist_default: false)

data/lib/samagotchi/session_manager.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require "securerandom"
 require "rbconfig"
+require_relative "chi_home"
 require_relative "child_env"
 require_relative "client_id"
 require_relative "analytics_file"
@@ -1252,16 +1253,50 @@ module Samagotchi
     # as it is read, so an rspec run by the worker's execute never forks.
     WORKER_DETACH_ENV = "SAMAGOTCHI_WORKER_DETACH"
 
-    def self.worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec)
+    # The boot string's rescue under a chi home: one line in the spawner's
+    # log file (SAMAGOTCHI_LOG_FILE, set by spawn_options), LogLine's shape,
+    # then exit. Single-quoted: the #{} run in the worker. SID is replaced.
+    # rubocop:disable-next Lint/InterpolationCheck -- the worker interpolates these, not this process
+    HOME_BOOT_FAILED = 'rescue ScriptError, StandardError => e; f = ENV["SAMAGOTCHI_LOG_FILE"].to_s; begin; ' \
+                       'File.open(f, "a") { |io| io.puts(Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ") + ' \
+                       '" ERROR worker pid=#{Process.pid} sid=SID boot_failed ruby=#{RbConfig.ruby.inspect} error=" + ' \
+                       "e.message.lines.first.to_s.strip.inspect) } unless f.empty?; rescue SystemCallError; end; exit 1"
+
+    def self.worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec,
+                            home: ChiHome.current(gem_spec: gem_spec))
       boot = "require 'samagotchi/session_manager'; " \
              "Samagotchi::SessionManager.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})"
       return [RbConfig.ruby, "-I", File.expand_path("..", __dir__), "-e", boot] unless gem_spec
+      return home_worker_command(session_id, state_dir: state_dir, gem_spec: gem_spec, home: home) if home
 
       activate = "begin; gem 'samagotchi', '>= 0.a'; rescue LoadError => e; " \
                  "ENV['#{BOOT_FALLBACK_ENV}'] = e.message; gem 'samagotchi', '= #{gem_spec.version}'; end"
       [RbConfig.ruby, "-e", "#{activate}; #{boot}"]
     end
 
+    # With a chi home (ChiHome.current, docs/architecture.md "How chi
+    # launches itself"): the home's ruby, `Gem.paths` set to its gems in the
+    # boot string (no GEM_* in the worker's env), the newest chi there, else
+    # the fallback pin (ChiHome.fallback_version). A home that still can't
+    # load chi (a broken install) logs HOME_BOOT_FAILED and exits: never a
+    # silent spawn timeout.
+    private_class_method def self.home_worker_command(session_id, state_dir:, gem_spec:, home:)
+      newest = home.newest_version
+      if newest && newest < Gem::Version.new(gem_spec.version.to_s)
+        ChiHome.warn_once(:older_than_spawner, home: newest.to_s, spawner: gem_spec.version.to_s)
+      end
+      fallback = ChiHome.fallback_version(home, gem_spec)
+      activate = if fallback
+                   "begin; gem 'samagotchi', '>= 0.a'; rescue LoadError => e; " \
+                     "ENV['#{BOOT_FALLBACK_ENV}'] = e.message; gem 'samagotchi', '= #{fallback}'; end"
+                 else
+                   "gem 'samagotchi', '>= 0.a'"
+                 end
+      home.boot_argv(run: "begin; #{activate}; require 'samagotchi/session_manager'; " \
+                           "#{HOME_BOOT_FAILED.sub("SID", session_id)}; end; " \
+                           "Samagotchi::SessionManager.run_session_loop('#{session_id}', state_dir: #{state_dir.inspect})")
+    end
+
     private_class_method def self.spawn_worker_for_session(session, state_dir:)
       session_dir = Session.session_dir(session.id, state_dir: state_dir)
       FileUtils.mkdir_p(session_dir)

data/lib/samagotchi/session_model_settings.rb

@@ -61,9 +61,12 @@ module Samagotchi
 
     # #turn_llm_context with where each value came from
     # (LLMContextStrategy.explain), nil when it can't be resolved.
+    # @param own [LLMContextOverride, nil] the session's own values to
+    #   resolve with (the ones a change would set: /llm-context's confirm)
     # @return [LLMContextStrategy::Explained, nil]
-    def llm_context_explained
-      model_setting(nil) { |model| model.llm_context_explained(llm_context_session_args) }
+    def llm_context_explained(own: :session)
+      args = own == :session ? llm_context_session_args : own&.resolve_args || {}
+      model_setting(nil) { |model| model.llm_context_explained(args) }
     end
 
     # #llm_context_explained's summary (Explained#summary), nil when it