samagotchi 0.5.0 → 0.6.0

data/lib/samagotchi/engine.rb

@@ -33,6 +33,7 @@ require_relative "system_prompt"
 require_relative "session_metrics"
 require_relative "token_usage"
 require_relative "idle_recap"
+require_relative "recap_setup"
 require_relative "idle_reminders"
 require_relative "idle_scheduler"
 require_relative "hooks"
@@ -50,6 +51,9 @@ require_relative "sampling_settings"
 require_relative "thinking"
 require_relative "answer_display"
 require_relative "edit_preview"
+require_relative "question_desk"
+require_relative "guardrail_wiring"
+require_relative "plugin_tasks"
 
 module Samagotchi
   # Engine owns the core agent logic: system prompt construction, tool
@@ -61,7 +65,7 @@ module Samagotchi
     # Raised by #answer_question when the question it targets is no longer
     # open (never asked, superseded, already answered or cancelled). A subclass
     # of ArgumentError for existing callers; transports map it to 409 Conflict.
-    class QuestionNotPending < ArgumentError; end
+    QuestionNotPending = QuestionDesk::NotPending
 
     # Build a system prompt string for the given profile.
     # Used by specs and inspection.
@@ -118,11 +122,31 @@ module Samagotchi
       # 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.
-      @guardrail_failures = Guardrails::LoadFailures.new
-      @guardrail_rules_mutex = Mutex.new
+      @guardrail_wiring = GuardrailWiring.new(
+        scratch: @scratch,
+        hooks: -> { @hooks },
+        tools: -> { @tools },
+        session: -> { @session },
+        model_key: -> { @model_key },
+        cancelled: -> { !!active_cancel_controller&.cancelled? },
+        ask: ->(fields) { open_question(fields) }
+      )
+      @guardrail_failures = @guardrail_wiring.failures
       # Plugins that failed to load: announced apart, as plugins (not
       # guardrails: no tool call is denied for them).
       @plugin_failures = Guardrails::LoadFailures.new
+      # The question flow (ask_user_question, hooks' and plugins' ask_user,
+      # approvals). Built before the hooks and plugins load: a plugin can ask
+      # during its load (answered nil then: the interface is still
+      # :non_interactive).
+      @question_desk = QuestionDesk.new(
+        session: -> { @session },
+        state_dir: -> { session_state_dir },
+        emit: ->(event) { emit_event(nil, event) },
+        cancel_controller: -> { active_cancel_controller },
+        interface: -> { interface },
+        user_input: ->(sid) { ArchiveStore.user_input(sid, state_dir: session_state_dir) }
+      )
       @hooks = load_hooks_from_config
       load_hooks_from_bundles
       # The tools this session offers (the prompts' declarations and the
@@ -143,11 +167,19 @@ module Samagotchi
       # commands running now (#spawn_anytime), which it waits for.
       @services = Plugin::Services.new
       @anytime_threads = []
-      # Plugins' tool sets from chi.replace_tools, by bundle, until the
-      # turn thread applies them (#apply_staged_tools!).
-      @staged_tools = {}
-      # chi.init tasks (#add_init_task), started by #start_init_tasks!.
-      @init_tasks = []
+      # chi.init tasks (#add_init_task), started by #start_init_tasks!, and
+      # plugins' tool sets from chi.replace_tools until the turn thread
+      # applies them (#apply_staged_tools!). Built before the plugins load.
+      @plugin_tasks = PluginTasks.new(
+        clock: -> { monotonic_now },
+        synchronize_events: ->(&block) { synchronize_events(&block) },
+        announce: ->(event) { announce(event) },
+        emit: ->(sink, event) { emit_event(sink, event) },
+        show_card: ->(**card) { show_card(**card) },
+        tools: -> { @tools },
+        notify: ->(text, level, source) { hook_notify(text, level, source) },
+        tools_changed: -> { tools_changed! }
+      )
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
@@ -190,30 +222,13 @@ module Samagotchi
       @kernel.question_handler = proc { |payload| request_question(payload) } if @kernel.respond_to?(:question_handler=)
       # Every tool call asks this gate first. The kernel is never rebuilt, so
       # it holds across model switches.
-      @guardrail_git = Guardrails::GitInfo.new
       self.guardrail_state_dir = Session.default_state_dir
       # list_sessions and send_note speak for whichever session runs now.
       @kernel.peers = PeerView.new(self) if @kernel.respond_to?(:peers=)
-      if @kernel.respond_to?(:guardrail_gate=)
-        @kernel.guardrail_gate = Guardrails::Gate.new(
-          -> { @hooks },
-          context_lookup: -> { guardrail_context },
-          model_key_lookup: -> { @model_key },
-          approver: ->(verdict) { request_approval(verdict) },
-          approvals_lookup: -> { @guardrail_approvals },
-          checks_lookup: -> { guardrail_checks },
-          cancelled_lookup: -> { !!active_cancel_controller&.cancelled? },
-          tools_lookup: -> { @tools }
-        )
-      end
+      @kernel.guardrail_gate = @guardrail_wiring.gate if @kernel.respond_to?(:guardrail_gate=)
       # What a hook can do beyond reading its event (event[:notify],
       # event[:ask_user], event[:stop_turn]): the Engine's routes to the UIs.
       @hooks.runtime = hook_runtime
-      # If session was resumed and has a pending_question, hydrate engine state
-      if @resume_session && @resume_session.pending_question
-        @pending_question = @resume_session.pending_question.dup
-        @session = @resume_session
-      end
       # The loop follows the effective model's host (its api:): the raw-prompt
       # NativeBackend, or the chat backend for openai hosts.
       @native_backend = LLM::NativeBackend.new(kernel: @kernel)
@@ -248,11 +263,9 @@ module Samagotchi
       # Reminder names the interactive REPL's IdleReminders callback marked due;
       # the REPL polls them to decide when to run a synthetic reminder turn.
       @due_reminder_names = []
-      @question_mutex = Monitor.new
-      @question_cv = @question_mutex.new_cond
-      @pending_question = nil
-      @question_answer = nil
-      @recap = build_recap(recap)
+      @recap = RecapSetup.build(recap, engine: self, host_registry: @host_registry,
+                                session_target: -> { session_model_recap_target },
+                                session_id: -> { @session&.id }, state_dir: -> { session_state_dir })
       # One shared poller for the whole idle layer (reminders + optional
       # recap). Both jobs read the activity seam above; the scheduler owns
       # the single background thread and isolates per-job failures.
@@ -587,135 +600,41 @@ module Samagotchi
 
     # ── Plugin init tasks (chi.init) ──────────────────────────────────────
 
-    # A plugin's slow setup (docs/plugins.md, Init tasks): run on its own
-    # thread once the owner can show it (#start_init_tasks!), announced as
-    # plugin_init_started / plugin_init_finished unless quiet. A turn waits
-    # for the running ones that provide tools before its first model request
-    # (#await_init_tasks), up to each one's timeout. +cancel+ is its own
-    # controller, cancelled only by #shutdown: a Ctrl-C ends a turn's wait,
-    # not the task.
-    InitTask = Struct.new(:id, :bundle, :label, :plugin_label, :provides_tools, :quiet, :timeout, :failed, :block,
-                          :cancel, :thread, :state, :started_at, keyword_init: true) do
-      # What the task's block reads: whether chi is shutting down.
-      def cancelled? = cancel.cancelled?
-    end
-
-    # How long a task may hold a turn when it gives no timeout.
-    INIT_TASK_TIMEOUT = 60.0
+    # A plugin's slow setup (docs/plugins.md, Init tasks): PluginTasks.
+    InitTask = PluginTasks::InitTask
+    INIT_TASK_TIMEOUT = PluginTasks::INIT_TASK_TIMEOUT
+    INIT_WAIT_POLL = PluginTasks::INIT_WAIT_POLL
 
     # Add a plugin's init task (Plugin::Api#init at commit); it starts with
     # #start_init_tasks!.
     def add_init_task(bundle:, label:, plugin_label:, provides_tools:, quiet:, timeout:, failed: nil, &block)
-      @lifecycle_mutex.synchronize do
-        @init_tasks << InitTask.new(id: "#{bundle}-#{@init_tasks.size + 1}", bundle: bundle.to_s, label: label.to_s,
-                                    plugin_label: plugin_label, provides_tools: provides_tools ? true : false,
-                                    quiet: quiet ? true : false, timeout: timeout || INIT_TASK_TIMEOUT, failed: failed,
-                                    block: block, cancel: CancellationController.new, state: :pending)
-      end
-      nil
+      @plugin_tasks.add(bundle: bundle, label: label, plugin_label: plugin_label, provides_tools: provides_tools,
+                        quiet: quiet, timeout: timeout, failed: failed, &block)
     end
 
-    # Start the init tasks not started yet, each on its own thread. The
-    # worker calls it once its Bridge is up, the REPL once it renders
-    # events, and every turn (a -p run has only that); later calls start
-    # nothing new.
+    # Start the init tasks not started yet, each on its own thread
+    # (PluginTasks#start!).
     def start_init_tasks!
-      @lifecycle_mutex.synchronize do
-        return if @shut_down
-
-        @init_tasks.each do |task|
-          next unless task.state == :pending
-
-          task.state = :starting
-          task.started_at = monotonic_now
-          task.thread = Thread.new { run_init_task(task) }
-          task.thread.report_on_exception = false
-        end
-      end
-      nil
+      @plugin_tasks.start!
     end
 
     # The running init tasks a UI shows (not the quiet ones), for a UI that
     # joins while they run (Bridge#snapshot, with the event log held).
     # @return [Array<Hash>] {bundle:, id:, label:}
     def init_tasks
-      @lifecycle_mutex.synchronize do
-        @init_tasks.select { |task| task.state == :running && !task.quiet }
-                   .map { |task| { bundle: task.bundle, id: task.id, label: task.label } }
-      end
+      @plugin_tasks.running
     end
 
-    # Wait for the running init tasks that provide tools, each up to its
-    # timeout from its start, while +controller+ isn't cancelled; tell the
-    # turn's sink what it waits for (:plugin_init_wait). A task that ends
-    # late or fails leaves the turn without its tools.
+    # Wait for the running init tasks that provide tools (PluginTasks#await).
     # @return [Boolean] whether it waited
     def await_init_tasks(controller = nil, on_event = nil)
-      waiting = @lifecycle_mutex.synchronize do
-        @init_tasks.select { |task| task.provides_tools && %i[starting running].include?(task.state) }
-      end
-      return false if waiting.empty?
-
-      emit_event(on_event, { type: :plugin_init_wait,
-                             tasks: waiting.map { |task| { bundle: task.bundle, id: task.id, label: task.label } } })
-      started = monotonic_now
-      loop do
-        now = monotonic_now
-        left = waiting.select { |task| %i[starting running].include?(task.state) && now < task.started_at + task.timeout }
-        break if left.empty? || controller&.cancelled?
-
-        sleep(INIT_WAIT_POLL)
-      end
-      Log.info(:plugins, "init_wait", ms: ((monotonic_now - started) * 1000).round,
-                                      cancelled: controller&.cancelled? ? true : nil)
-      true
+      @plugin_tasks.await(controller, on_event)
     end
 
-    INIT_WAIT_POLL = 0.05
-
     # The init task this thread runs, or nil.
-    def current_init_task = Thread.current[:"samagotchi_init_#{object_id}"]
+    def current_init_task = @plugin_tasks.current
     private :current_init_task
 
-    def run_init_task(task)
-      Thread.current[:"samagotchi_init_#{object_id}"] = task
-      synchronize_events do
-        task.state = :running
-        announce({ type: :plugin_init_started, bundle: task.bundle, id: task.id, label: task.label }) unless task.quiet
-      end
-      Log.info(:plugins, "init_started", bundle: task.bundle, id: task.id, label: task.label)
-      summary = task.block.call(task)
-      finish_init_task(task, ok: true, summary: summary.is_a?(String) ? summary : nil)
-    rescue StandardError => e
-      finish_init_task(task, ok: false, error: e.message)
-    end
-    private :run_init_task
-
-    def finish_init_task(task, ok:, summary: nil, error: nil)
-      Log.public_send(ok ? :info : :warn, :plugins, "init_finished", bundle: task.bundle, id: task.id, ok: ok,
-                                                                      ms: ((monotonic_now - task.started_at) * 1000).round,
-                                                                      msg: error)
-      shut_down = @lifecycle_mutex.synchronize { @shut_down }
-      synchronize_events do
-        task.state = ok ? :done : :failed
-        next if shut_down || (task.quiet && ok)
-
-        unless task.quiet
-          announce({ type: :plugin_init_finished, bundle: task.bundle, id: task.id, label: task.label, ok: ok,
-                     summary: summary, error: error }.compact)
-        end
-        # A failure stays on screen (and for a UI that joins later) as a
-        # card: a short title (the card shows the bundle beside it), the
-        # detail in the body.
-        unless ok
-          title = task.failed || "setup failed"
-          body = task.failed ? error.to_s : "#{task.label}: #{error}"
-          show_card(source: task.bundle, title: title, body: body, level: :warn, id: "init-#{task.id}")
-        end
-      end
-    end
-    private :finish_init_task
-
     # ── Load events ───────────────────────────────────────────────────────
 
     # Announce what failed to load and what plugins showed while loading,
@@ -755,8 +674,7 @@ module Samagotchi
 
         @shut_down = true
         # An init task's requests end (a server's boot), so it finishes.
-        @init_tasks.each { |task| task.cancel.cancel!(:shutdown) }
-        @anytime_threads.dup + @init_tasks.filter_map(&:thread)
+        @anytime_threads.dup + @plugin_tasks.shut_down!
       end
       # #stop_idle's work (the scheduler's stop is idempotent), where the
       # callers haven't stopped it already.
@@ -769,7 +687,7 @@ module Samagotchi
       end
       left = threads.count(&:alive?)
       Log.warn(:plugins, "anytime_commands_left", count: left) if left.positive?
-      @init_tasks.each { |task| task.thread&.kill if task.thread&.alive? }
+      @plugin_tasks.kill_leftovers
       @services.stop_all
       self
     end
@@ -1035,7 +953,7 @@ module Samagotchi
         last_prompt: @session&.last_prompt,
         event_seq: @session_observer&.event_count,
         metrics: metrics,
-        pending_question: @question_mutex.synchronize { @pending_question&.dup },
+        pending_question: @question_desk.pending,
         used_memory_names: @used_memory_mutex.synchronize { @used_memory_names.dup },
         preloaded_memory_names: preloaded_memory_names,
         muted_memory_names: @muted_memory_names.dup,
@@ -1144,14 +1062,11 @@ module Samagotchi
     # default, so a bare Engine denies instead of waiting for nobody). Set
     # by the host (TerminalUI, Worker).
     def interface
-      @interface || :non_interactive
+      @guardrail_wiring.interface
     end
 
     def interface=(value)
-      value = value.to_sym
-      raise ArgumentError, "unknown interface #{value}" unless Guardrails::Context::INTERFACES.include?(value)
-
-      @interface = value
+      @guardrail_wiring.interface = value
     end
 
     # Where the approval store lives: beside Session's state dir
@@ -1178,128 +1093,36 @@ module Samagotchi
     def guardrail_state_dir=(state_dir)
       # Also where list_sessions and send_note look for other sessions.
       @state_dir = state_dir
-      @guardrail_approvals = Guardrails::Approvals.new(dir: Guardrails::Approvals.dir_for(state_dir))
-      @guardrail_protected = nil
+      @guardrail_wiring.state_dir = state_dir
     end
 
-    # The gate's core checks, in order.
+    # The gate's core checks, in order (GuardrailWiring#checks).
     def guardrail_checks
-      rules = guardrail_rules
-      [@guardrail_failures, rules.hook_asks, guardrail_protected_paths, (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch),
-       rules].compact
+      @guardrail_wiring.checks
     end
 
-    # The YAML rules: config.yml's `guardrails:` section (rules, disable) and
-    # installed bundles'. One that doesn't parse is a required load failure
-    # (every call is denied). Read again when one of those files changed
-    # (a stat of each per tool call), so a long-lived worker follows edits.
+    # The YAML rules, read again when a file changed (GuardrailWiring#rules).
     # @return [Guardrails::Rules]
     def guardrail_rules
-      @guardrail_rules_mutex.synchronize do
-        stamp = guardrail_rules_stamp
-        if @guardrail_rules.nil? || stamp != @guardrail_rules_stamp
-          @guardrail_failures.drop(:rules)
-          @guardrail_rules = load_guardrail_rules
-          @guardrail_rules_stamp = stamp
-        end
-        @guardrail_rules
-      end
-    end
-
-    # [path, mtime, size] of config.yml and every installed bundle's
-    # manifest.json and guardrails/ file.
-    def guardrail_rules_stamp
-      require_relative "memory_bundle/provenance"
-      paths = [Samagotchi::ConfigFile.global_path] +
-              Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "{manifest.json,guardrails/*}")]
-      paths.compact.sort.map do |path|
-        stat = File.stat(path)
-        [path, stat.mtime.to_r, stat.size]
-      rescue SystemCallError
-        [path]
-      end
-    end
-
-    def load_guardrail_rules
-      section = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-      section = section["guardrails"] if section.is_a?(Hash)
-      rules = []
-      disable = []
-      begin
-        raise Guardrails::Rules::ParseError, "guardrails must be a mapping" unless section.nil? || section.is_a?(Hash)
-
-        rules = Guardrails::Rules.parse(section && section["rules"], source: "config")
-        disable = Guardrails::Rules.parse_disable(section && section["disable"])
-      rescue Guardrails::Rules::ParseError => e
-        Log.warn(:guardrails, "config_rules_invalid", echo: "[samagotchi:guardrails] config.yml guardrails rules: #{e.message}")
-        @guardrail_failures.add("rules in config.yml", e.message, required: true, group: :rules)
-      end
-      Guardrails::Rules.new(rules + bundle_guardrail_rules, disable: disable,
-                            enabled: Samagotchi::Config.get("guardrails.enabled") != false)
+      @guardrail_wiring.rules
     end
-    private :guardrail_rules_stamp, :load_guardrail_rules
 
-    # Installed bundles' guardrails/*.yml, by bundle name then file name.
-    # A file that is missing, changed since install (sha256) or doesn't
-    # parse is a required load failure.
+    # Installed bundles' guardrails/*.yml (GuardrailWiring#bundle_rules).
     def bundle_guardrail_rules
-      require_relative "memory_bundle/provenance"
-      rules = []
-      MemoryBundle::Provenance.each_installed_with_guardrails do |bundle_name, data|
-        if data[:error]
-          Log.warn(:guardrails, "bundle_rules_invalid", echo: "[samagotchi:guardrails] bundle #{bundle_name}: #{data[:error]}", bundle: bundle_name)
-          @guardrail_failures.add("rules (bundle #{bundle_name})", data[:error], required: true, group: :rules)
-          next
-        end
-        dir = MemoryBundle::Provenance.new(name: bundle_name).guardrails_dir
-        data[:guardrails].sort_by { |k, _| k.to_s }.each do |basename, meta|
-          what = "rules #{basename} (bundle #{bundle_name})"
-          path = File.join(dir, basename.to_s)
-          begin
-            raise Guardrails::Rules::ParseError, "the file is missing" unless File.file?(path)
-
-            expected = (meta.is_a?(Hash) ? meta[:sha256] : nil).to_s.sub(/\Asha256:/, "")
-            actual = Digest::SHA256.hexdigest(File.binread(path))
-            if expected != actual
-              raise Guardrails::Rules::ParseError, "its sha256 differs from the installed one (edited after install? reinstall the bundle)"
-            end
-
-            doc = YAML.safe_load(File.read(path))
-            raise Guardrails::Rules::ParseError, "expected a mapping with rules:" unless doc.is_a?(Hash)
-
-            rules.concat(Guardrails::Rules.parse(doc["rules"], source: "bundle #{bundle_name}"))
-          rescue Guardrails::Rules::ParseError, Psych::Exception => e
-            Log.warn(:guardrails, "rules_file_invalid", echo: "[samagotchi:guardrails] #{what}: #{e.message}", bundle: bundle_name, file: basename.to_s)
-            @guardrail_failures.add(what, e.message, required: true, group: :rules)
-          end
-        end
-      end
-      rules
-    rescue StandardError => e
-      Log.error(:guardrails, "bundle_rules_failed", echo: "[samagotchi:guardrails] failed to read installed bundles' rules: #{e.class}: #{e.message}", error: e.class.name)
-      @guardrail_failures.add("bundle rules", "#{e.class}: #{e.message}", required: true, group: :rules)
-      rules || []
+      @guardrail_wiring.bundle_rules
     end
 
     # @return [Guardrails::LoadFailures]
     attr_reader :guardrail_failures
 
     def guardrail_protected_paths
-      @guardrail_protected ||= begin
-        require_relative "memory_bundle/provenance"
-        config = Samagotchi::ConfigFile.read_yaml(path: Samagotchi::ConfigFile.global_path)
-        hooks_dir = config.is_a?(Hash) && config["hooks"].is_a?(Hash) ? config["hooks"]["hooks_dir"] : nil
-        Guardrails::ProtectedPaths.new(
-          store_dir: File.dirname(@guardrail_approvals.path),
-          bundles_dir: MemoryBundle::Provenance.bundles_dir,
-          config_path: Samagotchi::ConfigFile.global_path,
-          hooks_dir: Hooks::Loader.expand_path(hooks_dir || Hooks::Loader.default_hooks_dir)
-        )
-      end
+      @guardrail_wiring.protected_paths
     end
 
     # @return [Guardrails::Approvals]
-    attr_reader :guardrail_approvals
+    def guardrail_approvals
+      @guardrail_wiring.approvals
+    end
 
     # @return [Guardrails::LoadFailures] the plugins that failed to load
     attr_reader :plugin_failures
@@ -1334,37 +1157,16 @@ module Samagotchi
     # The context the gate sees for a tool call now.
     # @return [Guardrails::Context]
     def guardrail_context
-      Guardrails::Context.new(cwd: Dir.pwd, session_id: @session&.id, interface: interface,
-                              origin: @turn_origin, git: @guardrail_git)
+      @guardrail_wiring.context
     end
 
-    # Ask the user to approve a call the gate voted `ask` on, through the
-    # question flow (REPL sync handler, attached TUI, web). Settles the
-    # verdict: allow with the picked scope, or deny with a note for the
-    # model. A --non-interactive run has no one to ask and denies at once.
+    # Ask the user to approve a call the gate voted `ask` on
+    # (GuardrailWiring#request_approval).
     # @param verdict [Guardrails::Verdict]
     # @return [Guardrails::Verdict]
     def request_approval(verdict)
-      if interface == :non_interactive
-        return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it (non-interactive run).")
-      end
-
-      # A plugin tool is asked about by its label, as its row shows it.
-      label = ToolActivity.plugin_label(verdict.call[:name].to_s, registry: @tools)
-      # verdict.call is the call that will run (a hook may have replaced it).
-      payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call))
-      Guardrails::Approval.settle(verdict, open_question(payload), payload[:approval][:scopes])
-    end
-
-    # The dry-run diff of an edit/write call for its approval; a preview
-    # that fails only leaves the diff out, it never denies the call.
-    def approval_preview(call)
-      EditPreview.for(call)
-    rescue StandardError => e
-      Log.warn(:guardrails, "edit_preview_failed", error: "#{e.class}: #{e.message}")
-      nil
+      @guardrail_wiring.request_approval(verdict)
     end
-    private :approval_preview
 
     # The conversation as a hook may read it: a frozen array of copied
     # messages, so a hook cannot change what the turn sends or stores.
@@ -1416,7 +1218,8 @@ module Samagotchi
         notify: ->(text:, level:, hook:) { hook_notify(text, level, hook) },
         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)) }
+        steer: ->(text:, hook:) { steer(text, source: hook_source(hook)) },
+        stop_generation: ->(reason:, hook:) { hook_stop_generation(reason, hook) }
       )
     end
     private :hook_runtime
@@ -1462,22 +1265,7 @@ module Samagotchi
     # answer, cancelled) is nil too.
     # @return [Hash, nil] {selected:, freeform:, selected_indices:}
     def hook_ask_user(question, options, header, allow_freeform, hook)
-      return nil if interface == :non_interactive
-
-      opts = Tools::AskUserQuestion.normalize_options(options)
-      unless opts
-        Log.warn(:hooks, "ask_user_invalid", echo: "[samagotchi:hooks] #{hook} asked with invalid options (2-8 strings)", hook: hook.to_s)
-        return nil
-      end
-
-      fields = { question: question.to_s, options: opts, header: header, multi_select: false,
-                 allow_freeform: !!allow_freeform, kind: "hook", hook: hook.to_s }.compact
-      answer = open_question(fields)
-      return nil unless answer.is_a?(Hash) && answer[:selected]
-
-      result = { selected: Array(answer[:selected]), freeform: answer[:freeform] }
-      result[:selected_indices] = answer[:selected_indices] if answer.key?(:selected_indices)
-      result
+      @question_desk.ask_for_hook(question, options, header, allow_freeform, hook)
     end
     private :hook_ask_user
 
@@ -1494,216 +1282,58 @@ module Samagotchi
     end
     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
+
+      ctrl.cancel_generation!(:hook, { by: hook_source(hook), reason: reason.to_s })
+    end
+    private :hook_stop_generation
+
     # ── Ask-user-question (structured qualification) ──────────────────────────
 
     # @return [Hash, nil] current pending question (thread-safe copy)
     def pending_question
-      @question_mutex.synchronize { @pending_question&.dup }
+      @question_desk.pending
     end
 
     # Ask the model's question (ask_user_question): the kernel's
     # question_handler, called on the turn thread with the payload
-    # Tools::AskUserQuestion.validate made. Opens it (#open_question) and
-    # returns the answer as JSON for the tool result.
+    # Tools::AskUserQuestion.validate made (QuestionDesk#request).
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request_question(payload)
-      result = open_question(**payload.slice(:question, :options, :header),
-                             multi_select: !!payload[:multi_select], allow_freeform: !!payload[:allow_freeform])
-      # Dismissed (the card's dismiss, Esc): an answer of its own, not a
-      # tool failure the model learns to avoid the tool from.
-      result = { dismissed: true, id: result[:id], note: QUESTION_DISMISSED_NOTE } if result.is_a?(Hash) && result[:error] == "no answer"
-      result.is_a?(String) ? result : JSON.generate(result)
-    end
-
-    QUESTION_DISMISSED_NOTE = "The user dismissed the question without answering. Go on with your best judgement, " \
-                              "or ask in your reply if you can't."
-
-    # Open a question for the UIs and wait for its answer. Emits
-    # :question_requested, persists it to the session, and BLOCKS until
-    # answer_question / cancel_question wakes it (or the turn is cancelled).
-    # The fields go to pending_question as given (no cleaning), extra keys
-    # included, so a caller can add its own (kind:, approval:).
-    # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
-    # @return [Hash, String] the answer {id:, selected:, freeform:, selected_indices:},
-    #   or {error:, …}; a String when a sync handler returned text itself
-    def open_question(fields)
-      id = SecureRandom.uuid
-      pending = { id: id, **fields, status: "pending", created_at: Time.now.iso8601(3) }.compact
-
-      @question_mutex.synchronize do
-        @pending_question = pending
-        @question_answer = nil
-      end
-      # Persist to session file for WEB stub + resume (generic for all UIs)
-      if @session
-        @session.pending_question = pending.dup
-        begin; @session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-      end
-      # Generic emit for all UIs (TUI, WEB, Bridge, future). Observers that
-      # stash this event (e.g. TerminalUI handle_question_event) will
-      # discard it as stale if the synchronous handler below already answers
-      # and clears pending — see drain_pending_question? staleness check.
-      emit_event(nil, { type: :question_requested, pending_question: pending })
-
-      # If a synchronous UI handler is registered (TUI), invoke it inline on the
-      # SAME thread that called request_question (TerminalUI's REPL thread is the
-      # turn thread — no second thread exists to answer). This avoids deadlock.
-      # This path is TUI-specific but the surrounding emit/clear is generic, so
-      # any future UI that registers a sync handler gets the same guarantee.
-      if instance_variable_defined?(:@question_sync_handler) && @question_sync_handler
-        begin
-          sync_res = @question_sync_handler.call(pending.dup)
-          # Handler may have called answer_question or returned a hash/string
-          @question_mutex.synchronize do
-            if @question_answer
-              ans = @question_answer
-              @pending_question = nil
-              if @session
-                @session.pending_question = nil
-                begin; @session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-              end
-              emit_event(nil, { type: :question_answered, id: id, answer: ans })
-              return ans
-            end
-            if sync_res.is_a?(Hash) && sync_res[:selected]
-              # Treat returned hash as answer (handler rendered and parsed)
-              @question_answer = sync_res
-              @pending_question = nil
-              if @session
-                @session.pending_question = nil
-                begin; @session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-              end
-              emit_event(nil, { type: :question_answered, id: id, answer: sync_res })
-              return sync_res
-            elsif sync_res.is_a?(String) && !sync_res.strip.empty?
-              return sync_res
-            end
-          end
-        rescue StandardError => e
-          Log.warn(:turn, "question_handler_failed", echo: "[ask_user_question] sync handler failed: #{e.message}", error: e.class.name)
-        end
-        # Sync handler existed but did not produce an answer — do not deadlock on
-        # CV (no cross-thread answerer exists for synchronous UIs). Clear pending
-        # and return an error so the model can fallback to plain text. Generic
-        # observers will discard the stale question_requested via staleness check.
-        @question_mutex.synchronize { @pending_question = nil }
-        if @session
-          @session.pending_question = nil
-          begin; @session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-        end
-        return { error: "no answer", detail: "handler failed to capture selection", id: id }
-      end
-
-      # Block until answered/cancelled (cross-thread path: WEB/Bridge/background worker)
-      answer = nil
-      @question_mutex.synchronize do
-        loop do
-          break if @question_answer
-          break if active_cancel_controller&.cancelled?
-          break if @pending_question.nil? || @pending_question[:status] != "pending"
+      @question_desk.request(payload)
+    end
 
-          # Wait with timeout to check cancel; 0.2s matches reminder poll
-          @question_cv.wait(0.2)
-        end
-        answer = @question_answer
-        # If cancelled
-        if active_cancel_controller&.cancelled? && answer.nil?
-          @pending_question = nil
-          if @session
-            @session.pending_question = nil
-            begin; @session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-          end
-          emit_event(nil, { type: :question_cancelled, id: id, reason: active_cancel_controller.reason.to_s })
-          return { error: "cancelled", reason: active_cancel_controller.reason.to_s, id: id }
-        end
-      end
+    QUESTION_DISMISSED_NOTE = QuestionDesk::DISMISSED_NOTE
 
-      # Clear persisted
-      @question_mutex.synchronize { @pending_question = nil }
-      if @session
-        @session.pending_question = nil
-        begin; @session.save(state_dir: session_state_dir); rescue StandardError; nil; end
-      end
-      if answer
-        emit_event(nil, { type: :question_answered, id: id, answer: answer })
-        answer
-      else
-        { error: "no answer", id: id }
-      end
+    # Open a question for the UIs and wait for its answer
+    # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
+    # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
+    # @return [Hash, String] the answer, or {error:, …}
+    def open_question(fields)
+      @question_desk.open_question(fields)
     end
 
-    # Answer the pending question (called from UI thread).
-    # @param id [String] pending id
-    # @param selected [Array<String>] values/labels
-    # @param freeform [String, nil]
+    # Answer the pending question (called from UI thread; QuestionDesk#answer).
     # @return [Hash] normalized answer
     def answer_question(id:, selected:, freeform: nil)
-      sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
-      fm = freeform.to_s.strip
-      fm = nil if fm.empty?
-      @question_mutex.synchronize do
-        pending = @pending_question
-        raise QuestionNotPending, "no pending question" unless pending
-        raise QuestionNotPending, "id mismatch" unless pending[:id].to_s == id.to_s
-        # First responder wins: after the first answer the turn thread clears
-        # @pending_question in a later lock block, so a second UI's answer can
-        # land in between and must not overwrite the first.
-        raise QuestionNotPending, "question already answered" if @question_answer
-        raise QuestionNotPending, "question #{pending[:status]}" unless pending[:status].to_s == "pending"
-
-        opts = Array(pending[:options])
-        # Validate selected subset of options (value == label in v1)
-        invalid = sel.reject { |v| opts.include?(v) }
-        unless invalid.empty?
-          raise ArgumentError, "invalid selection: #{invalid.join(', ')} (valid: #{opts.join(', ')})"
-        end
-        if !pending[:multi_select] && sel.size > 1
-          raise ArgumentError, "single-select question: got #{sel.size} selections"
-        end
-        if pending[:multi_select] == false && sel.empty? && fm.nil?
-          raise ArgumentError, "selection required"
-        end
-        # Persist pending cleared elsewhere; just set answer
-        answer = { id: id.to_s, selected: sel, freeform: fm }
-        # Derive indices for convenience
-        answer[:selected_indices] = sel.map { |v| opts.index(v) }.compact
-        @question_answer = answer
-        @question_cv.broadcast
-        answer
-      end.tap do
-        # A human answered: the session is back in the lists (ArchiveStore).
-        ArchiveStore.user_input(@session&.id, state_dir: session_state_dir)
-      end
+      @question_desk.answer(id: id, selected: selected, freeform: freeform)
     end
 
     def set_question_sync_handler(&block)
-      @question_sync_handler = block
+      @question_desk.sync_handler = block
     end
 
-    # Cancel the pending question (e.g. /cancel, a dismiss). Announces which
-    # one, so every UI closes it; with none pending there is nothing to
-    # announce. A question already answered (the turn thread hasn't taken the
-    # answer yet) or already closed stays as it is: the first responder wins.
-    # @param id [String, nil] cancel only this question (a UI's dismiss
-    #   names the one it showed)
-    # @return [Boolean] whether it was cancelled (true with none pending and
-    #   no id, as before)
+    # Cancel the pending question (QuestionDesk#cancel).
+    # @return [Boolean] whether it was cancelled
     def cancel_question(reason = "user", id: nil)
-      cancelled_id = @question_mutex.synchronize do
-        pending = @pending_question
-        next unless pending
-        next if id && pending[:id].to_s != id.to_s
-        next if @question_answer || pending[:status].to_s != "pending"
-
-        pending[:status] = "cancelled"
-        @question_cv.broadcast
-        pending[:id]
-      end
-      return id.nil? && pending_question.nil? unless cancelled_id
-
-      emit_event(nil, { type: :question_cancelled, id: cancelled_id, reason: reason.to_s }) rescue nil
-      true
+      @question_desk.cancel(reason, id: id)
     end
 
     # The system prompt for a target's loop (default: the effective model's):
@@ -1789,7 +1419,7 @@ module Samagotchi
 
       messages = @activity_mutex.synchronize { @session&.messages } || []
       covered = state[:covered].to_i
-      turns_since = Array(messages).drop(covered).count { |m| Steer.prompt?(m) }
+      turns_since = Array(messages).drop(covered).count { |m| Steer.turn_prompt?(m) }
       { text: state[:text], covered: covered, turns_since: turns_since, created_at: state[:created_at] }
     end
 
@@ -1871,8 +1501,7 @@ module Samagotchi
         @turn_event_sink = on_event
       end
       # The gate's context: who queued this turn, and git asked afresh.
-      @turn_origin = origin
-      @guardrail_git = Guardrails::GitInfo.new
+      @guardrail_wiring.begin_turn(origin)
 
       prompt = nil if continue
       # For the cancel note: how long the turn ran.
@@ -1962,7 +1591,7 @@ module Samagotchi
         result = backend.complete(
           messages: messages,
           max_iterations: max_iterations,
-          on_stream_event: build_stream_event_handler(on_event),
+          on_stream_event: build_stream_event_handler(on_event, cancel_controller: effective_controller),
           cancel_controller: effective_controller,
           model_name: bare_for_backend,
           max_tool_output_chars: max_tool_output_chars,
@@ -2385,41 +2014,17 @@ module Samagotchi
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
-    # for the turn thread, which applies it (#apply_staged_tools!): the
-    # registry is read only there. A later set of the same bundle wins.
+    # for the turn thread (PluginTasks#stage_tools).
     def stage_tools(bundle, specs, context)
-      @lifecycle_mutex.synchronize do
-        return if @shut_down
-
-        @staged_tools[bundle] = [specs, context]
-      end
-      nil
+      @plugin_tasks.stage_tools(bundle, specs, context)
     end
     private :stage_tools
 
-    # Apply the staged tool sets (#stage_tools), on the turn thread, before
-    # the turn's system prompt is built; the prompts are built again when
-    # a set changed anything. A name another source has is left out with a
-    # notice.
+    # Apply the staged tool sets, on the turn thread, before the turn's
+    # system prompt is built (PluginTasks#apply_staged_tools!).
     # @return [Boolean] whether the tools changed
     def apply_staged_tools!
-      staged = @lifecycle_mutex.synchronize do
-        taken = @staged_tools
-        @staged_tools = {}
-        taken
-      end
-      changed = false
-      staged.each do |bundle, (specs, context)|
-        result = Plugin::Api.apply_tools(@tools, bundle, specs, context)
-        changed ||= result[:changed]
-        result[:skipped].each do |why|
-          Log.warn(:plugins, "plugin_tool_skipped", bundle: bundle, msg: why)
-          hook_notify("#{why}; left out", :warn, bundle)
-        end
-        Log.info(:plugins, "plugin_tools_replaced", bundle: bundle, tools: specs.size) if result[:changed]
-      end
-      tools_changed! if changed
-      changed
+      @plugin_tasks.apply_staged_tools!
     end
     public :apply_staged_tools!
 
@@ -2450,6 +2055,7 @@ module Samagotchi
         card: ->(**card) { show_card(**card) },
         steer: ->(text, source) { steer(text, source: source) },
         stop_turn: ->(reason, label) { hook_stop_turn(reason, label) },
+        stop_generation: ->(reason, label) { hook_stop_generation(reason, label) },
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
           ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller)
         },
@@ -2516,74 +2122,6 @@ module Samagotchi
     end
     private :read_bundle_settings
 
-    # Build (or disable) the idle recap job. On by default: with no recap
-    # host or model configured it asks the session's current model on its
-    # host, resolved at each attempt the way a turn does (a /model switch
-    # counts). An explicit `recap: {host_ref:, model:}` or `{base_url:,
-    # model:}` pins it; an incomplete one warns and leaves recap off.
-    #
-    # Single precedence path: explicit `recap:` kwarg > Config registry
-    # (CLI > ENV > file > default). An explicit disable (`recap: false` as
-    # the kwarg or in the config file, `recap: {enabled: false}`, or
-    # SAMAGOTCHI_RECAP_ENABLED=false) always wins.
-    def build_recap(recap)
-      return nil if recap == false
-      # The TUI passes the config file's section; a worker passes nothing, so
-      # read it here too (a scalar `recap: false` is only seen this way).
-      return nil if recap.nil? && ConfigFile.recap_config == false
-      return nil if Samagotchi::Config.get("recap.enabled") == false
-
-      # Normalize kwarg (TerminalUI passes recap: recap_config hash or nil)
-      kwarg_config = recap.is_a?(Hash) ? recap : {}
-
-      base_url = string_config(kwarg_config, :base_url) || registry_string("recap.base_url")
-      host_ref = string_config(kwarg_config, :host_ref) || string_config(kwarg_config, :host) || registry_string("recap.host_ref")
-      model = string_config(kwarg_config, :model) || registry_string("recap.model")
-      label = model
-
-      target = nil
-      if base_url.nil? && host_ref.nil? && model.nil?
-        target = -> { session_model_recap_target }
-      else
-        # If host_ref given, derive base_url (the host's OpenAI base) and its
-        # API key variable from the host_registry entry
-        api_key_env = nil
-        if host_ref && !host_ref.empty?
-          entry = @host_registry.find_entry(host_ref)
-          if entry
-            base_url = entry.openai_base_url
-            api_key_env = entry.api_key_env
-            # If model is host-qualified, extract bare model for recap client
-            _, bare = @host_registry.parse_qualified_model(model) if model
-            model = bare if bare && !bare.empty?
-          else
-            Log.warn(:recap, "host_ref_unknown", echo: "Warning: recap host_ref '#{host_ref}' not found in hosts:; recap disabled.", host_ref: host_ref)
-            return nil
-          end
-        end
-
-        if base_url.to_s.strip.empty? || model.to_s.strip.empty?
-          Log.warn(:recap, "recap_unconfigured",
-                   echo: "Warning: SAMAGOTCHI session recap is enabled but base_url/model are missing; recap disabled. " \
-                         "Set recap: {host_ref:, model:} or SAMAGOTCHI_RECAP_BASE_URL and SAMAGOTCHI_RECAP_MODEL (or pass recap: {base_url:, model:}), " \
-                         "or leave them all out to recap with the session's own model.")
-          return nil
-        end
-        fixed = { base_url: base_url.to_s.strip, api_key_env: api_key_env, model: model.to_s.strip, label: label.to_s.strip }
-        target = -> { fixed }
-      end
-
-      IdleRecap.new(
-        engine: self,
-        target: target,
-        inactivity: recap_number_setting(kwarg_config, :inactivity, "recap.inactivity", IdleRecap::DEFAULT_INACTIVITY_SECONDS, :float),
-        min_user_turns: recap_number_setting(kwarg_config, :min_user_turns, "recap.min_user_turns", IdleRecap::DEFAULT_MIN_USER_TURNS, :int),
-        timeout: recap_number_setting(kwarg_config, :timeout, "recap.timeout", IdleRecap::DEFAULT_TIMEOUT_SECONDS, :float),
-        sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences")),
-        store: RecapStore.new(session_id_lookup: -> { @session&.id }, state_dir_lookup: -> { session_state_dir })
-      )
-    end
-
     # The session's current model as a recap target: its host's OpenAI API
     # (native llama.cpp hosts serve /v1/chat/completions too), key variable
     # and bare model name, as a turn resolves them.
@@ -2593,37 +2131,6 @@ module Samagotchi
         model: target.bare_model, label: @effective_model_name.to_s }
     end
 
-    # recap.sentences as [min, max]; an invalid value warns and falls back to
-    # the default range (the recap stays on).
-    def recap_sentences(value)
-      range = IdleRecap::RecapPrompt.sentences_range(value)
-      return range if range
-
-      default = IdleRecap::RecapPrompt::DEFAULT_SENTENCES
-      Log.warn(:recap, "sentences_invalid", echo: "Warning: invalid value for recap.sentences: #{value.to_s.inspect} — using #{default.join('-')}",
-                                            value: value.to_s)
-      default
-    end
-
-    # Read a scalar recap setting via the Config registry (ENV > file > default).
-    def registry_string(key)
-      value = Samagotchi::Config.get(key)
-      value = value.to_s.strip
-      value.empty? ? nil : value
-    rescue StandardError
-      nil
-    end
-
-    # Resolve a numeric recap setting: kwarg > Config registry > built-in default.
-    def recap_number_setting(kwarg_config, kwarg_key, config_key, default, numeric_type)
-      value = kwarg_config[kwarg_key] || kwarg_config[kwarg_key.to_s]
-      value = Samagotchi::Config.get(config_key) if value.nil? || value.to_s.strip.empty?
-      value = default if value.nil? || value.to_s.strip.empty?
-      numeric_type == :float ? value.to_f : value.to_i
-    rescue StandardError
-      numeric_type == :float ? default.to_f : default.to_i
-    end
-
     # Build the idle reminders job. Always created (reminders are opt-in
     # via the agent calling register_reminder). The shared IdleScheduler
     # polls it and triggers synthetic turns when reminders are due.
@@ -2640,11 +2147,6 @@ module Samagotchi
       )
     end
 
-    def string_config(config, key)
-      value = config[key]
-      value.to_s.strip.empty? ? nil : value.to_s
-    end
-
     # ── Event helpers ──────────────────────────────────────────────────────────
 
     # Always return a handler so raw kernel loop events reach the persistent
@@ -2669,18 +2171,27 @@ module Samagotchi
     #   * Non-splitting profiles (nil think close, e.g. Gemma) leave the event
     #     unchanged; the web client then falls back to raw `content`, preserving
     #     today's behavior (no regression).
-    def build_stream_event_handler(on_event)
+    #
+    # With a :generation_progress hook registered, a Hooks::StreamWatch gets
+    # each chunk's thinking and text after the UIs had it.
+    def build_stream_event_handler(on_event, cancel_controller: nil)
       splitter = ThoughtStreamSplitter.for_profile(profile)
       enrich = profile.thought_close ? :always : :never
+      watch = stream_watch(cancel_controller)
       proc do |event|
+        progress = nil
         case event[:type]
         when :generation_started
           splitter = ThoughtStreamSplitter.for_profile(profile)
+          watch&.started(event[:iteration])
         when :generation_chunk
           # The chat loop already splits its stream (reasoning arrives apart
           # from the answer); only raw native chunks are split here.
-          unless event.key?(:text)
+          if event.key?(:text)
+            progress = { thinking: event[:thinking], text: event[:text] }
+          else
             delta = splitter.feed(event[:content])
+            progress = { thinking: delta[:thinking], text: delta[:text] }
             event = event.merge(text: delta[:text], thinking: delta[:thinking]) if enrich == :always
           end
         end
@@ -2689,6 +2200,7 @@ module Samagotchi
         next thinking_refused(event) if event[:type] == :thinking_refused
 
         emit_event(on_event, event)
+        watch.feed(**progress) if watch && progress
         if event[:type] == :generation_completed
           check_thinking_honoured(event)
           announce_effort_ignored
@@ -2696,6 +2208,14 @@ module Samagotchi
       end
     end
 
+    # The turn's StreamWatch, or nil when no hook listens.
+    def stream_watch(cancel_controller)
+      return nil unless cancel_controller && @hooks.any?(Hooks::StreamWatch::EVENT)
+
+      Hooks::StreamWatch.new(hooks: @hooks, cancel_controller: cancel_controller)
+    end
+    private :stream_watch
+
     def emit_event(on_event, event)
       # Capture used memories synchronously in the turn thread.
       read_names = begin