samagotchi 0.96.0 → 0.98.0

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/memory_bundle/profile.rb

@@ -80,7 +80,7 @@ module Samagotchi
       # "Shipped notes").
       def kept_own_line(member, file)
         "#{member}: kept your own #{file} (not the bundle's; to take the bundle's, remove yours with " \
-          "memory_write remove: true, then chi bundle install #{member})"
+          "chi memory rm #{file.delete_suffix(".md")} --scope system, then chi bundle install #{member})"
       end
 
       # The one rule.
@@ -121,19 +121,29 @@ module Samagotchi
         member_dir = File.join(shipped_dir, member)
         failure = Manifest.requires_chi_failure(Manifest.read(dir: member_dir).requires_chi, chi_version)
         return result.skipped[member] = failure if failure
-        return result.installed << member if dry_run
 
+        # A dry run runs the Installer's too, which writes nothing, so it
+        # names the files the real run would keep as the user's own.
         installer = Installer.new(source: member_dir, name: member, scope: "system", force: force, strict: true,
-                                  shipped_dir: shipped_dir)
+                                  shipped_dir: shipped_dir, dry_run: dry_run)
         installer.run
         result.installed << member
-        kept = installer.results.select { |_, entry| entry[:status] == "skipped" && entry[:reason] == "already exists" }.keys
+        kept = installer.results.select { |_, entry| kept_own?(entry) }.keys
         result.kept_own[member] = kept.sort unless kept.empty?
       rescue StandardError => e
         result.failed[member] = e.message.lines.first.to_s.strip
       end
       private_class_method :install_member
 
+      # An Installer result for a file the user already had, with other
+      # bytes: skipped ("already exists"), or a dry run's would_skip. One
+      # with the bundle's bytes ("already up to date") isn't named: nothing
+      # of the bundle's is missing (it stays the user's all the same).
+      def kept_own?(entry)
+        entry[:status] == "would_skip" || (entry[:status] == "skipped" && entry[:reason] == "already exists")
+      end
+      private_class_method :kept_own?
+
       # Uninstalls each recorded member still installed, then the meta. A
       # member that won't go (an edited .md file, without +force+) is
       # reported and the rest carry on; the meta then stays, still

data/lib/samagotchi/memory_command.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "memory_paths"
+require_relative "tools/memory"
+require_relative "memory_bundle/index_updater"
+require_relative "memory_bundle/provenance"
+
+module Samagotchi
+  # `chi memory`: the user's side of the memories (docs/memory.md). ls lists
+  # both scopes' entries from their index.md lines and files, as memory_read
+  # and the prompt see them; rm removes one as memory_write remove: true does
+  # (Tools::MemoryWrite.remove: the file and its model overlays into the
+  # bundle trash, the index line dropped, a bundle's memory refused).
+  class MemoryCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi memory <ls|rm> [options]
+        ls [--scope project|system] [--format text|json]   the memories: both scopes (this folder's project
+             first), or one; each with its size, date, the bundle it came from and its index description
+        rm NAME [--scope project|system]   remove a memory: its file and its model overlays (NAME.<key>.md)
+             move to the bundle trash (chi bundle trash lists and empties it) and its index line is dropped.
+             Without --scope NAME must be in one scope only. A bundle's memory is refused: chi bundle
+             uninstall removes it. NAME.<key> removes one model overlay alone.
+    TEXT
+
+    SUBCOMMANDS = %w[ls rm].freeze
+    SCOPES = Tools::VALID_SCOPES
+    # The description column's width in ls's text form (json has it all).
+    DESCRIPTION_WIDTH = 60
+    # ls's size column, right-aligned.
+    SIZE_COLUMN = 2
+
+    FLAGS = {
+      "ls" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--scope"
+        f.value "--format"
+      end,
+      "rm" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--scope" }
+    }.freeze
+
+    # One memory of a scope. +date+ is the index line's (the file's mtime
+    # when it has none); +source+ the bundle that owns it; +overlays+ the
+    # model keys of its overlays; +indexed+ / +file+: whether it has an
+    # index line / a file (a line whose file was deleted by hand has none).
+    Entry = Data.define(:name, :scope, :path, :bytes, :date, :source, :description, :overlays, :indexed, :file) do
+      def to_h = super.transform_keys(&:to_s)
+    end
+
+    # A managed index line: "- **name** · scope · date · size[ · from b][ — desc]"
+    # or a legacy "- **name**: desc" (MemoryWrite.managed_pattern).
+    LINE = /^- \*\*([^*\n]+)\*\*[ \t]*(?:[·•][^\n]*|:[^\n]*)?$/
+
+    # @param argv [Array<String>] the arguments after "memory"
+    # The project scope is the cwd's project, as for the memory tools.
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
+    def run
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return CLI::Exit::OK
+      end
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      scope = parsed.options[:scope]
+      return usage_error("unknown scope #{scope.inspect}: use --scope project|system") if scope && !SCOPES.include?(scope)
+
+      send(:"run_#{@sub}", parsed.options, parsed.args)
+    end
+
+    # The memories of +scope+ (project first, then system, when nil), by
+    # name within a scope.
+    # @return [Array<Entry>]
+    def self.entries(scope = nil)
+      owners = MemoryBundle::Provenance.each_installed.reject { |_, bundle| bundle.error? }
+      (scope ? [scope] : SCOPES).flat_map { |s| scope_entries(s, owners) }
+    end
+
+    def self.scope_entries(scope, owners)
+      dir = MemoryPaths.scope_dir(scope)
+      return [] unless File.directory?(dir)
+
+      index_path = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
+      index_text = File.file?(index_path) ? File.read(index_path, encoding: "UTF-8") : ""
+      # name => its line; the first one when a name has two. A name rm
+      # would refuse (a path: "../x") isn't listed.
+      lines = {}
+      index_text.each_line do |l|
+        (m = l.chomp.match(LINE)) or next
+        lines[m[1]] ||= m[0] unless Tools::MemoryRead.invalid_name?(m[1])
+      end
+      stems = Dir.children(dir).filter_map { |f| f.delete_suffix(".md") if f.end_with?(".md") && File.file?(File.join(dir, f)) }.to_set
+      overlays = overlays_by_base(stems, lines)
+      overlay_stems = overlays.values.flatten(1).to_set { |_key, stem| stem }
+      names = (lines.keys + stems.to_a).uniq - [Tools::MEMORY_INDEX]
+      names.filter_map do |name|
+        next if overlay_stems.include?(name)
+
+        path = File.join(dir, "#{name}.md")
+        line = lines[name]
+        file = stems.include?(name)
+        # A bold line of prose ("- **Important**") isn't a memory: only a
+        # managed line ("· …") counts without a file.
+        next unless file || line&.include?(" · ")
+
+        entry(name, scope, path, line, file, overlays.fetch(name, []).map(&:first), owners)
+      end.sort_by(&:name)
+    end
+
+    # base name => [[key, stem]...] of its model overlays, in one pass over
+    # the files (+stems+, a Set): <base>.<key>.md with a key ModelOverlay
+    # makes, whose base is a file and whose stem has no index line of its
+    # own (MemoryWrite.overlay_files' rule, for every base at once).
+    def self.overlays_by_base(stems, lines)
+      stems.sort.each_with_object({}) do |stem, by_base|
+        base, dot, key = stem.rpartition(".")
+        next if dot.empty? || base.empty? || !key.match?(/\A[a-z0-9-]+\z/)
+        next unless stems.include?(base) && !lines.key?(stem)
+
+        (by_base[base] ||= []) << [key, stem]
+      end
+    end
+
+    def self.entry(name, scope, path, line, file, overlay_keys, owners)
+      source = line && MemoryBundle::IndexUpdater.extract_source(line)
+      source ||= owners.find { |_, bundle| bundle.effective_scope == scope && bundle.owns?("#{name}.md") }&.first
+      Entry.new(
+        name: name, scope: scope, path: path, bytes: file ? File.size(path) : nil,
+        date: line.to_s[/ · (\d{4}-\d{2}-\d{2})\b/, 1] || (file ? File.mtime(path).strftime("%Y-%m-%d") : nil),
+        source: source, description: line && line.include?(" · ") ? line.split(" — ", 2)[1]&.strip : legacy(line),
+        overlays: overlay_keys,
+        indexed: !line.nil?, file: file
+      )
+    end
+
+    # A legacy "- **name**: desc" line's description.
+    def self.legacy(line) = line&.split("**:", 2)&.[](1)&.strip&.then { |d| d.empty? ? nil : d }
+    private_class_method :scope_entries, :overlays_by_base, :entry, :legacy
+
+    private
+
+    def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi memory #{@sub}" : "chi memory"
+    def usage_on_error = nil
+
+    def run_ls(options, args)
+      return usage_error("ls takes no NAME (unexpected #{args.first})") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+
+      rows = self.class.entries(options[:scope])
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(rows.map(&:to_h)))
+      elsif rows.empty?
+        @stdout.puts("no memories#{" in #{options[:scope]} scope" if options[:scope]}")
+      else
+        print_rows(rows)
+      end
+      CLI::Exit::OK
+    end
+
+    def print_rows(rows)
+      table = rows.map do |r|
+        notes = []
+        notes << "overlays: #{r.overlays.join(", ")}" unless r.overlays.empty?
+        notes << "no file" unless r.file
+        notes << "no index line" unless r.indexed
+        [r.scope, r.name, r.bytes.to_s, r.date.to_s, r.source ? "from #{r.source}" : "",
+         [clip(r.description.to_s), *notes.map { |n| "[#{n}]" }].reject(&:empty?).join(" ")]
+      end
+      widths = table.transpose.map { |column| column.map(&:length).max }
+      # A column no row fills (no memory from a bundle) takes no room.
+      table.each do |line|
+        cells = line.each_with_index.map { |cell, i| i == SIZE_COLUMN ? cell.rjust(widths[i]) : cell.ljust(widths[i]) }
+        @stdout.puts(cells.reject.with_index { |_, i| widths[i].zero? }.join("  ").rstrip)
+      end
+    end
+
+    def clip(text) = text.length > DESCRIPTION_WIDTH ? "#{text[0, DESCRIPTION_WIDTH - 1]}…" : text
+
+    def run_rm(options, args)
+      name = args.shift
+      return usage_error("give the memory's NAME") unless name
+      return usage_error("rm takes one NAME (unexpected #{args.first})") unless args.empty?
+
+      scope = options[:scope] || only_scope(name)
+      return scope if scope.is_a?(Integer)
+
+      result = Tools::MemoryWrite.call(nil, path: name, scope: scope, remove: true)
+      if result.start_with?("Error: ")
+        error_line("#{command_name}: #{result.delete_prefix("Error: ")}")
+        return CLI::Exit::FAILED
+      end
+
+      @stdout.puts(result)
+      CLI::Exit::OK
+    end
+
+    # The one scope +name+ is in (a file or an index line), else the exit
+    # status: a usage error when it is in both, a failure in neither (an
+    # invalid name goes on to remove's own error).
+    # @return [String, Integer]
+    def only_scope(name)
+      return "project" if Tools::MemoryRead.invalid_name?(name) || name == Tools::MEMORY_INDEX
+
+      found = SCOPES.select { |scope| present?(name, scope) }
+      case found.size
+      when 1 then found.first
+      when 0
+        error_line("#{command_name}: no memory '#{name}' in project or system scope")
+        CLI::Exit::FAILED
+      else
+        usage_error("#{name} is in both scopes: chi memory rm #{name} --scope project, or --scope system")
+      end
+    end
+
+    def present?(name, scope)
+      dir = MemoryPaths.scope_dir(scope)
+      index = File.join(dir, "#{Tools::MEMORY_INDEX}.md")
+      File.file?(File.join(dir, "#{name}.md")) ||
+        (File.file?(index) && File.read(index, encoding: "UTF-8").match?(Tools::MemoryWrite.managed_pattern(name)))
+    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

@@ -21,8 +21,17 @@ module Samagotchi
       # The first chi release with each call a plugin may make (from git:
       # the first release tag holding it), for `chi bundle check`'s
       # requires-chi-floor: a bundle whose requires_chi admits an older chi.
-      # A call not listed gets no floor check: it came before the first tag
-      # (v0.2.0), or isn't listed yet. Keys have no "?" (API_CALL drops it).
+      # A call not listed gets no floor check: it is in the first tag (v0.2.0:
+      # chi.command/tool/on/service/init, ctx.settings, ctx.sessions,
+      # ctx.ask_model, ctx.notify, ctx.card, ctx.messages…). A member of
+      # 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",
@@ -31,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.cost" => "0.83.0", "ctx.sessions.children" => "0.34.0"
       }.freeze
 
       # @param bundle [String]

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/send_command.rb

@@ -685,13 +685,12 @@ module Samagotchi
         return true
       end
 
-      ack = result.ack
       @delivered = result
       # What the worker applied, for --format json: its ack's delivery
       # (next_step for an idle session) and a cut's outcome.
-      @sent_delivery = ack["delivery"] || delivery
-      @sent_cut = ack["cut"]
-      @info.puts("#{short}  sent#{with_images}#{delivery_note(ack, delivery: delivery, running: running, owner: owner)}")
+      @sent_delivery = result.delivery || delivery
+      @sent_cut = result.cut
+      @info.puts("#{short}  sent#{with_images}#{delivery_note(result, delivery: delivery, running: running, owner: owner)}")
       true
     rescue SessionManager::OwnedByTUI
       @info.puts("#{short}  refused: it is open in a chi REPL; messages need attached mode")
@@ -706,11 +705,12 @@ module Samagotchi
     # the outcome from the ack (now, waits, off); a --queue one runs after
     # the turn (or now, when the turn ended before it went in); images keep
     # their own wording; an idle session's turn simply runs.
-    # @param ack [Hash] the Bridge's 202 body ({} for the input file)
+    # @param result [SessionManager::DeliverResult] the accepted delivery
+    #   (its ack is {} for the input file)
     # @return [String] "" or " (...)"
-    def delivery_note(ack, delivery:, running:, owner:)
+    def delivery_note(result, delivery:, running:, owner:)
       return " (started its worker)" if owner.nil?
-      return queue_note(ack, running: running) if Delivery.queue?(delivery)
+      return queue_note(result, running: running) if Delivery.queue?(delivery)
       return "" unless running
 
       # A busy worker runs a message with images as its own next turn
@@ -720,18 +720,18 @@ module Samagotchi
       # The TUIs' words for a cut's outcome. No outcome: a plain message,
       # or the input file (the Bridge went away), which the next step's
       # drain takes.
-      outcome = Delivery.cut?(delivery) ? ack["cut"].to_s : ""
+      outcome = Delivery.cut?(delivery) ? result.cut.to_s : ""
       return " (goes in at the running turn's next step)" unless CUT_OUTCOMES.include?(outcome)
 
-      " #{TerminalUI::Formatting.steer_cut_note(outcome.to_sym, ack["cut_after"])}"
+      " #{TerminalUI::Formatting.steer_cut_note(outcome.to_sym, result.cut_after)}"
     end
 
     # A --queue, worded from the Bridge's ack: queue when a turn ran as it
     # went in (one another client started too), next_step when none did
     # (it runs now). The input file (no Bridge) carries the queue to
     # whichever turn runs: worded from the session as chi read it.
-    def queue_note(ack, running:)
-      queued = ack.key?("delivery") ? ack["delivery"] == Delivery::QUEUE : running
+    def queue_note(result, running:)
+      queued = result.delivery.nil? ? running : result.delivery == Delivery::QUEUE
       return " (queued: runs after the current turn)" if queued
 
       running ? " (the running turn had ended: it runs now)" : " (nothing running: it runs now)"

data/lib/samagotchi/session_inbox.rb

@@ -359,6 +359,35 @@ module Samagotchi
     end
     private_class_method :unmark_removed
 
+    # How old a per-input tombstone (input/removed/, TurnCheckpoint's
+    # input/settled/) gets before a worker's start prunes it (#prune_old).
+    # A wait reads one at its next poll (ReplyWait::POLL_INTERVAL) and a
+    # later `chi send --wait --turn` reads a settled one at its start, so
+    # only a wait whose process slept (a closed laptop) or one started long
+    # after needs it to stay. A removed one gone under a live wait would
+    # read as a merge (the wrong reply), so the age is generous: a week,
+    # half the session retention (14 days), for one small file per
+    # file-delivered command or dequeue.
+    TOMBSTONE_MAX_AGE = 7 * 24 * 3600
+
+    # Deletes the files in input/<+subdir+> last written more than
+    # +max_age+ seconds ago; one that can't be read or deleted stays.
+    # @return [Integer] how many went
+    def self.prune_old(session_dir, subdir, max_age: TOMBSTONE_MAX_AGE)
+      cutoff = Time.now - max_age
+      Dir.glob(File.join(session_dir, INPUT_DIR, subdir, "*")).count do |file|
+        next false unless File.mtime(file) < cutoff
+
+        File.delete(file)
+        true
+      rescue SystemCallError
+        false
+      end
+    end
+
+    # The removed tombstones past +max_age+ (#prune_old).
+    def self.prune_removed(session_dir, max_age: TOMBSTONE_MAX_AGE) = prune_old(session_dir, REMOVED_DIR, max_age: max_age)
+
     # @return [Boolean] whether the queued input +enqueued_id+ was removed
     #   before it ran (#take_queued_input's tombstone), or is being removed:
     #   the tombstone goes first, so while its claimed file is still there

data/lib/samagotchi/session_manager.rb

@@ -1177,6 +1177,17 @@ module Samagotchi
       def error = ack["error"]
 
       def detail = ack["detail"]
+
+      # What the worker applied (a Bridge ack only): the delivery asked for,
+      # or next_step for a --queue that found no turn running; nil from the
+      # input file or a worker older than delivery.
+      def delivery = ack["delivery"]
+
+      # A --cut's outcome ("now", "waits", "off"), nil when nothing was cut.
+      def cut = ack["cut"]
+
+      # The steer cut-after seconds, with a cut that waits only.
+      def cut_after = ack["cut_after"]
     end
 
     # Hand a user message to the session the way a UI does, for the web