samagotchi 0.51.0 → 0.52.0

data/lib/samagotchi/session_inbox.rb

@@ -183,20 +183,29 @@ module Samagotchi
       Dir.glob(File.join(input_dir, "*.json"))
     end
 
-    # @return [Array(String, Hash|nil, Boolean, Array<Hash>, String|nil)] a
-    #   claimed input file's prompt, origin ({client_id:, enqueued_id:},
-    #   nil when it names no sender), whether its turn runs with the raised
-    #   iteration limit (--no-interrupt), its image refs ({file:, name:}),
-    #   and its delivery ("queue" or nil; a file without the key is one an
-    #   older chi wrote, so nil)
+    # A claimed input file as read: its +prompt+, +origin+ ({client_id:,
+    # enqueued_id:}, nil when it names no sender), whether its turn runs
+    # with the raised iteration limit (+no_interrupt+, --no-interrupt), its
+    # +images+ ({file:, name:} refs), and its +delivery+ ("queue" or nil; a
+    # file without the key is one an older chi wrote, so nil).
+    Input = Data.define(:prompt, :origin, :no_interrupt, :images, :delivery) do
+      def initialize(prompt:, origin: nil, no_interrupt: false, images: [], delivery: nil) = super
+    end
+    # A file that doesn't parse, or isn't a JSON object: no prompt.
+    UNREADABLE_INPUT = Input.new(prompt: nil)
+
+    # @return [Input] a claimed input file's contents; UNREADABLE_INPUT for
+    #   one that isn't a JSON object
     def self.read_input(claimed_file)
       data = JSON.parse(File.read(claimed_file).to_s)
+      return UNREADABLE_INPUT unless data.is_a?(Hash)
+
       origin = { client_id: data["client_id"], enqueued_id: data["enqueued_id"] }.compact
       images = Array(data["images"]).select { |image| image.is_a?(Hash) }.map { |image| image.transform_keys(&:to_sym) }
-      [data["prompt"].to_s, origin.empty? ? nil : origin, data["no_interrupt"] == true, images,
-       Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil]
+      Input.new(prompt: data["prompt"].to_s, origin: origin.empty? ? nil : origin, no_interrupt: data["no_interrupt"] == true,
+                images: images, delivery: Delivery.queue?(data["delivery"]) ? Delivery::QUEUE : nil)
     rescue JSON::ParserError
-      [nil, nil, false, [], nil]
+      UNREADABLE_INPUT
     end
 
     # Whether an unclaimed input file carries images (a mid-turn drain

data/lib/samagotchi/session_manager.rb

@@ -14,6 +14,7 @@ require_relative "session"
 require_relative "session_inbox"
 require_relative "session_metrics"
 require_relative "llm_context_strategy"
+require_relative "session_setup"
 require_relative "host_registry"
 require_relative "utf8_default"
 require_relative "turn_note"
@@ -163,8 +164,8 @@ module Samagotchi
     # @param images_from [String, nil] the session dir the seed's images are in
     # @param title [String, nil] what the lists show before the first turn
     #   (the prompt's preview by default, else the seed's first user message)
-    # @param llm_context [LLMContextOverride, nil] the session's own
-    #   llm_context values (chi --llm-context; a fork copies its parent's)
+    # @param setup [SessionSetup] the session's own settings (chi
+    #   --llm-context; a fork and a continue copy their session's)
     # @param continues [String, nil] the session this one continues (a
     #   session field; #continue_session)
     # @param note [String, nil] a context note the session starts with,
@@ -176,7 +177,7 @@ module Samagotchi
     #   and #model_warning: an id its host's saved list doesn't have
     def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
-                           title: nil, delegate: false, llm_context: nil, continues: nil, note: nil,
+                           title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
                            note_source: "chi", before_spawn: nil)
       sd = state_dir || Session.default_state_dir
       # The resolved ref is stored (a resumed session keeps its model when an
@@ -198,7 +199,7 @@ module Samagotchi
         parent_id: parent_id,
         messages: messages,
         delegate: delegate,
-        llm_context: llm_context,
+        setup: setup,
         continues: continues
       )
       session.model_warning = model_warning
@@ -232,7 +233,7 @@ module Samagotchi
 
     # Start the next link of a chain: a new session that continues
     # +id_or_ref+ (Session#continues) in its folder, on its model (the name
-    # it was typed as, so an alias holds) and with its own llm_context,
+    # it was typed as, so an alias holds) and with its own setup (SessionSetup),
     # starting with a context note from chi: the link and the previous
     # link's recap (SessionChain.note_text). The previous link is archived
     # first, with its finished delegates (archive_session's rules: a turn
@@ -363,7 +364,7 @@ module Samagotchi
         ChildMove.apply(move, from: previous.id, to: link.id, state_dir: state_dir)
       end
       link = spawn_session(prompt: start, title: title, working_directory: previous.working_directory,
-                           model_name: previous.model_typed || previous.model_name, llm_context: previous.llm_context,
+                           model_name: previous.model_typed || previous.model_name, setup: SessionSetup.of(previous),
                            continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
                            note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn)
       link.moved_children = move
@@ -515,7 +516,7 @@ module Samagotchi
 
     GUARDRAILS_ENV_PREFIX = "SAMAGOTCHI_GUARDRAILS_"
     # Tools::Builtins.parent_env's (Tools::TaskRuntime::MARKER_ENV_KEYS).
-    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL].freeze
+    SESSION_MARKER_ENV = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING].freeze
 
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).

data/lib/samagotchi/session_setup.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "llm_context_override"
+require_relative "thinking"
+
+module Samagotchi
+  # A session's own settings that come before its model's, carried as one
+  # value on the paths that spawn a session from a whole setup
+  # (SessionManager.spawn_session, a continue, a plugin's fork, the web's
+  # create, chi send --new): +llm_context+ is an LLMContextOverride or nil,
+  # +thinking+ a level Symbol (Thinking.session_level) or nil.
+  #
+  # It doesn't save itself: the session keeps each setting in its own field
+  # and file key, and resolves it on its own. A delegate child starts
+  # without one; a continue and a fork copy their session's (.of).
+  SessionSetup = Data.define(:llm_context, :thinking) do
+    def initialize(llm_context: nil, thinking: nil) = super
+
+    def empty? = llm_context.nil? && thinking.nil?
+
+    # A session's own setup, for a session that starts from it.
+    # @param session [Session, nil]
+    # @return [SessionSetup]
+    def self.of(session)
+      return new if session.nil?
+
+      new(llm_context: session.llm_context, thinking: session.thinking)
+    end
+  end
+end

data/lib/samagotchi/steer_cut.rb

@@ -22,6 +22,13 @@ module Samagotchi
       { thinking: event[:thinking].to_s, text: text.to_s }
     end
 
+    # steer.cut_after: how long a generation streams only thinking before a
+    # message may cut it, in whole seconds (0 or less: cutting is off).
+    # @return [Integer]
+    def self.cut_after
+      Config.get("steer.cut_after").to_i
+    end
+
     # +clock+: monotonic seconds; +controller+: the running turn's cancel
     # controller (nil between turns), read only when a cut is due.
     def initialize(clock:, controller:)
@@ -51,7 +58,7 @@ module Samagotchi
     def cut_for_steer(source, epoch: nil)
       return :off unless Steer.cuts?(source)
 
-      after = Config.get("steer.cut_after").to_i
+      after = self.class.cut_after
       return :off unless after.positive?
 
       ctrl = @controller.call
@@ -104,7 +111,7 @@ module Samagotchi
     def recheck
       return unless @waiting.waiting?
 
-      after = Config.get("steer.cut_after").to_i
+      after = self.class.cut_after
       return unless after.positive? && @phase.cuttable?(after)
 
       source = @waiting.take

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -4,6 +4,7 @@ require_relative "../session"
 require_relative "../config"
 require_relative "../model_profile"
 require_relative "../session_manager"
+require_relative "../thinking_command"
 require_relative "../bridge_client"
 require_relative "../parent_report"
 require_relative "../cli/exit"
@@ -40,16 +41,20 @@ module Samagotchi
       #   (LLMContextOverride.update): a new session starts with them; a
       #   resumed or attached one's worker gets a /llm-context, after the
       #   /model
+      # @param thinking [String, nil] --thinking as typed: a new session
+      #   starts with it as its own level; a resumed or attached one's
+      #   worker gets a /thinking, after those
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [], llm_context: {})
+              memories: [], muted_memories: [], llm_context: {}, thinking: nil)
         client = connect(attach: attach, shared: shared, resume: resume, model: model,
-                         memories: memories, muted_memories: muted_memories, llm_context: llm_context)
+                         memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking)
         commands = []
         commands << "/model #{model}" if model && (attach || resume)
         commands << LLMContextOverride.command_line(llm_context) if (attach || resume) && !llm_context.empty?
+        commands << "#{ThinkingCommand::NAME} #{thinking}" if (attach || resume) && thinking
         first_command = commands.size > 1 ? commands : commands.first
         surface = open_surface
         attached = AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
@@ -111,7 +116,7 @@ module Samagotchi
       # @return [BridgeClient] a client for the live Bridge of the session
       # @raise [Error]
       def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
-                  memories: [], muted_memories: [], llm_context: {}, err: $stderr)
+                  memories: [], muted_memories: [], llm_context: {}, thinking: nil, err: $stderr)
         sd = state_dir || Session.default_state_dir
         warn_memory_flags_ignored(attach || resume, memories, muted_memories, err) if attach || resume
         if attach
@@ -127,7 +132,8 @@ module Samagotchi
                   else
                     SessionManager.spawn_session(prompt: nil, model_name: model && model_ref(model), state_dir: sd,
                                                  memories: memories, muted_memories: muted_memories,
-                                                 llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context))
+                                                 setup: SessionSetup.new(llm_context: llm_context.empty? ? nil : LLMContextOverride.update(nil, llm_context),
+                                                                         thinking: Thinking.session_level(thinking)))
                   end
         client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
         client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -430,7 +430,7 @@ module Samagotchi
       # @return [nil]
       def submit_delivery(choice, text)
         return @screen.commit(STEER_CHOICE_USAGE) if text.empty?
-        return @screen.commit(QUEUE_UNAVAILABLE) if choice == :queue
+        return @screen.commit(QUEUE_UNAVAILABLE) if choice == :queue && @running
 
         # To an idle session it is an ordinary prompt: no delivery to send.
         send_prompt(text, delivery: @running ? Delivery::CUT : nil)

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -5,6 +5,7 @@ require_relative "../served_model"
 require_relative "../image_store"
 require_relative "../turn_note"
 require_relative "../steer"
+require_relative "../steer_cut"
 require_relative "../memory_bundle/index_size"
 require_relative "../prompt_note"
 
@@ -99,7 +100,8 @@ module Samagotchi
       # line goes in at the running turn's next step boundary (nothing cuts
       # unless the message asked for it), /cut's cutting now or once the
       # thinking passes steer.cut_after, and /queue's waiting for the end.
-      # Both TUIs print the same words (SteerCut#cut_for_steer's answer).
+      # Both TUIs and chi send --cut print the same words
+      # (SteerCut#cut_for_steer's answer).
       NEXT_STEP_NOTE = "(goes in at the next step)"
       CUT_NOW_NOTE = "(cut in now)"
       CUT_WAITS_NOTE = "(cuts in once the thinking passes %d s)"
@@ -115,14 +117,17 @@ module Samagotchi
 
       # @param outcome [Symbol] SteerCut#cut_for_steer's answer: :now, :waits or :off
       # @return [String] the dim line to show for a /cut
-      def steer_cut_note(outcome)
+      def self.steer_cut_note(outcome)
         case outcome
         when :now then CUT_NOW_NOTE
-        when :waits then format(CUT_WAITS_NOTE, Config.get("steer.cut_after").to_i)
+        when :waits then format(CUT_WAITS_NOTE, SteerCut.cut_after)
         else CUT_OFF_NOTE
         end
       end
 
+      # The same words, for a UI that includes the module.
+      def steer_cut_note(outcome) = Formatting.steer_cut_note(outcome)
+
       # The choice a mid-turn line carries, as [:cut, "TEXT"] or
       # [:queue, "TEXT"]; nil for any other line. The text is "" when the
       # line named the choice without one.
@@ -591,6 +596,8 @@ module Samagotchi
         lines << "model notes:      #{notes}" unless notes.empty?
         llm_context = llm_context_stats_text(snapshot[:llm_context])
         lines << "llm context:      #{llm_context}" if llm_context
+        thinking = thinking_stats_text(snapshot[:thinking])
+        lines << "thinking:         #{thinking}" if thinking
         if snapshot[:served_model]
           asked = snapshot[:served_model_for]
           differs = !snapshot[:served_expected_by] && ServedModel.differs?(asked, snapshot[:served_model])
@@ -630,6 +637,17 @@ module Samagotchi
           "budget #{budget} (#{get.call(:budget_where)})"
       end
 
+      # "low (session)", "default" for /stats (Thinking::Explained#summary;
+      # symbol or string keys, the attached TUI's come as JSON); nil
+      # without one.
+      def thinking_stats_text(summary)
+        return nil unless summary.is_a?(Hash)
+
+        level = summary[:level] || summary["level"]
+        source = summary[:source] || summary["source"]
+        source ? "#{level} (#{source})" : level
+      end
+
       # ", cached 4864 (93%), cache writes 312, re-prefilled 2100, reasoning
       # 212" for the tokens line; the counts a server didn't report are left
       # out (re-prefilled: SessionMetrics' reprefill_sum).

data/lib/samagotchi/terminal_ui.rb

@@ -90,9 +90,12 @@ module Samagotchi
     #   however the REPL ends, saves no memories and writes no recap
     # @param llm_context [Hash{Symbol => String}] --llm-context* as typed
     #   (LLMContextOverride.update): set on the new or resumed session
+    # @param thinking [String, nil] --thinking as typed: the new or resumed
+    #   session's own level (default unsets it)
     def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
-                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {})
+                   spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false, llm_context: {}, thinking: nil)
       @scratch        = scratch
+      @thinking_word  = thinking
       @prompt         = prompt
       @llm_context_words = llm_context
       @default_model_name = ModelProfile.required_model_name(nil)
@@ -246,8 +249,10 @@ module Samagotchi
       ))
       # --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.
-      unless @llm_context_words.empty?
-        session.llm_context = LLMContextOverride.update(session.llm_context, @llm_context_words)
+      # --thinking: the session's own level, saved at once on a resumed one.
+      unless @llm_context_words.empty? && @thinking_word.nil?
+        session.llm_context = LLMContextOverride.update(session.llm_context, @llm_context_words) unless @llm_context_words.empty?
+        session.thinking = Thinking.session_level(@thinking_word) if @thinking_word
         session.save if @resume_session
       end
       claim_session!(session.id) unless @owner_lock

data/lib/samagotchi/thinking.rb

@@ -10,7 +10,9 @@ module Samagotchi
   #   low, medium, high   the effort a chat host is asked for
   #   default  chi sends nothing: the provider's or template's own default
   #
-  # Order (#resolve): --thinking / SAMAGOTCHI_THINKING_LEVEL, then
+  # Order (#resolve): the session's own level (/thinking, chi --thinking at
+  # start, chi send --new --thinking, the web), then the process default
+  # (chi web --thinking / SAMAGOTCHI_THINKING_LEVEL), then
   # models.<key>.thinking, hosts.<name>.thinking, thinking.level in
   # config.yml, then default.
   module Thinking
@@ -33,8 +35,39 @@ module Samagotchi
     # anything there (low/medium/high have no native knob).
     Native = Data.define(:system_token, :prefill, :honoured)
 
+    # The source a session's own level reads as.
+    SESSION_SOURCE = "session"
+
+    # A level and where it came from (#explain): +source+ is "session",
+    # "--thinking", "SAMAGOTCHI_THINKING_LEVEL", "models: qwen",
+    # "hosts.work" or "thinking.level", nil for the default; +own+ is the
+    # session's own level, nil without one. What /thinking, /model,
+    # /stats, the snapshots and the web read.
+    Explained = Data.define(:level, :source, :own) do
+      # "low (session)", "default" with no source.
+      def label = source ? "#{level} (#{source})" : level.to_s
+
+      # The plain form the snapshots, the worker's command_ran event and
+      # the web read.
+      # @return [Hash] symbol keys
+      def summary = { level: level.to_s, source: source, own: own&.to_s }
+    end
+
     module_function
 
+    # A session's own level from its file or a command word: :off, :low,
+    # :medium or :high; nil for anything else, default included (unset:
+    # the session follows the process default and the model). Never warns:
+    # a session file keeps a value it can't read as written.
+    # @return [Symbol, nil]
+    def session_level(value)
+      return value if LEVELS.include?(value) && value != DEFAULT
+      return nil unless value.is_a?(String)
+
+      level = value.strip.downcase.to_sym
+      LEVELS.include?(level) && level != DEFAULT ? level : nil
+    end
+
     # A configured value as a level; nil when unset or not a level (that
     # warns once, naming +where+). YAML reads an unquoted `off` as false,
     # which is :off; true (`on`) isn't a level.
@@ -51,13 +84,17 @@ module Samagotchi
       nil
     end
 
-    # The level for +target+ and where it came from ("--thinking",
-    # "models: qwen", "hosts.work", "thinking.level"; nil for the default).
+    # The level for +target+ and where it came from ("session",
+    # "--thinking", "models: qwen", "hosts.work", "thinking.level"; nil for
+    # the default).
     # @param target [HostRegistry::ModelTarget]
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
-    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
+    # @param session [Symbol, nil] the session's own level (Session#thinking)
     # @return [Array(Symbol, String|nil)]
-    def resolve(target, names:, models: nil)
+    def resolve(target, names:, models: nil, session: nil)
+      return [session, SESSION_SOURCE] if session
+
       global, origin = global_level
       return [global, origin == :cli ? "--thinking" : "SAMAGOTCHI_THINKING_LEVEL"] if global && %i[cli env].include?(origin)
 
@@ -66,8 +103,8 @@ module Samagotchi
       rescue StandardError
         {}
       end
-      key, value = ConfigFile.model_setting(names, :thinking, models: models)
-      return [value, "models: #{key}"] if key
+      setting = ConfigFile.model_setting(names, :thinking, models: models)
+      return [setting.value, "models: #{setting.key}"] if setting
 
       host = target.entry.thinking
       return [host, "hosts.#{target.entry.name}"] if host
@@ -76,6 +113,13 @@ module Samagotchi
       [DEFAULT, nil]
     end
 
+    # #resolve, as an Explained with the session's own level beside it.
+    # @return [Explained]
+    def explain(target, names:, models: nil, session: nil)
+      level, source = resolve(target, names: names, models: models, session: session)
+      Explained.new(level: level, source: source, own: session)
+    end
+
     # thinking.level as a level and its origin (:cli, :env, :file), or nil.
     def global_level
       raw, origin = Config.get_with_origin("thinking.level")
@@ -88,6 +132,22 @@ module Samagotchi
       nil
     end
 
+    # What a level change costs the prompt cache on +target+ (/thinking's
+    # note; a confirm step may ask before the costly ones):
+    #   :full      the native Gemma 4 prompt starts with <|think|>, so the
+    #              whole prompt is read again;
+    #   :provider  a chat host gets other request fields: a local llama.cpp
+    #              or Splash server keeps its cache, a hosted API may not;
+    #   :tail      native Qwen and the rest: only the tail changes.
+    # @param target [HostRegistry::ModelTarget]
+    # @param profile [String, nil] the native prompt profile's name
+    # @return [Symbol]
+    def cache_cost(target, profile: nil)
+      return :provider if target.entry&.chat?
+
+      profile == "gemma4" ? :full : :tail
+    end
+
     # Request fields for an OpenAI-style chat host. off sends both switches
     # (the template's enable_thinking and the OpenAI-style reasoning_effort
     # "none"): llama.cpp, Splash and OpenRouter each honour one of them.

data/lib/samagotchi/thinking_command.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "thinking"
+
+module Samagotchi
+  # /thinking, the session's own thinking level (Session#thinking): with no
+  # argument, the level the next turn runs at and where it came from;
+  # `/thinking off|low|medium|high` sets the session's own, `/thinking
+  # default` unsets it (the session follows the process default, the
+  # model, its host, then thinking.level). 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 (Thinking.cache_cost).
+  class ThinkingCommand
+    NAME = "/thinking"
+    SETTABLE = (Thinking::LEVELS - [Thinking::DEFAULT]).freeze
+    USAGE = "usage: #{NAME} [#{Thinking::LEVELS.join("|")}]".freeze
+
+    COST_NOTES = {
+      full: "On this model the whole prompt is read again (Gemma's <|think|> starts it).",
+      provider: "The request's thinking fields change: a local llama.cpp or Splash server keeps its cache; " \
+                "hosted APIs (OpenRouter → Claude, OpenAI) may restart theirs.",
+      tail: "Only the prompt's tail changes: the cache keeps the rest."
+    }.freeze
+
+    # @param engine [Engine] #thinking_explained, #thinking_override(=),
+    #   #session, #thinking_cache_cost
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows /thinking
+    # @return [Array(String, Boolean)] the reply and whether the level changed
+    # @raise [ArgumentError] a word that isn't a level (with USAGE)
+    def run(args)
+      word = args.to_s.strip.downcase
+      return [listing(@engine.thinking_explained), false] if word.empty?
+
+      level = word.to_sym
+      raise ArgumentError, "unknown thinking level #{word}\n#{USAGE}" unless Thinking::LEVELS.include?(level)
+
+      session = @engine.session or raise ArgumentError, "no session yet"
+      before = @engine.thinking_explained
+      @engine.thinking_override = SETTABLE.include?(level) ? level : nil
+      @save.call(session)
+      after = @engine.thinking_explained
+      [[listing(after), *notes(before, after)].join("\n"), true]
+    end
+
+    # The level, where it came from, and what the session sets itself.
+    def listing(explained)
+      return "thinking: can't be resolved for this model" unless explained
+
+      lines = ["thinking: #{explained.label}"]
+      unless explained.own
+        lines << "  this session's own: none (follows chi web --thinking / SAMAGOTCHI_THINKING_LEVEL, the model, " \
+                 "its host, then thinking.level)"
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    def notes(before, after)
+      return [] unless before && after
+      return ["(no change to what the next turn runs under)"] if before.level == after.level
+
+      ["From the next turn's start (a running turn keeps its own).", COST_NOTES[@engine.thinking_cache_cost]].compact
+    end
+  end
+end

data/lib/samagotchi/tools/builtins.rb

@@ -119,15 +119,19 @@ module Samagotchi
       # wrapper. The session's id, "chi" without one. And the model the
       # session runs on (SAMAGOTCHI_SESSION_MODEL, read live, so right after
       # /model), which chi self reports; unset when unknown, so a value
-      # inherited from an outer session never passes for this one. A
+      # inherited from an outer session never passes for this one. So too
+      # the session's own thinking level (SAMAGOTCHI_SESSION_THINKING, unset
+      # without one), which chi self puts first. A
       # worker's `chi --model X` default (ModelProfile::MODEL_FROM_CLI_ENV)
       # is unset: it was that run's, not the default of a chi run here.
       def parent_env(kctx, env: ENV)
         peers = kctx.peers
         id = peers.respond_to?(:session_id) ? peers.session_id.to_s : ""
         model = peers.respond_to?(:model_ref) ? peers.model_ref.to_s : ""
+        thinking = peers.respond_to?(:thinking) ? peers.thinking&.to_s : nil
         { Guardrails::ParentApprovals::PARENT_SESSION_ENV => id.empty? ? "chi" : id,
-          SESSION_MODEL_ENV => model.empty? ? nil : model }.merge(cli_model_unset(env))
+          SESSION_MODEL_ENV => model.empty? ? nil : model,
+          SESSION_THINKING_ENV => thinking }.merge(cli_model_unset(env))
       end
 
       # The unsets that keep a `chi --model X` worker's default from passing
@@ -139,6 +143,7 @@ module Samagotchi
       end
 
       SESSION_MODEL_ENV = "SAMAGOTCHI_SESSION_MODEL"
+      SESSION_THINKING_ENV = "SAMAGOTCHI_SESSION_THINKING"
 
       # task_create's parent_env, less the unsets of a variable the model
       # set in its env (a SAMAGOTCHI_DEFAULT_MODEL it asked for stays).

data/lib/samagotchi/tools/peers.rb

@@ -8,10 +8,11 @@ module Samagotchi
     # canceled (a waiting tool returns on it), and the question flow a
     # delegate's approval is relayed through (relay: nil when this session
     # can't host one), and the model the session runs on (model_ref: the
-    # resolved ref, live after /model). Engine hands KernelLoop one that follows its current
+    # resolved ref, live after /model), and the session's own thinking level
+    # (thinking: nil without one). Engine hands KernelLoop one that follows its current
     # session (Engine::PeerView); this plain one is for specs and a kernel
     # without an Engine.
-    Peers = Struct.new(:session_id, :cwd, :state_dir, :cancelled, :relay, :model_ref, keyword_init: true) do
+    Peers = Struct.new(:session_id, :cwd, :state_dir, :cancelled, :relay, :model_ref, :thinking, keyword_init: true) do
       # @return [Boolean] the turn was canceled (:cancelled is a proc or a value)
       def cancelled?
         cancelled.respond_to?(:call) ? !!cancelled.call : !!cancelled

data/lib/samagotchi/tools/task_runtime.rb

@@ -22,7 +22,7 @@ module Samagotchi
       OUTPUT_TAIL_READ_BYTES = 16 * 1024
       SANITIZED_ENV_KEYS = %w[RUBYOPT RUBYLIB BUNDLE_GEMFILE BUNDLE_BIN_PATH BUNDLER_VERSION].freeze
       # Set by chi (Builtins.parent_env); the model's env can't change it.
-      MARKER_ENV_KEYS = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL].freeze
+      MARKER_ENV_KEYS = %w[SAMAGOTCHI_PARENT_SESSION SAMAGOTCHI_SESSION_MODEL SAMAGOTCHI_SESSION_THINKING].freeze
       # task_wait and task_get add it to a task the user stopped (the web's
       # stop-task button), so the model doesn't rerun the job.
       # A record whose pid isn't a process group chi started (missing, 0, 1,

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.51.0"
+  VERSION = "0.52.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/vision_support.rb

@@ -24,7 +24,7 @@ module Samagotchi
     # @param target [HostRegistry::ModelTarget]
     # @param profile [ModelProfile, nil] the model's prompt profile (native)
     # @param adapter [LLM::OpenAIChat, nil] the chat host's adapter
-    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
     # @param names [Array<String>] the model's lookup names (HostRegistry#lookup_names)
     # @return [Answer]
     def self.for(target, names:, profile: nil, adapter: nil, models: nil)
@@ -51,8 +51,9 @@ module Samagotchi
       rescue StandardError
         {}
       end
-      key, value = ConfigFile.model_setting(names, :vision, models: models)
-      return Answer.new(value: value, reason: value ? nil : "models: #{key} sets vision: false") if key
+      if (setting = ConfigFile.model_setting(names, :vision, models: models))
+        return Answer.new(value: setting.value, reason: setting.value ? nil : "models: #{setting.key} sets vision: false")
+      end
       return nil if entry.vision.nil?
 
       Answer.new(value: entry.vision, reason: entry.vision ? nil : "hosts.#{entry.name} sets vision: false")