samagotchi 0.97.0 → 0.99.0

data/lib/samagotchi/llm/errors.rb

@@ -191,12 +191,24 @@ module Samagotchi
         elsif tools_unsupported?
           "host #{host} rejected the request: #{tools_detail}; #{TOOLS_HINT}"
         else
-          "host #{host} rejected the request: #{detail}#{"; #{hint}" if hint}"
+          "host #{host} rejected the request: #{hinted_detail}"
         end
       end
 
       private
 
+      # The detail with the hint, ahead of a model list the detail has (a
+      # 404's "Available models: …", cut at the message's limit), else at
+      # its end.
+      def hinted_detail
+        return detail unless hint
+
+        list_at = detail.index(ProviderErrors::AVAILABLE_MODELS_START_RE)
+        return "#{detail}; #{hint}" unless list_at
+
+        "#{detail[0...list_at].sub(/[\s.;:]+\z/, "")}; #{hint} #{detail[list_at..].lstrip}"
+      end
+
       # The detail up to the end of the sentence that says the model takes no
       # tools: what a provider adds after it (OpenRouter: "Try disabling
       # "execute"…" and a routing docs link) is advice for its own UI.
@@ -395,6 +407,8 @@ module Samagotchi
       # third of the name, in a name at least HINT_FUZZY_MIN long.
       HINT_MAX_EDITS = 2
       HINT_FUZZY_MIN = 6
+      # The most ids a hint names.
+      HINT_SUGGESTIONS = 3
       # A 404's model it couldn't find: "Model 'X' not found", "model `X`
       # does not exist", "model X-1 not found" (unquoted, an id-like word,
       # checked after the match). Bounded quantifiers: a server's long token
@@ -402,6 +416,8 @@ module Samagotchi
       MODEL_NOT_FOUND_RE = /model\s+(?:["'`]([^"'`\s]{1,#{HINT_ID_MAX}})["'`]|([^"'`\s]{1,#{HINT_ID_MAX}}))\s+(?:was\s+)?(?:not found|does not exist)/i
       # The ids a 404 lists after "Available models:".
       AVAILABLE_MODELS_RE = /available models?:\s*(.+)\z/im
+      # Where that list starts, for the summary to put its hint ahead of it.
+      AVAILABLE_MODELS_START_RE = /\s*\bavailable models?:/i
       # The HTTP status an Anthropic error.type stands for, for an error
       # object that carries no numeric code (a Messages stream's error event,
       # an OpenAI error whose code is null or a name).
@@ -528,11 +544,10 @@ module Samagotchi
 
       # "did you mean 'ID'?" for a 404 that names the model it couldn't find
       # and lists the ones it has (oMLX: "Model 'X' not found. Available
-      # models: a, b, …"): the listed id that is X but for case, the one
-      # whose last segment (after "/" or "--") is X, else the one id a
-      # typo away (#typo_distance, whole or its last segment). Read from
-      # the message past the summary's cut (MESSAGE_LIMIT), within the
-      # HINT_* bounds; nil when there is no list, nothing close or a tie.
+      # models: a, b, …"), naming up to HINT_SUGGESTIONS ids
+      # (#closest_model_ids: "did you mean 'A' or 'B'?"). Read from the
+      # message past the summary's cut (MESSAGE_LIMIT), within the HINT_*
+      # bounds; nil when there is no list or nothing close.
       def model_hint(message)
         message = message[0, HINT_SCAN_CHARS]
         match = MODEL_NOT_FOUND_RE.match(message)
@@ -547,26 +562,45 @@ module Samagotchi
                   .reject { |id| id.empty? || id.length > HINT_ID_MAX }.uniq
         return nil if ids.empty? || ids.include?(requested)
 
-        close = closest_model_id(requested, ids)
-        close && "did you mean '#{close}'?"
+        close = closest_model_ids(requested, ids)
+        "did you mean #{close.map { |id| "'#{id}'" }.join(" or ")}?" unless close.empty?
       end
 
-      # The id that is +requested+ but for case, or whose last segment is,
-      # else the one id a typo away (#typo_distance); nil on a tie.
-      def closest_model_id(requested, ids)
+      # The listed ids closest to +requested+, at most HINT_SUGGESTIONS, in
+      # the first tier that has any: the ids that are +requested+ but for
+      # case, or whose last segment (after "/" or "--") is; else the ids a
+      # typo away (#typo_distance, whole or last segment), the nearest
+      # only; else the ids that contain +requested+ (HINT_FUZZY_MIN
+      # characters or more) or whose last segment it contains, the
+      # shortest first.
+      def closest_model_ids(requested, ids)
         probe = requested.downcase
-        exact = ids.find { |id| id.downcase == probe } || ids.find { |id| last_segment(id) == probe }
-        return exact if exact
+        exact = ids.select { |id| id.downcase == probe || last_segment(id) == probe }
+        return exact.first(HINT_SUGGESTIONS) unless exact.empty?
 
         scored = ids.filter_map do |id|
           distance = [id.downcase, last_segment(id)].uniq.filter_map { |name| typo_distance(probe, name) }.min
           [distance, id] if distance
         end
-        return nil if scored.empty?
+        unless scored.empty?
+          best = scored.map(&:first).min
+          return scored.select { |distance, _| distance == best }.map(&:last).first(HINT_SUGGESTIONS)
+        end
+
+        containing_ids(probe, ids)
+      end
+
+      # The ids that contain +probe+ or whose last segment +probe+ contains
+      # (either one HINT_FUZZY_MIN characters or more), closest in length
+      # first, at most HINT_SUGGESTIONS.
+      def containing_ids(probe, ids)
+        return [] if probe.length < HINT_FUZZY_MIN
 
-        best = scored.map(&:first).min
-        closest = scored.select { |distance, _| distance == best }
-        closest.size == 1 ? closest.first.last : nil
+        ids.select do |id|
+          segment = last_segment(id)
+          id.downcase.include?(probe) || (segment.length >= HINT_FUZZY_MIN && probe.include?(segment))
+        end.each_with_index.sort_by { |id, index| [(id.length - probe.length).abs, index] }
+           .first(HINT_SUGGESTIONS).map(&:first)
       end
 
       # The edit distance of +a+ and +b+ when it is a typo's: at most

data/lib/samagotchi/llm/refusal_memo.rb

@@ -23,6 +23,12 @@ module Samagotchi
       # Whether +kind+ is remembered for +model+ (nil: the host).
       def refused?(kind, model = nil) = @mutex.synchronize { @facts.key?([kind, model]) }
 
+      # Add +item+ to the list remembered for +kind+ and +model+ (a value
+      # that grows: the deferred tools a model's host refused, one by one).
+      def add(kind, model, item)
+        @mutex.synchronize { (@facts[[kind, model]] ||= []) << item unless Array(@facts[[kind, model]]).include?(item) }
+      end
+
       # The value remembered for +kind+ and +model+, or nil.
       def [](kind, model = nil) = @mutex.synchronize { @facts[[kind, model]] }
     end

data/lib/samagotchi/llm/turn_settings.rb

@@ -15,14 +15,22 @@ module Samagotchi
     # window (ContextWindow.setting, nil for none) and LLM context strategy
     # (LLMContextStrategy.resolve, nil for none), and its price on its host
     # (hosts.<name>.models.<id>.price, a ModelPrice; nil for none), what
-    # SessionMetrics estimates an unreported cost from. The Engine sets them once
-    # per turn, in Engine#generate, after the model's host is synced.
+    # SessionMetrics estimates an unreported cost from, and whether the turn's
+    # host takes tools it doesn't declare up front (+loads_tools+:
+    # AnthropicMessages#loads_tools?; a direct call of a reachable tool then
+    # runs). The Engine sets them once per turn, in Engine#generate, after
+    # the model's host is synced.
     TurnSettings = Data.define(:vision, :sampling, :thinking, :reasoning_history, :model_name, :window_setting,
-                               :llm_context, :price) do
+                               :llm_context, :price, :loads_tools) do
+      def initialize(vision:, sampling:, thinking:, reasoning_history:, model_name:, window_setting:, llm_context:,
+                     price:, loads_tools: false)
+        super
+      end
+
       # No vision, no sampling, the default thinking, no reasoning sent
-      # back, no model name.
+      # back, no model name, no tools loaded.
       def self.none = new(vision: nil, sampling: {}.freeze, thinking: Thinking::DEFAULT, reasoning_history: :drop,
-                          model_name: nil, window_setting: nil, llm_context: nil, price: nil)
+                          model_name: nil, window_setting: nil, llm_context: nil, price: nil, loads_tools: false)
     end
   end
 end

data/lib/samagotchi/llm_context_stale.rb

@@ -192,7 +192,7 @@ module Samagotchi
         id = entry[:tool_call_id].to_s
         matches = id.empty? ? [] : batch.select { |call_id, _| call_id.to_s == id }
         call = matches.one? ? matches.first.last : nil
-        call &&= Tools::BuiltinCalls.unwrap_saved(call, entry[:content])
+        call &&= Tools::BuiltinCalls.unwrap_saved(Tools::BuiltinCalls.wrap_saved(call, entry[:content]), entry[:content])
         texts = call && refs.size == 1 ? ToolResponse.runs_named(entry[:content], [call[:name]]) : nil
         return texts ? [[refs.first, call, texts.first.text]] : []
       end
@@ -201,7 +201,7 @@ module Samagotchi
       # built-in (BuiltinCalls.unwrap_saved).
       calls = batch.map(&:last)
       calls = calls.zip(ToolResponse.runs(entry[:content], calls.size)).map do |call, run|
-        Tools::BuiltinCalls.unwrap_saved(call, run&.text)
+        Tools::BuiltinCalls.unwrap_saved(Tools::BuiltinCalls.wrap_saved(call, run&.text), run&.text)
       end
       texts = ToolResponse.runs_named(entry[:content], calls.map { |call| call[:name] })
       return [] unless texts && texts.size == refs.size

data/lib/samagotchi/memory_bundle/bundle_hook.rb

@@ -6,15 +6,22 @@ module Samagotchi
   module MemoryBundle
     # One hook's metadata, as a bundle's manifest.yml declares it and its
     # installed record (manifest.json) keeps it: the file's sha256
-    # ("sha256:<hex>", "" when none is recorded), the event it registers
-    # for ("" when none: it isn't loaded), on_error (skip, log or
-    # fail_closed) and priority. The one place the defaults live.
-    class BundleHook < Data.define(:sha256, :event, :on_error, :priority)
+    # ("sha256:<hex>", "" when none is recorded), the events it registers
+    # for (manifest `event:` for one, `events:` a list; none: it isn't
+    # loaded), on_error (skip, log or fail_closed) and priority. One
+    # instance of the hook serves every event it lists. The one place the
+    # defaults live.
+    class BundleHook < Data.define(:sha256, :events, :on_error, :priority)
       DEFAULT_ON_ERROR = "skip"
       DEFAULT_PRIORITY = 100
 
-      def initialize(sha256: "", event: "", on_error: DEFAULT_ON_ERROR, priority: DEFAULT_PRIORITY)
-        super
+      # @param event [String, nil] one event (manifest `event:`)
+      # @param events [Array<String>, String, nil] the events (manifest
+      #   `events:`); `event:` and `events:` together are joined, blanks
+      #   and repeats dropped
+      def initialize(sha256: "", event: nil, events: nil, on_error: DEFAULT_ON_ERROR, priority: DEFAULT_PRIORITY)
+        names = [*event, *events].map { |e| e.to_s.strip }.reject(&:empty?).uniq.freeze
+        super(sha256: sha256, events: names, on_error: on_error, priority: priority)
       end
 
       # @param raw [Hash, BundleHook, nil] string keys (manifest.yml) or
@@ -25,7 +32,7 @@ module Samagotchi
 
         h = raw.is_a?(Hash) ? raw.transform_keys(&:to_s) : {}
         on_error = h["on_error"].to_s.strip
-        new(sha256: prefixed(h["sha256"]), event: h["event"].to_s.strip,
+        new(sha256: prefixed(h["sha256"]), event: h["event"], events: h["events"],
             on_error: on_error.empty? ? DEFAULT_ON_ERROR : on_error,
             priority: (h["priority"] || DEFAULT_PRIORITY).to_i)
       end
@@ -44,8 +51,20 @@ module Samagotchi
       # The sha's hex, "" when none is recorded.
       def hex = sha256.delete_prefix("sha256:")
 
-      # The string-keyed form manifest.yml and manifest.json hold.
-      def to_record = to_h.transform_keys(&:to_s)
+      # Whether the hook fails closed: on_error fail_closed applies to its
+      # before_tool_call registration only.
+      def fail_closed?(event) = on_error == "fail_closed" && event.to_s == "before_tool_call"
+
+      # How `chi bundle status` / `diff` name its events: `event=x`, or
+      # `events=x,y` for more than one.
+      def events_field = events.size > 1 ? "events=#{events.join(",")}" : "event=#{events.first}"
+
+      # The string-keyed form manifest.yml and manifest.json hold: `event`
+      # for one event (as an older chi reads it), `events` for more.
+      def to_record
+        listed = events.size > 1 ? { "events" => events.dup } : { "event" => events.first.to_s }
+        { "sha256" => sha256, **listed, "on_error" => on_error, "priority" => priority }
+      end
     end
   end
 end

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -375,9 +375,26 @@ module Samagotchi
           next unless k.is_a?(String) && !k.empty?
           next unless v.is_a?(Hash)
 
+          check_hook_events(k, v)
           acc[k] = BundleHook.parse(v)
         end
       end
+
+      HOOK_EVENT_NAME = /\A[a-z][a-z0-9_]*\z/
+
+      # A hook's events: list holds event names (one instance registered
+      # for each); it and event: are one or the other.
+      def check_hook_events(file, entry)
+        return unless entry.key?("events")
+
+        raw = entry["events"]
+        raise ValidationError, "hooks: #{file}: give event: or events:, not both" if entry.key?("event")
+        raise ValidationError, "hooks: #{file}: events: must be a list of event names" unless raw.is_a?(Array) && !raw.empty?
+
+        raw.each do |item|
+          raise ValidationError, "hooks: #{file}: events: #{item.inspect} is not an event name" unless item.is_a?(String) && item.strip.match?(HOOK_EVENT_NAME)
+        end
+      end
     end
   end
 end

data/lib/samagotchi/message_parts.rb

@@ -237,7 +237,8 @@ module Samagotchi
                   tool_id: nil, marks: {})
       # A built-in reached through call_tool reloads as that built-in's
       # row, with via (its saved params and label are the built-in's).
-      call = Tools::BuiltinCalls.unwrap_saved(call, output)
+      # A direct call of an MCP tool reloads as the call_tool row it ran as.
+      call = Tools::BuiltinCalls.unwrap_saved(Tools::BuiltinCalls.wrap_saved(call, output), output)
       name = call[:name].to_s
       params = shown.is_a?(String) ? shown : ToolActivity.tool_activity_params(name, call, registry: registry)
       part = { tool: name, params: params.to_s }

data/lib/samagotchi/output_formatter.rb

@@ -65,6 +65,10 @@ module Samagotchi
     # Qwen tool_call XML blocks that survive when a tool call is rendered as text
     # e.g. <tool_call>\n<function=list_reminders>\n</function>\n</tool_call>
     QWEN_TOOL_CALL_RE = %r{<tool_call>.*?</tool_call>}m
+    # Gemma 4's closed tool-call block, <|tool_call>call:NAME{…}<tool_call|>:
+    # a native step's call, whose body #strip_markup drops (#strip keeps it:
+    # a streamed chunk may hold only one marker).
+    GEMMA_TOOL_CALL_RE = /<\|tool_call>.*?<tool_call\|>/m
 
     module_function
 
@@ -85,9 +89,11 @@ module Samagotchi
 
     # The same tokens as #strip, but the text keeps its layout (indentation,
     # runs of spaces); only the blank lines removed blocks leave collapse.
-    # For showing a whole saved message (the attached TUI's join, the web history).
+    # For showing a whole saved message (the attached TUI's join, the web history):
+    # a native Gemma step's closed tool-call blocks go with their bodies, as
+    # Qwen's do (a step that only calls a tool has no text).
     def strip_markup(text)
-      remove_tokens(text).gsub(/\n[ \t]*\n(?:[ \t]*\n)+/, "\n\n").strip
+      remove_tokens(text.to_s.gsub(GEMMA_TOOL_CALL_RE, "")).gsub(/\n[ \t]*\n(?:[ \t]*\n)+/, "\n\n").strip
     end
 
     def remove_tokens(text)

data/lib/samagotchi/pending_question.rb

@@ -17,15 +17,19 @@ module Samagotchi
   # relayed approval's facts (Relay.card); limit, context: the step-limit
   # question's turn limit and offer context (ContinueOffer); status:
   # "pending" or "cancelled"; created_at: iso8601; relayed_to: the relay
-  # mark ({parent_id:, parent_short:, relay_id:}, QuestionDesk#annotate).
-  # approval, relay, context and relayed_to stay Hashes as given (string
+  # mark ({parent_id:, parent_short:, relay_id:}, QuestionDesk#annotate);
+  # refs: the refs on the reply that asks ({match:, kind:, target:, …},
+  # the :question_asked hooks', QuestionAsked; display only, checked again
+  # where a saved one reaches a UI).
+  # approval, relay, context, relayed_to and refs stay as given (string
   # keys inside after a load). A field may be nil (unset).
   #
   # Crosses the process as a Hash: #to_h for an event, a Bridge snapshot or
   # a UI (symbol keys), #to_file for session.json (string keys); both in
   # member order with unset fields left out. .from_file reads either back.
   PendingQuestion = Data.define(:id, :question, :options, :header, :multi_select, :allow_freeform, :effects, :user_only,
-                                :kind, :hook, :approval, :relay, :limit, :context, :status, :created_at, :relayed_to) do
+                                :kind, :hook, :approval, :relay, :limit, :context, :status, :created_at, :relayed_to,
+                                :refs) do
     def initialize(**fields)
       super(**members.to_h { |m| [m, nil] }, **fields)
     end

data/lib/samagotchi/plugin/api.rb

@@ -27,6 +27,11 @@ module Samagotchi
       # one (ctx.sessions.children) is listed when it came later. Keys have
       # no "?" (API_CALL drops it). A keyword added later (ctx.ask_model's
       # model: in 0.80.0, ctx.sessions.send's delivery: in 0.64.0) has none.
+      # Events aren't listed: chi.on takes any symbol and an older chi never
+      # fires one it doesn't know (harmless; chi bundle check warns on it),
+      # and a manifest hook's events: list (BundleHook) needs the bundle's
+      # requires_chi set by hand (docs/hooks.md, Bundle Hooks): no source
+      # scan covers manifest.yml.
       SINCE = {
         "ctx.steer" => "0.3.0", "ctx.stop_turn" => "0.3.0", "ctx.stop_generation" => "0.6.0",
         "Samagotchi::AtomicFile" => "0.8.0", "ctx.model" => "0.17.0", "ctx.model_key" => "0.17.0",
@@ -35,7 +40,7 @@ module Samagotchi
         "ctx.prompt_files" => "0.60.0", "chi.annotation" => "0.66.0", "chi.toolkit" => "0.66.0",
         "ctx.use_toolkit" => "0.66.0", "ctx.toolkit" => "0.66.0", "ctx.declared_tools" => "0.66.0",
         "chi.tool_source" => "0.67.0", "chi.peer_source" => "0.67.0", "ctx.http" => "0.80.0",
-        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0"
+        "ctx.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0", "ctx.load_tools" => "0.99.0"
       }.freeze
 
       # @param bundle [String]

data/lib/samagotchi/plugin/context.rb

@@ -48,7 +48,9 @@ module Samagotchi
     # :non_interactive), which ctx.frontend names for plugins.
     # +toolkit+ returns the session's toolkit name, +declared_tools+ the
     # tool names its next turn declares, +use_toolkit+ takes a name and
-    # returns whether it staged it (Engine#use_toolkit).
+    # returns whether it staged it (Engine#use_toolkit); +load_tools+ takes
+    # (names, bundle) and returns the wire names it staged
+    # (Engine#load_tools).
     # +cancel_controller+ takes (handler:) and returns the controller a
     # ctx.http call without cancel: uses, nil for none: an init task's own,
     # else the running turn's for work done for it (the turn's thread, or a
@@ -56,7 +58,7 @@ module Samagotchi
     # +cost+ returns the session's spend now (SessionMetrics::Cost).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
-                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
+                      :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
                       :cancel_controller, :cost, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
@@ -182,6 +184,23 @@ module Samagotchi
       # @raise [ArgumentError] a toolkit no one declared
       def use_toolkit(name) = !!@host.use_toolkit&.call(name.to_s)
 
+      # Load tools the session reaches but doesn't declare, so the model
+      # calls them by name (docs/plugins.md): built-in names, MCP tools'
+      # acts_as (mcp_fs_read) or <group>/<tool>. A hint, not access: the
+      # tools stay behind the same guardrails, and only a host that takes
+      # tool changes (api: anthropic) gets one; elsewhere nothing is sent.
+      # Called from before_turn, they load for that turn; anywhere else,
+      # from the next turn's start. Idempotent: a declared tool, one loaded
+      # before, a removed or unknown one is skipped.
+      # @param names [Array<String>]
+      # @return [Array<String>] the names staged (wire names)
+      # @raise [ArgumentError] +names+ isn't an Array
+      def load_tools(names)
+        raise ArgumentError, "load_tools takes an Array of tool names" unless names.is_a?(Array)
+
+        Array(@host.load_tools&.call(names.map(&:to_s), @bundle))
+      end
+
       # Whether the session is a `chi scratch` one (deleted when it ends).
       def scratch? = !!@host.scratch&.call
 

data/lib/samagotchi/prompt.rb

@@ -5,6 +5,7 @@ require_relative "prompt_literal_guard"
 require_relative "vision_context"
 require_relative "tool_response"
 require_relative "steer"
+require_relative "tool_loads"
 
 module Samagotchi
   # Formats a message list into a prompt string ready for the /completion endpoint.
@@ -48,6 +49,8 @@ module Samagotchi
     #   the model's answer (Thinking.native: Qwen's empty thought)
     # @return [Array(String, Array<String>)]
     def self.format_with_images(messages, profile: ModelProfile.default, vision: nil, prefill: "")
+      # A plugin's tool change (ToolLoads) is for a Messages host only.
+      messages = messages.reject { |message| ToolLoads.entry?(message) }
       plan = ImagePlan.new(messages, vision, data: :base64)
       images = []
       suffixes = messages.each_with_index.map { |m, index| image_lines(plan.items(m, index), profile, images) }

data/lib/samagotchi/question_asked.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "answer_refs"
+require_relative "log"
+require_relative "output_formatter"
+
+module Samagotchi
+  # The :question_asked hook event: a question of the model's own (its
+  # ask_user_question, kind "question") or an approval of its tool call
+  # (kind "approval") is about to open. Fired from the two Engine seams
+  # (Engine#request_question, the guardrail wiring's ask:), never from
+  # QuestionDesk, so a relayed delegate approval, a hook's ask_user and the
+  # step-limit question never fire it.
+  #
+  # A hook attaches refs to the reply that asks (event[:refs], after_turn's
+  # call shape and checks, AnswerRefs): they are kept as `display_refs` on
+  # the step's model message (the live conversation's last model entry,
+  # changed in place: the loops and the forget layer hold it by identity),
+  # display only, and go on the pending question (PendingQuestion#refs), so
+  # a UI pairs them in the asking text, on the card and in the history.
+  #
+  # The hooks run on the turn thread before the question opens: their time
+  # is the question's wait. A raising hook is logged (Registry#fire) and the
+  # question opens without its refs; event[:ask_user] is a no-op (nil).
+  module QuestionAsked
+    EVENT = :question_asked
+    KIND_QUESTION = "question"
+    KIND_APPROVAL = "approval"
+    # Lower than an answer's (AnswerRefs): cards.json holds up to 20 cards.
+    MAX_REFS = 50
+    MAX_BYTES = 32 * 1024
+
+    module_function
+
+    # Fire the event and return the question's fields with the step's refs
+    # (+fields+ as given when it has none, or with no subscriber: then
+    # nothing is built).
+    # @param hooks [Hooks::Registry]
+    # @param conversation [Array<Hash>, nil] the running turn's live
+    #   conversation (Engine#live_conversation)
+    # @param kind [String] KIND_QUESTION or KIND_APPROVAL
+    # @param fields [Hash] the question's fields (no id yet)
+    # @param cwd [String, nil] the session's folder, for file refs
+    # @param synchronize [#call, nil] runs the step's change under the
+    #   event lock (a snapshot reads the conversation under it)
+    # @param visible [#call, nil] (content) → the step's text as the asking
+    #   slot shows it; default OutputFormatter.strip_markup (the Engine's
+    #   drops the native loop's tool-call bodies first)
+    # @return [Hash] the fields to open the question with
+    def fire(hooks:, conversation:, kind:, fields:, cwd:, synchronize: nil, visible: nil)
+      return fields unless hooks&.any?(EVENT)
+
+      step = Array(conversation).reverse_each.find { |m| m.is_a?(Hash) && (m[:role] || m["role"]).to_s == "model" }
+      refs = AnswerRefs.new(step ? [step] : [], cwd: cwd, max_refs: MAX_REFS, max_bytes: MAX_BYTES)
+      visible ||= ->(content) { OutputFormatter.strip_markup(content) }
+      event = { type: EVENT, kind: kind, text: step ? visible.call((step[:content] || step["content"]).to_s) : "",
+                question: deep_freeze(Marshal.load(Marshal.dump(fields.to_h))),
+                # A question from here would wait inside the one opening.
+                ask_user: ->(**) {} }
+      event[:refs] = refs.adder(event)
+      hooks.fire(EVENT, event)
+      refs.close!
+      list = refs.to_a
+      if refs.added?
+        store = -> { step[AnswerRefs::KEY] = list }
+        synchronize ? synchronize.call(&store) : store.call
+      end
+      # The step's whole list: a second question in it gets the first's too.
+      list.empty? ? fields : fields.merge(refs: list)
+    rescue StandardError => e
+      Log.warn(:hooks, "question_asked_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+      fields
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash then value.each_value { |v| deep_freeze(v) }
+      when Array then value.each { |v| deep_freeze(v) }
+      end
+      value.freeze
+    end
+  end
+end

data/lib/samagotchi/question_desk.rb

@@ -120,10 +120,11 @@ module Samagotchi
     # 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.
-    # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
+    # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:},
+    #   and refs: (the asking step's, QuestionAsked) when it has any
     # @return [String] normalized answer JSON
     def request(payload)
-      result = open_question(payload.slice(:question, :options, :header)
+      result = open_question(payload.slice(:question, :options, :header, :refs)
                                     .merge(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.

data/lib/samagotchi/testing/bundle.rb

@@ -3,6 +3,7 @@
 require_relative "../plugin/loader"
 require_relative "../plugin/tool_spec"
 require_relative "../hooks"
+require_relative "../question_asked"
 require_relative "../commands/registry"
 require_relative "../session_commands"
 require_relative "../tools/builtins"
@@ -179,7 +180,7 @@ module Samagotchi
         end
         @hooks_namespace = Module.new
         @manifest.hooks.each do |basename, hook|
-          next if hook.event.empty?
+          next if hook.events.empty?
 
           Hooks::BundleLoader.load_hook_file(@name, basename, File.join(@dir, "hooks", basename), hook, hooks,
                                              settings: @settings, namespace: @hooks_namespace)
@@ -203,6 +204,22 @@ module Samagotchi
         payload
       end
 
+      # Fire :question_asked as chi's two seams do (QuestionAsked.fire): a
+      # question (+kind+ "question") or an approval ("approval") asked by a
+      # step whose text is +text+, with the question's +question+ fields.
+      # The hooks' refs are checked as chi checks them (the question caps,
+      # file refs under +cwd+, default the session's folder).
+      # @return [Array<Hash>] the refs the step and its pending question
+      #   get, as stored; [] for none
+      def question_asked(text, kind: "question", question: {}, cwd: nil)
+        step = { role: "model", content: text.to_s }
+        fields = failing do
+          QuestionAsked.fire(hooks: hooks, conversation: [step], kind: kind.to_s, fields: question.to_h,
+                             cwd: cwd || @recorder[:cwd])
+        end
+        Array(fields[:refs])
+      end
+
       # Build the before_tool_call payload from the real Gate, without firing
       # this bundle's hooks.
       # @param call [Hash] the parsed tool call
@@ -335,6 +352,8 @@ module Samagotchi
       def questions = @recorder.questions
       def model_requests = @recorder.model_requests
       def toolkit_uses = @recorder.toolkit_uses
+      # Every ctx.load_tools call (ToolLoad: names, bundle).
+      def tool_loads = @recorder.tool_loads
       # Queue ask_model answers: a String, an exception, or a callable.
       def model_answers = @recorder.model_answers
 

data/lib/samagotchi/testing/host.rb

@@ -47,6 +47,7 @@ module Samagotchi
           toolkit: -> { recorder[:toolkit] },
           declared_tools: -> { recorder[:declared_tools] || tool_names.call },
           use_toolkit: ->(name) { recorder.use_toolkit(name, toolkits.call) },
+          load_tools: ->(names, bundle) { recorder.load_tools(names, bundle) },
           cancel_controller: ->(handler: false) { recorder[:cancelled] ? stopped : nil },
           cost: -> { cost(recorder[:cost]) }
         )

data/lib/samagotchi/testing/recorder.rb

@@ -12,6 +12,8 @@ module Samagotchi
     Notice = Data.define(:text, :level, :hook, :fallback_for)
     # Text put into the running turn (ctx.steer, event[:steer]).
     Steer = Data.define(:text, :hook)
+    # A ctx.load_tools call: the names given, and the bundle.
+    ToolLoad = Data.define(:names, :bundle)
     # A stop_turn or stop_generation (+kind+ :turn or :generation).
     Stop = Data.define(:kind, :reason, :hook)
     # An ask_model request: the request Context built (SideQuestion), its
@@ -32,13 +34,13 @@ module Samagotchi
       DEFAULTS = {
         session_id: "test-session", cwd: nil, messages: [], messages_partial: false, model_name: "test:model",
         model_key: "model", toolkit: "full", declared_tools: nil, frontend: :worker, scratch: false, setup: nil,
-        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true,
+        prompt_files: [], cancelled: false, state_dir: nil, running: true, toolkit_staged: true, load_tools_staged: nil,
         # ctx.cost: nil (zero), a Float (reported USD), a Hash of the parts
         # (reported:, estimated:, side:, known:) or a callable giving one.
         cost: nil
       }.freeze
 
-      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :answers,
+      attr_reader :notices, :cards, :steers, :stops, :questions, :model_requests, :toolkit_uses, :tool_loads, :answers,
                   :model_answers, :values
 
       def initialize(**values)
@@ -53,6 +55,7 @@ module Samagotchi
         @questions = []
         @model_requests = []
         @toolkit_uses = []
+        @tool_loads = []
         @answers = []
         @model_answers = []
         @mutex = Mutex.new
@@ -127,6 +130,14 @@ module Samagotchi
         answer.respond_to?(:call) ? answer.call(entry) : answer
       end
 
+      # ctx.load_tools: recorded; every name is staged unless the test set
+      # load_tools_staged: (a list: those only).
+      def load_tools(names, bundle)
+        record(@tool_loads, ToolLoad.new(names: names, bundle: bundle))
+        staged = self[:load_tools_staged]
+        staged ? names & Array(staged) : names
+      end
+
       # ctx.use_toolkit: +known+ the toolkits chi and the plugins declare.
       # Staged (toolkit_staged:, true by default), the session is on it at
       # once, as chi saves it on the session (ToolkitBinding#use).