samagotchi 0.66.0 → 0.68.0

data/lib/samagotchi/engine.rb

@@ -14,11 +14,16 @@ require_relative "context_status"
 require_relative "steer"
 require_relative "turn_note"
 require_relative "model_profile"
+require_relative "effective_model"
+require_relative "session_setting"
+require_relative "thinking_notices"
 require_relative "cancellation_controller"
 require_relative "context_window"
 require_relative "kernel_loop"
 require_relative "tools/builtins"
 require_relative "tools/task_runtime"
+require_relative "tools/tool_index"
+require_relative "peer_sources"
 require_relative "session_commands"
 require_relative "plugin/loader"
 require_relative "extension_load"
@@ -31,7 +36,7 @@ require_relative "llm/backend"
 require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
-require_relative "toolkit"
+require_relative "toolkit_binding"
 require_relative "answer_tail"
 require_relative "archive_store"
 require_relative "session_observer"
@@ -44,6 +49,7 @@ require_relative "recap_setup"
 require_relative "idle_reminders"
 require_relative "idle_scheduler"
 require_relative "hooks"
+require_relative "hook_routes"
 require_relative "guardrails"
 require_relative "reminder_store"
 require_relative "reminder_queue"
@@ -131,24 +137,30 @@ module Samagotchi
       # is used (the REPL checks the model it starts on, #switch_model!).
       @default_model_name = ModelProfile.required_model_name(model_name)
       ModelProfile.check_host!(model_name, hosts: @host_registry.entries) unless model_name.to_s.strip.empty?
-      @effective_model_name = @default_model_name
+      # Guards the model choice and the profile cached for it (#store_profile).
+      @profile_mutex = Mutex.new
+      typed = model_typed.to_s.strip
+      @model_choice = ModelChoice.new(name: @default_model_name, typed: typed.empty? ? @default_model_name : typed)
       # An injected client (specs) stands in for every host's client.
       @host_registry.client_override = client if client
-      @client = @host_registry.resolve(@effective_model_name).client
+      @client = effective_model.client
       # A caller's profile pins it (until a model switch); otherwise
       # #profile_resolution decides on first need (see there), so building an
       # Engine makes no network call.
       @given_profile = profile ? ModelProfile.normalize(profile) : nil
-      @typed_model_name = model_typed.to_s.strip.empty? ? @default_model_name : model_typed.to_s.strip
       @profile_resolution = nil
       # Ensure the built-in system bundle is installed (lazy, warn-only).
       # This is the single seam for both TUI and non-TUI (web/worker) paths.
       begin
         require_relative "memory_bundle/system_bundle"
         MemoryBundle::SystemBundle.ensure!
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Log.warn(:memory, "system_bundle_ensure_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       end
+      # What hooks and plugins do beyond reading their event (a notice, a
+      # question, a stop, a steer), routed to the UIs. Built before anything
+      # that may notify.
+      @hook_routes = build_hook_routes
       # Load hooks from config (plugins) and create the registry; what fails
       # to load is announced, and a required guardrail's failure denies
       # every tool call. Rules load now too, so their errors are announced.
@@ -185,9 +197,18 @@ module Samagotchi
       # plugins' tool sets from chi.replace_tools until the turn thread
       # applies them (#apply_staged_tools!). Built before the plugins load.
       @plugin_tasks = build_plugin_tasks
-      # The toolkits plugins declare (chi.toolkit), beside the built-in and
-      # config ones (#toolkit_kits).
-      @plugin_kits = []
+      # The session's toolkit: the kits (the plugins' too, chi.toolkit),
+      # what its next turn declares, the turn-start apply.
+      @toolkit_binding = build_toolkit_binding
+      # The notices a turn's thinking level leads to (once per session and host).
+      @thinking_notices = ThinkingNotices.new(session: -> { @session }, profile: -> { self.profile },
+                                              notify: ->(text, level, source) { hook_notify(text, level, source) })
+      # The tools plugins publish without declaring (chi.tool_source), and
+      # the search and call tools that reach them (Tools::ToolIndex).
+      @tool_index = Tools::ToolIndex.new
+      # The context sources the peer bundles declare as a peer agent's
+      # answers (chi.peer_source); the worker's ContextAbsorber asks it.
+      @peer_sources = PeerSources.new
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
@@ -275,7 +296,7 @@ module Samagotchi
     def wire_kernel(kernel, muted_memories)
       # A given kernel (specs) gets the Engine's store, hooks and tools, as
       # the one built here does.
-      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, model_name: @effective_model_name,
+      @kernel = kernel || KernelLoop.new(client: @client, profile: @given_profile, model_name: effective_model_name,
                                          hooks: @hooks, reminder_store: @reminder_store, tools: @tools)
       @kernel.reminder_store = @reminder_store
       @kernel.hooks = @hooks
@@ -360,8 +381,8 @@ module Samagotchi
     end
 
     # The backend for the next turn: the loop the effective model's host speaks.
-    def backend
-      backend_for(@host_registry.resolve(@effective_model_name))
+    def backend(model = effective_model)
+      backend_for(model)
     end
 
     # Record that activity happened (user input or a completed turn): the
@@ -451,7 +472,8 @@ module Samagotchi
 
       log_dropped_steers(steers, "answered")
       []
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:turn, "take_steers_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       []
     end
     private :take_steers
@@ -508,14 +530,17 @@ module Samagotchi
 
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
-    # effective_model_name: the model as given (maybe an alias; HostRegistry#resolve
-    # applies it); typed_model_name: as typed at start or at the last /model.
-    attr_reader :default_model_name, :effective_model_name, :typed_model_name
+
+    # The model as given (maybe an alias; HostRegistry#resolve applies it).
+    def effective_model_name = @model_choice.name
+
+    # The model as typed at start or at the last /model.
+    def typed_model_name = @model_choice.typed
 
     # The resolved ref a session stores for the effective model (ModelRef#ref:
     # the alias applied, "host:id" when it names a host).
     def effective_model_ref
-      model_ref_for(@effective_model_name)
+      model_ref_for(effective_model_name)
     end
 
     # The effective model as the system prompt names it (SystemPrompt::ModelIdentity):
@@ -523,11 +548,11 @@ module Samagotchi
     # only, the model its /props names when that differs. Never a new
     # request: only the /props answer profile resolution already cached.
     def model_identity
-      target = @host_registry.resolve(@effective_model_name)
-      entry = target.entry
+      model = effective_model
+      entry = model.entry
       host = entry && "host #{entry.name}, #{entry.url || "#{entry.host}:#{entry.port}"}"
-      SystemPrompt::ModelIdentity.new(ref: effective_model_ref, host: host, key: @model_key,
-                                      served: prompt_served_model(target), fallback_key: @fallback_model_key)
+      SystemPrompt::ModelIdentity.new(ref: model.ref, host: host, key: @model_key,
+                                      served: model.prompt_served, fallback_key: @fallback_model_key)
     end
 
     # The model notes for the effective model (ModelNotes): matched on its
@@ -552,7 +577,8 @@ module Samagotchi
       return saved.dup if !@prompt_builder.prompt_notes.nil? || !saved.empty? || @session.messages.to_a.any?
 
       model_notes.map { |note| PromptNote.from_note(note) }
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:model, "prompt_notes_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       []
     end
 
@@ -571,10 +597,10 @@ module Samagotchi
       summary = error.respond_to?(:summary) ? error.summary : error.message
       return summary unless error.is_a?(LLM::ProviderError) && error.host
 
-      note = @host_registry.alias_note(@effective_model_name)
+      note = @host_registry.alias_note(effective_model_name)
       note && note.end_with?("on host #{error.host}") ? "#{summary} (#{note})" : summary
-    rescue StandardError
-      summary
+    rescue StandardError => e
+      EffectiveModel::Unresolved.fallback(:alias_note_failed, effective_model_name, e, summary)
     end
 
     # +name+'s resolved ref (ModelRef#ref).
@@ -588,7 +614,8 @@ module Samagotchi
     def store_model!(session)
       ref = effective_model_ref
       session.model_name = ref
-      session.model_typed = @typed_model_name.to_s == ref ? nil : @typed_model_name
+      typed = typed_model_name
+      session.model_typed = typed.to_s == ref ? nil : typed
       session
     end
 
@@ -607,16 +634,25 @@ module Samagotchi
     # and kept, so the system prompt and the server's KV prefix stay stable;
     # #switch_model! starts over, and a failed server probe is retried before
     # the next turn (#refresh_profile!). The kernel follows each resolution.
+    # Kept with the model choice it was resolved for: one that finishes
+    # after a switch is neither kept nor applied (#store_profile).
     # @return [ModelProfile::Resolution]
     def profile_resolution
-      @profile_resolution ||= apply_profile(resolve_profile)
+      choice = @model_choice
+      cached = @profile_resolution
+      return cached.last if cached&.first.equal?(choice)
+
+      store_profile(choice, resolve_profile(choice))
     end
-    attr_reader :host_registry, :client
+    attr_reader :default_model_name, :host_registry, :client
 
     # @return [Commands::Registry] the commands this session runs: the
     #   built-ins, and the ones bundle plugins add
     attr_reader :command_registry
 
+    # @return [PeerSources] the sources the peer bundles declared
+    attr_reader :peer_sources
+
     # The model id sent for +full_ref+ (its alias applied, the host prefix off).
     def bare_model_name(full_ref)
       @host_registry.bare_name(full_ref)
@@ -627,8 +663,9 @@ module Samagotchi
     # (before aliases were applied there): that key is read when the
     # target's overlay is missing (KernelLoop#sync_model_key!).
     def sync_model_key!
-      @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
-      typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(@typed_model_name).last)
+      choice = @model_choice
+      @model_key = ModelOverlay.key_for(bare_model_name(choice.name))
+      typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(choice.typed).last)
       @fallback_model_key = typed_key == @model_key ? nil : typed_key
       @kernel.sync_model_key!(@model_key, fallback: @fallback_model_key)
     end
@@ -637,17 +674,17 @@ module Samagotchi
     # The effective model's bare name for the guardrails' models: rules;
     # nil without a model name.
     def guardrail_model_name
-      name = @effective_model_name && bare_model_name(@effective_model_name)
+      model = effective_model_name
+      name = model && bare_model_name(model)
       name.to_s.strip.empty? ? nil : name
     end
 
     # Point the kernel (and a chat backend) at the effective model's host
     # (after /model, --model, resume).
-    def sync_kernel_client!
-      target = @host_registry.resolve(@effective_model_name)
-      @client = target.client
-      @kernel.client = target.client if @kernel.client != target.client
-      backend_for(target)
+    def sync_kernel_client!(model = effective_model)
+      @client = model.client
+      @kernel.client = model.client if @kernel.client != model.client
+      backend_for(model)
     end
 
     # Subscribe a persistent observer to engine events.
@@ -948,11 +985,14 @@ module Samagotchi
       # The alias is applied where the model is resolved (HostRegistry#resolve),
       # once; checked here: an unknown host, an alias naming another host.
       resolved = ModelProfile.check_host!(ModelProfile.required_model_name(model_name), hosts: @host_registry.entries)
-      @effective_model_name = resolved
-      @typed_model_name = typed.to_s.strip.empty? ? model_name : typed.to_s.strip
-      # A profile given to .new was for the starting model.
-      @given_profile = nil
-      @profile_resolution = nil
+      choice = ModelChoice.new(name: resolved, typed: typed.to_s.strip.empty? ? model_name : typed.to_s.strip)
+      @profile_mutex.synchronize do
+        # One assignment: a reader on another thread sees the old pair or the new one.
+        @model_choice = choice
+        # A profile given to .new was for the starting model.
+        @given_profile = nil
+        @profile_resolution = nil
+      end
       sync_model_key!
       @prompt_builder.reset!
       # The notes the new model's prompt loads at its next build, so /model,
@@ -1023,22 +1063,24 @@ module Samagotchi
     # @return [Hash] @metrics.snapshot, filled in
     def stats_snapshot
       snapshot = @metrics.snapshot
-      target = @host_registry.resolve(@effective_model_name)
-      served, served_for = served_model_for(snapshot, target: target)
+      # One resolve for the whole snapshot (its readers' rescues stay theirs);
+      # a model that doesn't resolve raises here, as it always has.
+      model = effective_model
+      served, served_for = served_model_for(snapshot, model: model)
       snapshot = snapshot.merge(served_model: served, served_model_for: served_for,
-                                served_expected_by: served_expected_by(served, target: target), llm_context: llm_context_summary,
-                                thinking: thinking_explained&.summary,
-                                reasoning_history: reasoning_history_explained&.summary, prompt_notes: prompt_notes.map(&:to_h),
-                                prompt_files: @prompt_builder.prompt_files, price_host: target.entry.name)
+                                served_expected_by: model.served_expected_by(served),
+                                **setting_chips(SessionSetting::STATS, model),
+                                prompt_notes: prompt_notes.map(&:to_h), prompt_files: @prompt_builder.prompt_files,
+                                price_host: model.host_name)
       unless snapshot.dig(:context, :window_tokens)
-        window = current_context_window(target)
+        window = current_context_window(model)
         if window
           snapshot = snapshot.merge(context: snapshot[:context].merge(window_tokens: window.tokens,
                                                                       window_source: window.source.to_s))
         end
       end
       # The chat loop uses no prompt profile: drop one a native turn reported.
-      return snapshot.except(:profile, :profile_source) if target.entry.chat?
+      return snapshot.except(:profile, :profile_source) if model.chat?
 
       unless snapshot[:profile]
         resolution = profile_resolution
@@ -1051,10 +1093,11 @@ module Samagotchi
     # no turn yet (it woke after an idle exit): nil when either count is
     # unknown or context.status is off. Counted as the turns count it:
     # against the effective model's llm_context budget when it has one.
-    def saved_context_status(context)
+    def saved_context_status(context, model: :current)
       return nil unless context
 
-      ContextStatus.new(llm_context: turn_llm_context)
+      llm_context = model == :current ? turn_llm_context : model&.llm_context_explained(llm_context_session_args)&.resolved
+      ContextStatus.new(llm_context: llm_context)
                    .display_for(used_tokens: context[:used_tokens], window_tokens: context[:window_tokens])
     end
 
@@ -1062,10 +1105,7 @@ module Samagotchi
     # (LLMContextStrategy.explain), nil when it can't be resolved.
     # @return [LLMContextStrategy::Explained, nil]
     def llm_context_explained
-      target = @host_registry.resolve(@effective_model_name)
-      LLMContextStrategy.explain(target, names: model_lookup_names(target), **llm_context_session_args)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.llm_context_explained(llm_context_session_args) }
     end
 
     # #llm_context_explained's summary (Explained#summary), nil when it
@@ -1077,7 +1117,7 @@ module Samagotchi
 
     # The session's own llm_context values, nil when it has none.
     # @return [LLMContextOverride, nil]
-    def llm_context_override = @session&.llm_context
+    def llm_context_override = SessionSetting::LLM_CONTEXT.own(@session)
 
     # Set the session's own llm_context values (an empty override unsets
     # them); the next turn's start resolves them, never a running one (its
@@ -1086,23 +1126,18 @@ module Samagotchi
     def llm_context_override=(override)
       raise ArgumentError, "no session yet" unless @session
 
-      @session.llm_context = override
+      SessionSetting::LLM_CONTEXT.set(@session, override)
       # The status a later client reads counts against the new budget.
       @last_context_status = saved_context_status(@metrics.snapshot[:context]) || @last_context_status if @last_context_status
     end
 
     # The effective model is on a chat host (api: openai or anthropic), whose loop uses
     # no prompt profile.
-    def chat_model? = @host_registry.resolve(@effective_model_name).entry.chat?
+    def chat_model? = effective_model.chat?
 
     # "temperature=0.6 (hosts.work)" for /model: the effective model's
     # configured sampling, nil when none.
-    def sampling_summary
-      target = @host_registry.resolve(@effective_model_name)
-      SamplingSettings.summary(target, names: model_lookup_names(target))
-    rescue StandardError
-      nil
-    end
+    def sampling_summary = model_setting(nil, &:sampling_summary)
 
     # "off (models: qwen)", "low (session)" for /model: the effective
     # model's thinking level and where it came from, nil when none is set.
@@ -1116,10 +1151,7 @@ module Samagotchi
     # turn_sampling; on any error, the global and its name.
     # @return [Array(Integer, String|nil)]
     def steer_cut_after_explained
-      target = @host_registry.resolve(@effective_model_name)
-      SteerCutAfter.resolve(target, names: model_lookup_names(target))
-    rescue StandardError
-      [SteerCut.cut_after, "steer.cut_after"]
+      model_setting([SteerCut.cut_after, "steer.cut_after"], &:steer_cut_after_explained)
     end
 
     # #steer_cut_after_explained's seconds: what SteerCut#cut_for_steer
@@ -1141,10 +1173,7 @@ module Samagotchi
     # +own+: the session's own level to resolve with (the current one by
     # default; /thinking asks what a change would resolve to).
     def thinking_explained(own: thinking_override)
-      target = @host_registry.resolve(@effective_model_name)
-      Thinking.explain(target, names: model_lookup_names(target), session: own)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.thinking_explained(own: own) }
     end
 
     # "drop (models: qwen)" for /model: the effective chat model's
@@ -1152,14 +1181,7 @@ module Samagotchi
     # default, the model runs on the native loop (which ignores it) or it
     # can't be resolved.
     def reasoning_history_summary
-      target = @host_registry.resolve(@effective_model_name)
-      return nil unless target.entry&.chat?
-
-      level, source = ReasoningHistory.resolve(target, names: model_lookup_names(target),
-                                                       session: reasoning_history_override)
-      source ? ReasoningHistory.label(level, source) : nil
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.reasoning_history_summary(own: reasoning_history_override) }
     end
 
     # The effective chat model's reasoning_history level with where it came
@@ -1171,12 +1193,7 @@ module Samagotchi
     # +own+: the session's own level to resolve with (the current one by
     # default; a command asks what a change would resolve to).
     def reasoning_history_explained(native: false, own: reasoning_history_override)
-      target = @host_registry.resolve(@effective_model_name)
-      return nil unless native || target.entry&.chat?
-
-      ReasoningHistory.explain(target, names: model_lookup_names(target), session: own)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.reasoning_history_explained(own: own, native: native) }
     end
 
     # What a reasoning_history change from level +from+ to level +to+ costs
@@ -1185,10 +1202,7 @@ module Samagotchi
     # marked as refusing it may still get :history (one needless ask).
     # @return [Symbol, nil]
     def reasoning_history_cache_cost(from, to)
-      target = @host_registry.resolve(@effective_model_name)
-      ReasoningHistory.cache_cost(from, to, target: target, conversation: @session&.messages)
-    rescue StandardError
-      nil
+      model_setting(nil) { |model| model.reasoning_history_cache_cost(from, to, conversation: @session&.messages) }
     end
 
     # Whether the session has a model reply (a cache to restart at all).
@@ -1198,7 +1212,7 @@ module Samagotchi
 
     # The session's own reasoning_history level, nil when it has none.
     # @return [Symbol, nil]
-    def reasoning_history_override = @session&.reasoning_history
+    def reasoning_history_override = SessionSetting::REASONING_HISTORY.own(@session)
 
     # Set the session's own reasoning_history level (nil unsets it); the
     # next turn's start resolves it. The caller saves the session.
@@ -1206,19 +1220,18 @@ module Samagotchi
     def reasoning_history_override=(level)
       raise ArgumentError, "no session yet" unless @session
 
-      @session.reasoning_history = level
+      SessionSetting::REASONING_HISTORY.set(@session, level)
     end
 
     # The session's own thinking level, nil when it has none.
     # @return [Symbol, nil]
-    def thinking_override = @session&.thinking
+    def thinking_override = SessionSetting::THINKING.own(@session)
 
     # What a thinking level change costs the effective model's prompt
     # cache (Thinking.cache_cost): :full, :provider or :tail.
     # @return [Symbol]
     def thinking_cache_cost
-      target = @host_registry.resolve(@effective_model_name)
-      Thinking.cache_cost(target, profile: target.entry&.chat? ? nil : profile&.name)
+      effective_model.thinking_cache_cost { profile }
     end
 
     # Set the session's own thinking level (nil unsets it); the next turn's
@@ -1228,7 +1241,7 @@ module Samagotchi
     def thinking_override=(level)
       raise ArgumentError, "no session yet" unless @session
 
-      @session.thinking = level
+      SessionSetting::THINKING.set(@session, level)
     end
 
     # The model the server serves for the current model, and the name asked
@@ -1237,17 +1250,15 @@ module Samagotchi
     # else [nil, nil].
     # @return [Array(String, String), Array(nil, nil)]
     def served_model(probe: true)
-      served_model_for(@metrics.served_report, target: probe ? @host_registry.resolve(@effective_model_name) : nil)
+      served_model_for(@metrics.served_report, model: probe ? effective_model : nil)
     end
 
     # The host whose hosts.<name>.models.<id>.served names +served+ for the
     # current model (a gateway's round-robin targets): not a mismatch to
     # warn about. nil when none does.
     # @return [String, nil]
-    def served_expected_by(served, target: nil)
-      ServedModel.expected_by(target || @host_registry.resolve(@effective_model_name), served)
-    rescue StandardError
-      nil
+    def served_expected_by(served)
+      model_setting(nil) { |model| model.served_expected_by(served) }
     end
 
     def served_expected?(served) = !served_expected_by(served).nil?
@@ -1279,6 +1290,10 @@ module Samagotchi
     def session_state_snapshot
       served_pair = served_model(probe: false)
       metrics = @metrics.snapshot
+      # One resolve for the model's fields; nil when it doesn't resolve (the
+      # Bridge's /state and reset frames rely on this never raising): those
+      # fields are nil then, as their own rescues always gave.
+      model = model_setting(nil) { |resolved| resolved }
       {
         status: @session&.status,
         message_count: (@session&.messages || []).size,
@@ -1294,12 +1309,9 @@ module Samagotchi
         model_name: effective_model_ref,
         served_model: served_pair[0],
         served_model_for: served_pair[1],
-        served_expected_by: served_expected_by(served_pair[0]),
-        context_status: @last_context_status&.dup || saved_context_status(metrics[:context]),
-        llm_context: llm_context_summary,
-        thinking: thinking_explained&.summary,
-        reasoning_history: reasoning_history_explained&.summary,
-        toolkit: toolkit_summary,
+        served_expected_by: model&.served_expected_by(served_pair[0]),
+        context_status: @last_context_status&.dup || saved_context_status(metrics[:context], model: model),
+        **setting_chips(SessionSetting::ALL, model),
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
         recap_inactivity_seconds: @recap&.inactivity&.to_i
@@ -1494,7 +1506,8 @@ module Samagotchi
 
     def save_quietly(session)
       session.save(state_dir: session_state_dir)
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:turn, "turn_end_save_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       nil
     end
     private :save_quietly
@@ -1532,122 +1545,59 @@ module Samagotchi
     end
     private :store_answer_display
 
-    # ── The hook runtime (Hooks::Runtime) ─────────────────────────────────────
-
-    # The three things a hook can do beyond reading its event. Each gets the
-    # hook's label (event[:hook]) from the registry.
-    def hook_runtime
-      Hooks::Runtime.new(
-        notify: ->(text:, level:, hook:, fallback_for: nil) { hook_notify(text, level, hook, fallback_for: fallback_for) },
-        ask_user: ->(question:, options:, header:, allow_freeform:, hook:) { hook_ask_user(question, options, header, allow_freeform, hook) },
-        stop_turn: ->(reason:, hook:) { hook_stop_turn(reason, hook) },
-        steer: ->(text:, hook:) { steer(text, source: hook_source(hook)) },
-        stop_generation: ->(reason:, hook:) { hook_stop_generation(reason, hook) }
-      )
-    end
+    # ── The hook runtime (HookRoutes) ───────────────────────────────────────
+
+    # What a hook (Hooks::Runtime) and a plugin (Plugin::Host) can do beyond
+    # reading its event, routed to the UIs by HookRoutes; these forward.
+    def hook_runtime = @hook_routes.runtime
     private :hook_runtime
 
-    # What a steer is attributed to: the bundle of a bundle hook's label
-    # ("<file> (bundle <name>)"), the label of any other.
-    def hook_source(hook)
-      hook.to_s[/\(bundle (.+)\)\z/, 1] || hook.to_s
-    end
+    def hook_source(hook) = @hook_routes.source(hook)
     private :hook_source
 
     # What a notice may stand in for (hook_notify's fallback_for:).
-    NOTICE_FALLBACKS = %i[display editor].freeze
+    NOTICE_FALLBACKS = HookRoutes::NOTICE_FALLBACKS
 
-    # One line to the user (:hook_notice). During a turn it is a turn
-    # event: the turn's sink (the REPL) and the observers (bridge, log).
-    # Outside one (a plugin's command at the prompt) it is announced with
-    # between_turns: true, which every UI shows as cards are shown.
-    #
-    # +fallback_for+ names what the line stands in for (NOTICE_FALLBACKS):
-    # :display, the answer's display (AnswerDisplay), for a UI that doesn't
-    # render its links; :editor, a ref the viewer could open in its editor
-    # (Web::Capabilities#editor), for a UI or a viewer that can't. A UI that
-    # does leaves the line out; the others, the log among them, show it. An
-    # unknown value is dropped, so the line shows everywhere.
-    # +extra+: more fields for the UIs (a toolkit change's summary).
+    # One line to the user (:hook_notice), HookRoutes#notify.
     def hook_notify(text, level, hook, fallback_for: nil, extra: {})
-      level = (level || :info).to_sym
-      level = :info unless %i[info warn].include?(level)
-      notice = { type: :hook_notice, hook: hook.to_s, text: text.to_s, level: level,
-                 fallback_for: notice_fallback(fallback_for, hook) }.compact.merge(extra)
-      return @extension_load.hold(notice) && nil if @extension_load.loading?
-
-      in_turn, sink = @turn_state.in_turn_sink
-      if anytime_thread?
-        announce_anytime(notice.merge(between_turns: true))
-      elsif current_init_task
-        announce(notice.merge(between_turns: true))
-      elsif in_turn
-        emit_event(sink, notice)
-      else
-        announce_or_hold(notice.merge(between_turns: true))
-      end
-      nil
+      @hook_routes.notify(text, level, hook, fallback_for: fallback_for, extra: extra)
     end
     private :hook_notify
 
-    # A known fallback_for (a String is symbolized), else nil; an unknown
-    # one is logged once at debug.
-    def notice_fallback(value, hook)
-      return if value.nil?
-
-      fallback = value.to_s.to_sym
-      return fallback if NOTICE_FALLBACKS.include?(fallback)
-
-      @unknown_fallbacks ||= Set.new
-      Log.debug(:hooks, "notice_unknown_fallback", hook: hook.to_s, value: value.to_s) if @unknown_fallbacks.add?(fallback)
-      nil
-    end
-    private :notice_fallback
-
-    # A guardrails line to the user after load (:guardrail_warning, as the
-    # load failures show): a running turn's event, else announced.
-    def guardrail_notify(message)
-      event = { type: :guardrail_warning, message: message.to_s }
-      in_turn, sink = @turn_state.in_turn_sink
-      in_turn ? emit_event(sink, event) : announce_or_hold(event)
-      nil
-    end
+    def guardrail_notify(message) = @hook_routes.guardrail_notify(message)
     private :guardrail_notify
 
-    # A question through the question flow (REPL sync handler, attached TUI,
-    # web), single-select, kind "hook". A --non-interactive run has no one
-    # to ask: nil at once. Anything but an answer (a sync handler's text, no
-    # answer, cancelled) is nil too.
     # @return [Hash, nil] {selected:, freeform:, selected_indices:}
     def hook_ask_user(question, options, header, allow_freeform, hook)
-      @question_desk.ask_for_hook(question, options, header, allow_freeform, hook)
+      @hook_routes.ask_user(question, options, header, allow_freeform, hook)
     end
     private :hook_ask_user
 
-    # Cancel the running turn (reason :hook), after a notice that says why.
-    # The gate denies the rest of a tool batch once the controller is
-    # cancelled; the next request ends the turn as :turn_canceled.
     # @return [Boolean] true when a running turn was cancelled now
-    def hook_stop_turn(reason, hook)
-      ctrl = active_cancel_controller
-      return false unless ctrl && !ctrl.cancelled?
-
-      hook_notify("stopped the turn: #{reason}", :warn, hook)
-      ctrl.cancel!(:hook, { by: hook_source(hook), reason: reason.to_s })
-    end
+    def hook_stop_turn(reason, hook) = @hook_routes.stop_turn(reason, hook)
     private :hook_stop_turn
 
-    # Cut the streaming generation (reason :hook); the turn goes on and asks
-    # the model again (the loops' cut path). No notice: the plugin posts its
-    # own. The bundle and +reason+ go to the log and the retry's nudge.
     # @return [Boolean] true when a streaming generation was cut now
-    def hook_stop_generation(reason, hook)
-      ctrl = active_cancel_controller
-      return false unless ctrl
+    def hook_stop_generation(reason, hook) = @hook_routes.stop_generation(reason, hook)
+    private :hook_stop_generation
 
-      ctrl.cancel_generation!(:hook, { by: hook_source(hook), reason: reason.to_s })
+    # The hook routes (see #initialize for when).
+    def build_hook_routes
+      HookRoutes.new(
+        extension_load: -> { @extension_load },
+        in_turn_sink: -> { @turn_state.in_turn_sink },
+        anytime_thread: -> { anytime_thread? },
+        announce_anytime: ->(event) { announce_anytime(event) },
+        init_task: -> { current_init_task },
+        announce: ->(event) { announce(event) },
+        announce_or_hold: ->(event) { announce_or_hold(event) },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        question_desk: -> { @question_desk },
+        cancel_controller: -> { active_cancel_controller },
+        steer: ->(text, source) { steer(text, source: source) }
+      )
     end
-    private :hook_stop_generation
+    private :build_hook_routes
 
     # ── Ask-user-question (structured qualification) ──────────────────────────
 
@@ -1717,15 +1667,17 @@ module Samagotchi
     # the chat loop's leaves out the raw-prompt tool text, since its tools go
     # as schemas. Built once per loop (and again after a model switch) so the
     # prompt prefix, and the server's KV cache for it, stay stable.
-    # @param target [HostRegistry::ModelTarget, nil]
+    # @param model [EffectiveModel, nil]
     # @return [String]
     # The native prompt depends on the thinking level too (Gemma's token,
-    # Qwen's turn preamble): a level change builds it again.
-    def system_prompt(target = nil)
-      target ||= @host_registry.resolve(@effective_model_name)
-      chat = target.entry.chat?
-      level = chat ? nil : thinking_level(target)
-      prompt = @prompt_builder.build(chat: chat, thinking: level, layers: llm_context_layers(target))
+    # Qwen's turn preamble): a level change builds it again. A build that
+    # misses the cache names the model and the level through its own
+    # lambdas (#model_identity, #turn_thinking), which resolve again.
+    def system_prompt(model = nil)
+      model ||= effective_model
+      chat = model.chat?
+      level = chat ? nil : thinking_level(model)
+      prompt = @prompt_builder.build(chat: chat, thinking: level, layers: model.llm_context_layers(llm_context_session_args))
       # The memory indexes this prompt holds: /stats, the snapshot, analytics.json.
       @metrics.memory_index = @prompt_builder.memory_index
       # The model notes it carries: the session records them (/stats, /model, the web).
@@ -1733,16 +1685,6 @@ module Samagotchi
       prompt
     end
 
-    # The LLM context layers +target+'s turns run under: the native prompt
-    # declares the tools they add (forget_outputs under forget), so a
-    # model switch may change the tool list. [] under none.
-    def llm_context_layers(target)
-      LLMContextStrategy.resolve(target, names: model_lookup_names(target), **llm_context_session_args).active_layers
-    rescue StandardError
-      []
-    end
-    private :llm_context_layers
-
     # The base prompt (specs, plugins' declarations).
     def assist_system_prompt(chat: false, thinking: nil)
       @prompt_builder.base(chat: chat, thinking: thinking)
@@ -2073,14 +2015,16 @@ module Samagotchi
     # sampling and thinking, the thinking resolved before the hooks run.
     # The model name is added in #generate, after the hooks that may switch
     # the model.
+    # One resolve for all of them: nothing runs between them that could
+    # change what a resolve gives.
     def turn_settings(session)
-      vision = turn_vision(session)
-      sampling = turn_sampling
-      thinking_target = @host_registry.resolve(@effective_model_name)
-      @turn_thinking = [thinking_level(thinking_target), thinking_target]
-      announce_thinking_level(*@turn_thinking)
-      LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: @turn_thinking.first,
-                            reasoning_history: reasoning_history_level(thinking_target), model_name: nil,
+      model = effective_model
+      vision = turn_vision(session, model)
+      sampling = model.sampling
+      level = thinking_level(model)
+      @thinking_notices.turn_started(level, model.target)
+      LLM::TurnSettings.new(vision: vision, sampling: sampling, thinking: level,
+                            reasoning_history: reasoning_history_level(model), model_name: nil,
                             window_setting: nil, llm_context: nil, price: nil)
     end
     private :turn_settings
@@ -2102,12 +2046,12 @@ module Samagotchi
     def warm_up_next_turn(turn, result)
       return if result.canceled? || result.resumable?
 
-      target = @host_registry.resolve(@effective_model_name)
-      client = target.client
-      return unless warmup_target?(target, client)
+      model = effective_model
+      client = model.client
+      return unless warmup_target?(model, client)
       return if reminders_due? || @turn_state.carried_steers? || @next_turn_waiting&.call
 
-      messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(target) })
+      messages = ContextNote.with_system_head(turn.session.messages.dup, { role: "system", content: system_prompt(model) })
       # Under the next turn's strategy (a /model switch may have changed it);
       # the last turn's when it can't be resolved.
       prompt, images = @kernel.warmup_prompt(messages, llm_context: turn_llm_context || @kernel.turn_settings&.llm_context)
@@ -2124,8 +2068,8 @@ module Samagotchi
     # Never a paid or remote host (cache.warmup auto means local only), nor
     # the chat loop (Splash keeps its own cache; llama.cpp's chat path is
     # not measured), nor a non-llama.cpp transport.
-    def warmup_target?(target, client)
-      return false if target.entry.chat? || target.entry.remote?
+    def warmup_target?(model, client)
+      return false if model.chat? || model.entry.remote?
       return false unless client.respond_to?(:warm_up) && client.respond_to?(:transport) && client.transport.native?
 
       PromptWarmup.enabled?
@@ -2166,16 +2110,19 @@ module Samagotchi
 
     # Ask the effective model's backend.
     def generate(turn, max_iterations:, max_tool_output_chars:, pending_input:)
-      sync_kernel_client!
+      # One resolve for the request: nothing runs between these reads that
+      # could change what a resolve gives (the hooks ran before).
+      model = effective_model
+      sync_kernel_client!(model)
       # Route model name as bare (without host prefix) to the transport;
       # host selection already done via active client.
-      bare_for_backend = bare_model_name(@effective_model_name)
+      bare_for_backend = bare_model_name(model.name)
       # The turn's settings, set once here. The chat loop dispatches tools
       # through the kernel without its #run: tag those dumps with this
       # turn's model, not the last native one.
-      explained = llm_context_explained
-      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting,
-                                                 llm_context: explained&.resolved, price: turn_price)
+      explained = model.llm_context_explained(llm_context_session_args)
+      @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: model.window_setting,
+                                                 llm_context: explained&.resolved, price: model.price)
       log_llm_context(explained)
 
       turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
@@ -2183,7 +2130,7 @@ module Samagotchi
       # end keeps it, so a Continue resumes this run.
       run_start = turn.messages.length
       reasoning_since = resumed_run_start(turn, run_start)
-      result = backend.complete(
+      result = backend(model).complete(
         messages: turn.messages,
         max_iterations: turn.limit,
         on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller),
@@ -2228,8 +2175,8 @@ module Samagotchi
       # Persist deduped used memories onto the session for Web + reload.
       begin
         session.used_memory_names = used_memory_names
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Log.warn(:memory, "used_memories_store_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       end
       # Notify live observers of the updated memory list (so yellow bar refreshes
       # even without a tool_call event if the preload was the only addition).
@@ -2238,8 +2185,8 @@ module Samagotchi
 
       begin
         emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names })
-      rescue StandardError
-        nil
+      rescue StandardError => e
+        Log.warn(:memory, "used_memories_emit_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       end
     end
     private :publish_used_memories
@@ -2397,164 +2344,30 @@ module Samagotchi
 
     # The turn's VisionContext: the session's images folder, and whether the
     # effective model can see images, asked only when a request carries one.
-    def turn_vision(session)
-      target = @host_registry.resolve(@effective_model_name)
+    def turn_vision(session, model = effective_model)
       VisionContext.new(session_dir: Session.session_dir(session.id, state_dir: session_state_dir),
-                        capability: lambda {
-                          VisionSupport.for(target, profile: profile, adapter: vision_adapter(target), names: model_lookup_names(target))
-                        })
+                        capability: -> { model.vision_support(profile) })
     end
 
     # The effective model's request parameters (hosts: and models:
     # sampling), read per turn: /model can change the model between turns.
-    def turn_sampling
-      target = @host_registry.resolve(@effective_model_name)
-      SamplingSettings.for(target, names: model_lookup_names(target))
-    rescue StandardError
-      SamplingSettings::EMPTY
-    end
+    def turn_sampling = model_setting(SamplingSettings::EMPTY, &:sampling)
 
     # The effective model's thinking level (Thinking.resolve), read each turn.
-    def turn_thinking
-      thinking_level(@host_registry.resolve(@effective_model_name))
-    rescue StandardError
-      Thinking::DEFAULT
-    end
-
-    # An effort on a native host, which has no knob for it: said once per
-    # session and host.
-    def announce_thinking_level(level, target)
-      return if target.entry.chat? || Thinking.native(level, profile).honoured
-
-      thinking_notice_once(:unsupported, target, :info,
-                           "#{level} isn't supported by native #{profile.name} on #{target.entry.name}; " \
-                           "thinking stays as the model has it")
-    rescue StandardError
-      nil
-    end
-
-    # An effort on a llama.cpp chat host whose chat template takes none
-    # (its /props says so): said once per session and host, as for a native
-    # host. Read from the /props answer the turn's window probe left in the
-    # cache, so it asks the server nothing.
-    def announce_effort_ignored
-      level, target = @turn_thinking
-      return unless target&.entry&.chat? && Thinking::EFFORTS.include?(level)
-
-      client = target.client
-      props = client.cached_server_props(model: target.bare_model)
-      return unless Thinking.effort_ignored?(level, props)
-
-      thinking_notice_once(:unsupported, target, :info,
-                           "#{level} isn't supported by #{target.bare_model}'s chat template on #{target.entry.name} " \
-                           "(/props: supports_reasoning_effort false); thinking stays as the model has it")
-    rescue StandardError
-      nil
-    end
+    def turn_thinking = model_setting(Thinking::DEFAULT) { |model| thinking_level(model) }
 
-    # Whether this generation's thinking lane said anything: nil while it
-    # streamed none, false while only whitespace (Gemma 4's empty thought
-    # with thinking off), true once a real thought came.
-    def note_generation_thought(thinking)
-      return if thinking.empty?
-
-      @generation_thought ||= thinking.match?(/\S/)
-    end
-
-    # Thinking off, and the model thought anyway: logged each time, said
-    # once per session and host. A thinking lane of whitespace alone is no
-    # thought.
-    def check_thinking_honoured(event)
-      level, target = @turn_thinking
-      chars = event[:thinking_chars].to_i
-      return unless level == :off && chars.positive? && target
-      return if @generation_thought == false
-
-      Log.warn(:model, "thinking_not_honoured", level: level, host: target.entry.name, model: target.bare_model, chars: chars)
-      thinking_notice_once(:not_honoured, target, :warn,
-                           "off wasn't honoured by #{target.bare_model} on #{target.entry.name} " \
-                           "(#{chars} chars of thinking); a sampling: override on the host or model may turn it off " \
-                           "(see Thinking in docs/configuration.md)")
-    rescue StandardError
-      nil
-    end
-
-    # The host refused the level's request fields (gpt-oss can't turn
-    # thinking off) and the chat loop sent the request without them: said
-    # once per session and host, standing in for the not-honoured notice.
-    def thinking_refused(event)
-      _level, target = @turn_thinking
-      return unless target
-
-      Log.warn(:model, "thinking_refused", level: event[:level], host: target.entry.name, model: event[:model],
-                                           detail: event[:detail])
-      (@thinking_notices ||= Set.new) << [@session&.id, target.entry.name, :not_honoured]
-      thinking_notice_once(:refused, target, :warn,
-                           "#{target.entry.name} refused thinking: #{event[:level]} for #{event[:model]} (#{event[:detail]}); " \
-                           "sent without it, so thinking stays as the model has it")
-    rescue StandardError
-      nil
-    end
-
-    # The host refused a sampling field (the empty-answer retry's
-    # temperature on a model that takes none) and the chat loop asked again
-    # without them, as it will for the model from now on: a log line.
-    def sampling_refused(event)
-      Log.info(:model, "sampling_refused", model: event[:model], detail: event[:detail])
-    rescue StandardError
-      nil
-    end
-
-    # The host refused the model's reasoning sent back (reasoning_history)
-    # and the chat loop asked the step again without it, as it will from
-    # now on: logged, and said once per session and host.
-    def reasoning_history_refused(event)
-      _level, target = @turn_thinking
-      return unless target
-
-      Log.warn(:model, "reasoning_history_refused", level: event[:level], host: target.entry.name, model: event[:model],
-                                                    detail: event[:detail])
-      return unless (@thinking_notices ||= Set.new).add?([@session&.id, target.entry.name, :reasoning_history_refused])
-
-      hook_notify("#{target.entry.name} refused reasoning sent back (reasoning_history: #{event[:level]}) for " \
-                  "#{event[:model]} (#{event[:detail]}); sent without it from now on", :warn, "reasoning history")
-    rescue StandardError
-      nil
-    end
-
-    def thinking_notice_once(kind, target, level, text)
-      key = [@session&.id, target.entry.name, kind]
-      return unless (@thinking_notices ||= Set.new).add?(key)
-
-      hook_notify(text, level, "thinking")
-    end
-
-    # +target+'s ReasoningHistory level, the session's own first; the
+    # +model+'s ReasoningHistory level, the session's own first; the
     # default when it can't be resolved.
-    def reasoning_history_level(target)
-      ReasoningHistory.resolve(target, names: model_lookup_names(target), session: reasoning_history_override).first
-    rescue StandardError
-      ReasoningHistory::DEFAULT
-    end
+    def reasoning_history_level(model) = model.reasoning_history(own: reasoning_history_override)
 
-    # +target+'s thinking level (Thinking.resolve), the session's own first.
-    def thinking_level(target)
-      Thinking.resolve(target, names: model_lookup_names(target), session: thinking_override).first
-    rescue StandardError
-      Thinking::DEFAULT
-    end
-
-    def vision_adapter(target)
-      target.entry.chat? ? @host_registry.adapter_for(target.entry) : nil
-    rescue StandardError
-      nil
-    end
+    # +model+'s thinking level (Thinking.resolve), the session's own first.
+    def thinking_level(model) = model.thinking(own: thinking_override)
 
     # A model known not to see images fails a turn with images up front.
     def refuse_images!(vision)
       return if vision.sendable?
 
-      host = @host_registry.resolve(@effective_model_name).entry.name
+      host = effective_model.host_name
       raise LLM::VisionUnsupported.new("#{host}: #{vision.refusal_reason}", host: host)
     end
 
@@ -2649,14 +2462,14 @@ module Samagotchi
       session.messages = messages
     end
 
-    # Pick the loop for a target; the chat loop is pointed at the target
-    # host's adapter (one per host, kept for its cached model list).
-    def backend_for(target)
-      return @native_backend unless target.entry.chat?
+    # Pick the loop for +model+ (EffectiveModel); the chat loop is pointed
+    # at its host's adapter (one per host, kept for its cached model list).
+    def backend_for(model)
+      return @native_backend unless model.chat?
 
       @chat_backend_mutex.synchronize do
         @chat_backend ||= LLM::ChatLoop.new(kernel: @kernel, stable_length: ->(text) { @prompt_builder.stable_length(text) })
-        @chat_backend.adapter = @host_registry.adapter_for(target.entry)
+        @chat_backend.adapter = @host_registry.adapter_for(model.entry)
         @chat_backend.session_id = session&.id
         @chat_backend
       end
@@ -2676,12 +2489,16 @@ module Samagotchi
           add_init_task(bundle: bundle, label: label, plugin_label: plugin_label, provides_tools: provides_tools,
                         quiet: quiet, timeout: timeout, failed: failed, &block)
         },
-        toolkits: @plugin_kits
+        toolkits: @toolkit_binding.plugin_kits,
+        tool_index: @tool_index,
+        peer_sources: @peer_sources
       )
       # What plugins show while they load (an MCP server that didn't
       # start) waits for the first turn, beside the load warnings: no UI
       # is there yet, and the Engine isn't built.
       @extension_load.load_plugins(registries, failures: @plugin_failures)
+      # Declared once, from what the sources published while they loaded.
+      @tool_index.declare(@tools, failures: @plugin_failures)
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
@@ -2699,100 +2516,42 @@ module Samagotchi
     end
     public :apply_staged_tools!
 
-    # The kits a session's toolkit resolves against: the built-ins, config's
-    # toolkit.kits, the plugins' (Toolkit.kits). Config's are read once per
-    # process, like the plugins': an edit to toolkit.kits never changes a
-    # live session's tools mid-session (a new worker reads it).
-    # @param errors [Array<String>] gets a line per config kit left out
-    # @return [Hash{String => Toolkit::Kit}]
-    def toolkit_kits(errors = [])
-      @config_kits = Toolkit.config_kits unless defined?(@config_kits)
-      Toolkit.kits(config: @config_kits, plugins: @plugin_kits, errors: errors)
-    end
-
-    # The session's toolkit resolved (Toolkit::Resolved): what its next
-    # turn declares. A plain full toolkit is nil, the Registry's "every tool".
-    def resolved_toolkit(session, errors = [])
-      resolved = Toolkit.of(session&.toolkit).resolve(toolkit_kits(errors))
-      resolved.everything? ? nil : resolved
-    end
+    # The session's toolkit (ToolkitBinding): the kits, what its next turn
+    # declares, ctx.use_toolkit and the turn-start apply.
+    def toolkit_kits(errors = []) = @toolkit_binding.kits(errors)
+    def resolved_toolkit(session, errors = []) = @toolkit_binding.resolved(session, errors)
+    def toolkit_explained(toolkit = nil) = @toolkit_binding.explained(toolkit)
+    def toolkit_summary = @toolkit_binding.summary
 
     # The tools this session registered (Tools::Registry), declared or not.
     attr_reader :tools
 
-    # +toolkit+ (the session's by default) as its next turn would declare
-    # it (/toolkit, the UIs' chip).
-    # @return [Toolkit::Explained]
-    def toolkit_explained(toolkit = nil)
-      toolkit ||= Toolkit.of(@session&.toolkit)
-      resolved = toolkit.resolve(toolkit_kits)
-      filter = resolved.everything? ? nil : resolved
-      Toolkit::Explained.new(toolkit: toolkit, resolved: resolved, declared: @tools.entries(toolkit: filter),
-                             left_out: @tools.left_out_names(toolkit: filter), pending: filter != @tools.toolkit)
-    end
-
-    # The session's toolkit for the UIs (the snapshot, command_ran): nil on
-    # full, or with no session.
-    def toolkit_summary
-      @session && toolkit_explained.summary
-    end
     public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
 
-    # A plugin's ctx.use_toolkit: put the session on toolkit +name+, saved,
-    # when it has no model reply yet and no turn runs (D3: no confirm from
-    # plugins), and tell the user as /toolkit would; it applies at the next
-    # turn's start.
+    # A plugin's ctx.use_toolkit (ToolkitBinding#use).
     # @return [Boolean] whether it was staged
     # @raise [ArgumentError] an unknown toolkit
-    def use_toolkit(name)
-      raise ArgumentError, "no toolkit named #{name}" unless toolkit_kits.key?(name)
-      return false if @session.nil? || turn_running? || history?
-
-      toolkit = Toolkit.new(name: name)
-      return true if @session.toolkit == toolkit
-
-      @session.toolkit = toolkit
-      @session.save(state_dir: session_state_dir)
-      hook_notify("toolkit: #{name} from the next turn's start", :info, "toolkit", extra: { toolkit: toolkit_summary })
-      true
-    end
+    def use_toolkit(name) = @toolkit_binding.use(name)
     public :use_toolkit
 
-    # Resolve the session's toolkit into the Registry, on the turn thread at
-    # a turn's start (before its prompt is built), and build the prompts
-    # again when what it declares changed. A name that doesn't resolve (a
-    # typo, an uninstalled bundle) declares everything for now and says so
-    # once; the saved toolkit stays as it is.
+    # At a turn's start (ToolkitBinding#apply!).
     # @return [Boolean] whether the declared tools changed
-    def apply_toolkit!(session, on_event = nil)
-      errors = []
-      resolved = Toolkit.of(session&.toolkit).resolve(toolkit_kits(errors))
-      warn_toolkit(session, resolved, errors, on_event)
-      resolved = nil if resolved.everything?
-      return false if resolved == @tools.toolkit
-
-      @tools.toolkit = resolved
-      @prompt_builder&.reset!
-      true
-    end
+    def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
     private :apply_toolkit!
 
-    # The toolkit's load warnings, each once per process: a name that
-    # didn't resolve, config kits left out.
-    def warn_toolkit(session, resolved, errors, on_event)
-      lines = errors.dup
-      if resolved.fallback
-        lines << "#{Toolkit.of(session&.toolkit).label}: #{resolved.fallback}; this session declares every tool (full) " \
-                 "until it resolves"
-      end
-      @toolkit_warned ||= []
-      (lines - @toolkit_warned).each do |line|
-        @toolkit_warned << line
-        Log.warn(:config, "toolkit_unresolved", message: line)
-        emit_event(on_event, { type: :guardrail_warning, message: line, label: "toolkit" })
-      end
+    # The session's toolkit (see #initialize for when).
+    def build_toolkit_binding
+      ToolkitBinding.new(
+        tools: -> { @tools },
+        session: -> { @session },
+        state_dir: -> { session_state_dir },
+        can_stage: -> { !turn_running? && !history? },
+        reset_prompt: -> { @prompt_builder&.reset! },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        notify: ->(text, level, source, extra:) { hook_notify(text, level, source, extra: extra) }
+      )
     end
-    private :warn_toolkit
+    private :build_toolkit_binding
 
     # The tools changed (a plugin's chi.tools_changed!): the system prompts,
     # which declare them, are built again on the next turn.
@@ -2820,7 +2579,7 @@ module Samagotchi
         steer: ->(text, label) { steer(text, source: hook_source(label)) },
         stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
         stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
-        toolkit: -> { @session && Toolkit.of(@session.toolkit).name },
+        toolkit: -> { @toolkit_binding.name },
         declared_tools: -> { toolkit_explained.declared.map(&:name) },
         use_toolkit: ->(name) { use_toolkit(name) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
@@ -2891,7 +2650,7 @@ module Samagotchi
     # and bare model name, as a turn resolves them.
     # @return [IdleTarget]
     def session_model_recap_target
-      IdleTarget.of_model(@host_registry, @effective_model_name)
+      IdleTarget.of_model(@host_registry, effective_model_name)
     end
 
     # Build the idle reminders job. Always created (reminders are opt-in
@@ -2938,29 +2697,26 @@ module Samagotchi
         @steer_cut.observe(event, progress)
         case event[:type]
         when :generation_started
-          @generation_thought = nil
+          @thinking_notices.generation_started
           watch&.started(event[:iteration])
         when :generation_retrying
           # A dropped stream's step asked again: it streams from the start.
           if event[:restarted]
-            @generation_thought = nil
+            @thinking_notices.generation_started
             watch&.started(event[:iteration], restarted: true)
           end
-        when :generation_chunk then note_generation_thought(progress[:thinking])
+        when :generation_chunk then @thinking_notices.note_thought(progress[:thinking])
         end
         # The chat loop asked again without the thinking fields or the
         # reasoning sent back: a notice, not an event of its own.
-        next thinking_refused(event) if event[:type] == :thinking_refused
-        next reasoning_history_refused(event) if event[:type] == :reasoning_history_refused
-        next sampling_refused(event) if event[:type] == :sampling_refused
+        next @thinking_notices.thinking_refused(event) if event[:type] == :thinking_refused
+        next @thinking_notices.reasoning_history_refused(event) if event[:type] == :reasoning_history_refused
+        next @thinking_notices.sampling_refused(event) if event[:type] == :sampling_refused
 
         event = with_generation_report(event) if event[:type] == :generation_completed
         emit_event(on_event, event)
         watch.feed(**progress) if watch && progress
-        if event[:type] == :generation_completed
-          check_thinking_honoured(event)
-          announce_effort_ignored
-        end
+        @thinking_notices.generation_completed(event) if event[:type] == :generation_completed
       end
     end
 
@@ -2973,7 +2729,8 @@ module Samagotchi
     def with_generation_report(event)
       report = @metrics.finish_generation
       event.merge(speed: report.speed&.to_h, tokens: report.tokens, served_expected_by: served_expected_by(event[:served_model]))
-    rescue StandardError
+    rescue StandardError => e
+      Log.warn(:turn, "generation_report_failed", error: e.class.name, msg: e.message.to_s[0, 200])
       event
     end
     private :with_generation_report
@@ -2990,7 +2747,8 @@ module Samagotchi
       # Capture used memories synchronously in the turn thread.
       read_names = begin
         @used_memories.capture(event, muted: @muted_memory_names)
-      rescue StandardError
+      rescue StandardError => e
+        Log.warn(:memory, "used_memories_capture_failed", error: e.class.name, msg: e.message.to_s[0, 200])
         nil
       end
       # Turn-scoped sink: receives the event hash as the stream handler
@@ -2999,8 +2757,9 @@ module Samagotchi
       if on_event
         begin
           on_event.call(event)
-        rescue StandardError
+        rescue StandardError => e
           # Sink errors must not break the kernel loop (same as KernelLoop's own handling)
+          Log.warn(:turn, "sink_failed", event_type: event[:type].to_s, error: e.class.name, msg: e.message.to_s[0, 200])
         end
       end
 
@@ -3014,38 +2773,13 @@ module Samagotchi
       emit_event(on_event, { type: :used_memories_updated, used_memory_names: used_memory_names, read_names: read_names })
     end
 
-    # The window as the target's loop would see it (see ChatLoop#context_window:
-    # a remote chat host has no /props, only its model list).
-    def current_context_window(target)
-      client = target.client
-      adapter = nil
-      if target.entry.chat?
-        adapter = @host_registry.adapter_for(target.entry)
-        client = nil if adapter.remote?
-      end
-      ContextWindow.resolve(client: client, model: target.bare_model, adapter: adapter,
-                            setting: ContextWindow.setting(target, names: model_lookup_names(target)))
-    rescue StandardError
-      nil
-    end
-
     # The effective model's models:/hosts: window_tokens, read per turn
     # (after the hooks that may switch the model).
-    def turn_window_setting
-      target = @host_registry.resolve(@effective_model_name)
-      ContextWindow.setting(target, names: model_lookup_names(target))
-    rescue StandardError
-      nil
-    end
+    def turn_window_setting = model_setting(nil, &:window_setting)
 
     # The effective model's price on its host (hosts.<name>.models.<id>.price),
     # by the requested id, never the served one; read per turn as the window is.
-    def turn_price
-      target = @host_registry.resolve(@effective_model_name)
-      target.entry.models&.dig(target.bare_model.to_s.strip.downcase)&.price
-    rescue StandardError
-      nil
-    end
+    def turn_price = model_setting(nil, &:price)
 
     # The LLM context strategy the next turn runs under: the session's own
     # (Session#llm_context), else the effective model's (models:/hosts:
@@ -3059,57 +2793,82 @@ module Samagotchi
     private :llm_context_session_args
 
     # See #served_model. A report for another name (before a /model switch)
-    # doesn't count. Without a target, no probe. A remote chat host has no
-    # /props: nil until a turn.
-    def served_model_for(snapshot, target: nil)
-      asked = bare_model_name(@effective_model_name)
+    # doesn't count. Without a model (EffectiveModel), no probe. A remote
+    # chat host has no /props: nil until a turn. The name asked is never
+    # resolved (HostRegistry#bare_name), so it holds on a broken resolve.
+    def served_model_for(snapshot, model: nil)
+      asked = bare_model_name(model ? model.name : effective_model_name)
       return [snapshot[:served_model], asked] if snapshot[:served_model] && snapshot[:served_model_for] == asked
-      return [nil, nil] unless target
+      return [nil, nil] unless model
 
-      client = target.client
-      if target.entry.chat?
-        adapter = @host_registry.adapter_for(target.entry)
-        return [nil, nil] if adapter.remote?
-      end
-      served = ServedModel.from_props(client.server_props(model: target.bare_model))
-      served ? [served, asked] : [nil, nil]
+      model.served_from_props(asked)
+    # Only bare_model_name and the snapshot lookup are left to fail here:
+    # the probe's failure is EffectiveModel#served_from_props's.
     rescue StandardError
       [nil, nil]
     end
 
-    # What a local native host's cached /props names, when it isn't the
-    # model asked for; nil for a chat or remote host, or before any probe.
-    def prompt_served_model(target)
-      entry = target.entry
-      return nil if entry.nil? || entry.chat? || entry.remote? || !target.client.respond_to?(:cached_server_props)
+    # The window as +model+'s loop would see it (EffectiveModel#context_window).
+    def current_context_window(model) = model.context_window
 
-      served = ServedModel.from_props(target.client.cached_server_props(model: target.bare_model))
-      served if ServedModel.differs?(target.bare_model, served)
-    rescue StandardError
-      nil
+    # +settings+' chips (SessionSetting), the model's from +model+ (nil
+    # when it doesn't resolve): /stats, the session state, a :command_ran.
+    def setting_chips(settings, model)
+      settings.to_h { |setting| [setting.key, setting.model? ? setting.chip_for(model, @session) : toolkit_summary] }
     end
 
-    # ── Prompt profile ─────────────────────────────────────────────────────────
+    # The effective model now (EffectiveModel.of): resolved on each call,
+    # never kept (config.yml, a model listing and another process's saved
+    # lists all move a resolve). Raises as HostRegistry#resolve does.
+    # @return [EffectiveModel]
+    def effective_model(choice = @model_choice) = EffectiveModel.of(@host_registry, choice)
 
-    def resolve_profile
-      if @given_profile
-        return ModelProfile::Resolution.new(profile: @given_profile, source: :given, detail: nil, retry: false)
+    # The block's answer for the effective model, or +fallback+ when the
+    # model doesn't resolve: the readers whose rescue always covered the
+    # resolve too. Each setting's own failure is the EffectiveModel's.
+    def model_setting(fallback)
+      # One read: the log line names the model that failed, even if a
+      # /model switched it meanwhile.
+      choice = @model_choice
+      model = begin
+        effective_model(choice)
+      rescue StandardError => e
+        return EffectiveModel::Unresolved.fallback(:effective_model_unresolved, choice.name, e, fallback)
       end
+      yield model
+    end
 
-      target = @host_registry.resolve(@effective_model_name)
-      ModelProfile.resolve(names: model_lookup_names(target), entry: target.entry, client: target.client, bare_model: target.bare_model)
+    # ── Prompt profile ─────────────────────────────────────────────────────────
+
+    # +choice+'s profile (ModelProfile.resolve; may probe /props), or the
+    # one given to .new.
+    def resolve_profile(choice)
+      given = @given_profile
+      return ModelProfile::Resolution.new(profile: given, source: :given, detail: nil, retry: false) if given
+
+      EffectiveModel.of(@host_registry, choice).profile_resolution
     end
 
-    # The names a models: entry may be under (HostRegistry#lookup_names):
-    # the model as typed at start or at the last /model, and what it became.
-    def model_lookup_names(target)
-      @host_registry.lookup_names(@typed_model_name, resolved: @effective_model_name, target: target)
+    # Keeps +resolution+ as +choice+'s and applies it, unless the model
+    # switched while it was resolved (a /stats on a Bridge thread probing
+    # as a /model ran): then it is only returned, and the new model's is
+    # resolved on its first need.
+    # @return [ModelProfile::Resolution]
+    def store_profile(choice, resolution)
+      @profile_mutex.synchronize do
+        return resolution unless @model_choice.equal?(choice)
+
+        apply_profile(resolution)
+        @profile_resolution = [choice, resolution]
+      end
+      resolution
     end
 
     # Everything that holds a profile follows the resolution: the kernel's
     # prompt format and parser, and the system prompts built for the old one.
     def apply_profile(resolution)
-      @prompt_builder&.reset! if @profile_resolution && @profile_resolution.profile.name != resolution.profile.name
+      kept = @profile_resolution&.last
+      @prompt_builder&.reset! if kept && kept.profile.name != resolution.profile.name
       @kernel.use_profile!(resolution)
       resolution
     end
@@ -3118,11 +2877,10 @@ module Samagotchi
     # server probe failed (unreachable, or 503 while loading a model). A
     # profile that changes here drops the cached system prompts.
     def refresh_profile!
-      if @profile_resolution&.retry?
-        @profile_resolution = apply_profile(resolve_profile)
-      else
-        profile_resolution
-      end
+      choice, kept = @profile_resolution
+      return profile_resolution unless choice.equal?(@model_choice) && kept.retry?
+
+      store_profile(choice, resolve_profile(choice))
     end
   end
 end