samagotchi 0.97.0 → 0.98.0

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -69,9 +69,9 @@ module Samagotchi
 
             hook = MemoryBundle::BundleHook.parse(raw_meta)
             # A hook with no declared event cannot be auto-registered.
-            next if hook.event.empty?
+            next if hook.events.empty?
 
-            fail_closed = hook.on_error == "fail_closed" && hook.event == "before_tool_call"
+            fail_closed = hook.events.any? { |event| hook.fail_closed?(event) }
             what = "hook #{basename} (bundle #{bundle_name})"
             file = hooks_dir && File.join(hooks_dir, basename)
             unless file && File.exist?(file)
@@ -98,9 +98,10 @@ module Samagotchi
           loaded
         end
 
-        # Build one hook file and register it in +registry+ under its
-        # event, priority and error policy (a fail_closed before_tool_call
-        # one denies when it raises). No missing-file, sha or requires_chi
+        # Build one hook file and register it in +registry+ under each of
+        # its events (one instance for all: its state is shared), with its
+        # priority and error policy (a fail_closed before_tool_call one
+        # denies when it raises). No missing-file, sha or requires_chi
         # check: #load makes them; the test kit loads a bundle's source
         # this way.
         # @param hook [MemoryBundle::BundleHook] its manifest entry
@@ -109,17 +110,19 @@ module Samagotchi
         # @raise [Exception] what loading or building the file raised;
         #   nothing is registered then
         def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil)
-          event_sym = hook.event.to_sym
-          fail_closed = hook.on_error == "fail_closed" && event_sym == :before_tool_call
           plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
-          policy = if fail_closed then :deny
-                   elsif hook.on_error == "log" then :log
-                   else :skip
-                   end
-          label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-          handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                               fields: { bundle: bundle_name }) { |event| plugin.call(event) }
-          registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          hook.events.each do |event_name|
+            event_sym = event_name.to_sym
+            fail_closed = hook.fail_closed?(event_sym)
+            policy = if fail_closed then :deny
+                     elsif hook.on_error == "log" then :log
+                     else :skip
+                     end
+            label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
+            handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                                 fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+            registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          end
           nil
         end
 

data/lib/samagotchi/hooks.rb

@@ -24,12 +24,15 @@ module Samagotchi
   #   :before_tool_call   — before a tool is dispatched: vote with event[:guardrail].deny!/ask!
   #                         (or the older event[:blocked]=true + event[:block_reason]); the
   #                         event also has context: and targets: (docs/guardrails.md)
+  #   :question_asked     — a question of the model's (ask_user_question) or an approval of its
+  #                         call is about to open: event[:refs] attaches refs to the asking
+  #                         reply (QuestionAsked)
   #   :after_tool_call    — after tool execution, before result injection
   module Hooks
     # Every event a hook can be registered for, in a turn's order
     # (docs/hooks.md). Plugin::Api#on takes any symbol: `chi bundle check`
     # warns on one not here.
     EVENTS = %i[session_start before_turn before_generation generation_progress after_generation before_tool_call
-                after_tool_call after_turn session_end].freeze
+                question_asked after_tool_call after_turn session_end].freeze
   end
 end

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/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/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",

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

data/lib/samagotchi/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -14,6 +14,7 @@ require_relative "../client_id"
 require_relative "../delivery"
 require_relative "../answer_tail"
 require_relative "../answer_refs"
+require_relative "../question_asked"
 require_relative "../bridge_client"
 require_relative "../bridge/bounded_queue"
 require_relative "../bridge/card_store"
@@ -839,7 +840,7 @@ module Samagotchi
           plugin_warning: turn_snapshot && turn_snapshot["plugin_warning"],
           # Plugins' slow setup still running (chi.init): the page's init row.
           init_tasks: snapshot_list(turn_snapshot, "init_tasks"),
-          cards: cards_for_display(live_or_saved(turn_snapshot, "cards") { saved_cards(id) }),
+          cards: cards_for_display(live_or_saved(turn_snapshot, "cards") { saved_cards(id) }, cwd: session.working_directory),
           # The composer's / autocomplete; the built-ins until a worker
           # names its plugins' too.
           commands: turn_snapshot&.fetch("commands", nil) || SessionCommands.builtin_registry.listing,
@@ -871,13 +872,28 @@ module Samagotchi
       # dead worker saved can't be answered (its turn is gone), nor a chi
       # REPL's (it shares nothing with the web).
       # A question between turns (the step-limit one) is the snapshot's own.
+      # Its refs (the asking reply's, QuestionAsked) are checked again.
       def shown_pending_question(session, turn_snapshot, owner)
-        if turn_snapshot
-          current_turn = turn_snapshot["current_turn"]
-          current_turn ? current_turn["pending_question"] : turn_snapshot["pending_question"]
-        elsif owner&.worker?
-          session.pending_question&.to_h
-        end
+        pending = if turn_snapshot
+                    current_turn = turn_snapshot["current_turn"]
+                    current_turn ? current_turn["pending_question"] : turn_snapshot["pending_question"]
+                  elsif owner&.worker?
+                    session.pending_question&.to_h
+                  end
+        with_question_refs(pending, cwd: session.working_directory)
+      end
+
+      # A pending question (a snapshot's, the session file's or a saved
+      # card's) with its refs checked again, under a question's caps
+      # (QuestionAsked): a stored file is never trusted, and what isn't
+      # valid any more is dropped. The question as it was without refs.
+      def with_question_refs(pending, cwd:)
+        return pending unless pending.is_a?(Hash)
+
+        key = [:refs, "refs"].find { |name| pending.key?(name) } or return pending
+        refs = Samagotchi::AnswerRefs.for_display(pending[key], cwd: cwd, max_refs: Samagotchi::QuestionAsked::MAX_REFS,
+                                                                max_bytes: Samagotchi::QuestionAsked::MAX_BYTES)
+        refs.empty? ? pending.except(key) : pending.merge(key => refs)
       end
 
       # The full show's session part: the file's, with what a live worker's
@@ -1031,11 +1047,16 @@ module Samagotchi
       # cards: CardStore#list), else (no live worker) the ones the last
       # worker saved in the session's folder (#saved_cards), a card's body as
       # body_html: rendered markdown when the renderer is on, else the
-      # escaped text in a <pre>.
+      # escaped text in a <pre>, and a question card's refs checked again
+      # (#with_question_refs; +cwd+ the session's folder, nil where the
+      # session file isn't read: a file ref then stays only absolute).
       # @return [Array<Hash>]
-      def cards_for_display(cards)
+      def cards_for_display(cards, cwd: nil)
         Array(cards).filter_map do |card|
           next unless card.is_a?(Hash)
+          if card["type"].to_s == "question" && card["pending_question"].is_a?(Hash)
+            next card.merge("pending_question" => with_question_refs(card["pending_question"], cwd: cwd))
+          end
           next card unless card["type"].to_s == "card"
 
           card.merge("body_html" => card_body_html(card["body"].to_s))