samagotchi 0.85.0 → 0.87.0

data/lib/samagotchi/kernel_loop.rb

@@ -525,8 +525,11 @@ module Samagotchi
     end
 
     # The payload a :generation_chunk event carries: llama.cpp's last chunk
-    # echoes the whole rendered prompt, which nothing reads and every SSE
-    # client would get (the kernel's own reads keep the full payload).
+    # echoes the whole rendered prompt, which nothing reads. SSE clients get
+    # no payload at all (Bridge::ClientEvent), but the event is still written
+    # to the debug log and handed to in-process observers (the ring, which
+    # `?raw=1` replays, SessionMetrics, hooks), so the prompt stays out of
+    # it (the kernel's own reads keep the full payload).
     def event_payload(payload)
       payload.is_a?(Hash) ? payload.except("prompt") : payload
     end

data/lib/samagotchi/llm/anthropic_assembly.rb

@@ -102,7 +102,7 @@ module Samagotchi
 
       # +event+ as on_delta passes it on: one that carries usage gets the
       # usage so far in the OpenAI shape as its `usage` (SessionMetrics,
-      # ContextStatus and ctx.js read that).
+      # ContextStatus and the Bridge's chunk `counts` read that).
       def with_usage(event)
         return event unless %w[message_start message_delta].include?(event["type"]) && (payload = usage_payload)
 

data/lib/samagotchi/memory_bundle/shas.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "digest"
+require "yaml"
+
+module Samagotchi
+  module MemoryBundle
+    # A bundle manifest's sha256 lines, recomputed from the files they name:
+    # `rake bundles:sha` for the shipped bundles and `chi bundle check --fix`
+    # for anyone's. Plain Ruby (no chi requires), so the release tools load
+    # it on their own.
+    module Shas
+      class Error < StandardError; end
+
+      # A sha line that doesn't match its file: +old+ is the hex the line
+      # holds ("" for a placeholder `sha256: sha256:`), nil when the entry
+      # has no sha line at all (a plugin:, hooks: or scripts: entry the
+      # installer then takes unchecked; .refresh can't write one).
+      Stale = Data.define(:file, :old, :new)
+
+      # What may follow a sha value on its line: a comment, then the line end
+      # (\r\n kept as it was).
+      TAIL = /(?:[ \t]+#[^\r\n]*)?[ \t]*\r?\n?\z/
+      # A sha value with what follows it, for the rewrite.
+      VALUE = /sha256:(\h*)((?:[ \t]+#[^\r\n]*)?)[ \t]*(\r?\n?)\z/
+
+      module_function
+
+      # The manifest text with every sha256 line recomputed from the file it
+      # names, the layout otherwise untouched. The shapes:
+      #   files:            a.md: sha256:<hex>             (dir/a.md)
+      #                     a.md:\n    sha256: sha256:<hex> (dir/a.md, with description:)
+      #   hooks:            h.rb:\n    sha256: sha256:<hex> (dir/hooks/h.rb)
+      #   plugin:           file: p.rb\n  sha256: sha256:<hex> (dir/p.rb)
+      #   scripts:          s.rb: sha256:<hex>             (dir/scripts/s.rb)
+      # Returns [text, [[relative file, old sha, new sha], ...]] for the lines
+      # that changed. +text+ defaults to dir/manifest.yml. A named file that's
+      # missing raises, and so does a files: entry none of those shapes
+      # matched (a quoted sha, a flow mapping), which would otherwise be
+      # skipped without a word.
+      def refresh(dir, text = File.read(File.join(dir, "manifest.yml")))
+        text, changes, = scan(dir, text)
+        [text, changes]
+      end
+
+      # The stale sha lines of the bundle at +dir+, then the plugin:, hooks:
+      # and scripts: entries with no sha line, as [Stale].
+      def stale(dir, text = File.read(File.join(dir, "manifest.yml")))
+        _, changes, unlined = scan(dir, text)
+        changes.map { |file, old, new| Stale.new(file, old, new) } +
+          unlined.map { |file| Stale.new(file, nil, digest(dir, file)) }
+      end
+
+      def scan(dir, text)
+        parsed = YAML.safe_load(parseable(text)) || {}
+        plugin_file = parsed.dig("plugin", "file")
+        top = sub = nil
+        changes = []
+        seen = []
+        lines = text.lines.map do |line|
+          if line.match?(/\A[^\s#]/)
+            top = line[/\A([^\s#][^:]*):/, 1]
+            sub = nil
+          end
+          sub = line[/\A  ([^\s#][^:]*):/, 1] if line.match?(/\A  [^\s#]/)
+          file, prefix = sha_line(line, top, sub, plugin_file)
+          next line unless file
+
+          seen << file
+          _, old, comment, eol = line.match(VALUE).to_a
+          new = digest(dir, file)
+          changes << [file, old, new] unless old == new
+          "#{prefix}sha256:#{new}#{comment}#{eol}"
+        end
+        unread = keys(parsed["files"]) - seen
+        unless unread.empty?
+          raise Error, "#{File.basename(dir)}/manifest.yml: no sha line to refresh for files: #{unread.join(", ")} " \
+                       "(write `name: sha256:<hex>`, or a mapping with an unquoted `sha256: sha256:<hex>` line)"
+        end
+        [lines.join, changes, coded(parsed, plugin_file) - seen]
+      end
+      private_class_method :scan
+
+      # +text+ with each placeholder `sha256: sha256:` given a hex digit: a
+      # value that ends in a colon isn't YAML. Manifest readers that should
+      # take a placeholder (`chi bundle check`) parse this text.
+      def parseable(text) = text.gsub(/^(\s*(?:["']?[^"':\s][^"':]*["']?: )?)sha256:(?=[ \t]*(?:#[^\r\n]*)?\r?$)/, "\\1sha256:0")
+
+      # The code files the manifest names (plugin, hooks, scripts), as paths
+      # relative to the bundle dir.
+      def coded(parsed, plugin_file)
+        (plugin_file.is_a?(String) ? [plugin_file] : []) +
+          keys(parsed["hooks"]).map { |h| File.join("hooks", h) } +
+          keys(parsed["scripts"]).map { |s| File.join("scripts", s) }
+      end
+      private_class_method :coded
+
+      def keys(section) = section.is_a?(Hash) ? section.keys.map(&:to_s) : []
+      private_class_method :keys
+
+      def digest(dir, file)
+        path = File.join(dir, file)
+        raise Error, "#{File.basename(dir)}/manifest.yml names #{file}, which isn't there" unless File.file?(path)
+
+        Digest::SHA256.hexdigest(File.binread(path))
+      end
+      private_class_method :digest
+
+      # [file relative to the bundle dir, the line up to its sha256: value] for a
+      # sha line, nil for any other line.
+      def sha_line(line, top, sub, plugin_file)
+        case top
+        when "files"
+          m = line.match(/\A(    sha256: )sha256:\h*#{TAIL}/) and return sub && [sub.delete("\"'"), m[1]]
+          m = line.match(/\A(  ["']?([^"':]+)["']?: )sha256:\h*#{TAIL}/) and [m[2], m[1]]
+        when "hooks"
+          m = line.match(/\A(    sha256: )sha256:\h*#{TAIL}/) and sub and [File.join("hooks", sub.delete("\"'")), m[1]]
+        when "plugin"
+          m = line.match(/\A(  sha256: )sha256:\h*#{TAIL}/) and plugin_file and [plugin_file, m[1]]
+        when "scripts"
+          m = line.match(/\A(  ["']?([^"':]+)["']?: )sha256:\h*#{TAIL}/) and [File.join("scripts", m[2]), m[1]]
+        end
+      end
+      private_class_method :sha_line
+    end
+  end
+end

data/lib/samagotchi/memory_bundle.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "memory_bundle/manifest"
+require_relative "memory_bundle/shas"
 require_relative "memory_bundle/source"
 require_relative "memory_bundle/provenance"
 require_relative "memory_bundle/placeholder"

data/lib/samagotchi/parent_answers_command.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "guardrails/parent_policy"
+
+module Samagotchi
+  # /parent-answers, the session's own guardrails.parent_answers
+  # (Session#parent_answers): with no argument, the level that applies, the
+  # session's own and config.yml's; `/parent-answers LEVEL` (hard, standard,
+  # soft) or `default` (none of its own) sets it, saved at once, for the next
+  # answer a parent gives. It may only tighten config.yml's
+  # (Guardrails::ParentPolicy.effective). Tightening goes from anyone;
+  # loosening (toward soft, or default) only from a user at a UI: the REPL,
+  # an attached TUI, the web (+user_ui+). A parent agent's line (chi send,
+  # a piped or marked attach, a delegate's follow-up) is refused.
+  class ParentAnswersCommand
+    NAME = "/parent-answers"
+    USAGE = "usage: #{NAME} [hard|standard|soft|default]".freeze
+    REFUSED = "loosening parent_answers is the user's: #{NAME} in chi --attach, the REPL or the web " \
+              "(not chi send or a parent agent)".freeze
+
+    # What +args+ (the text after the name) asks for.
+    # @return [Array] [:show], [:set, level or nil (default)] or [:usage]
+    def self.parse(args)
+      words = args.to_s.split
+      return [:show] if words.empty?
+      return [:usage] if words.size > 1
+
+      word = words.first.downcase
+      return [:set, nil] if word == Guardrails::ParentPolicy::UNSET
+
+      Guardrails::ParentPolicy::ORDER.include?(word) ? [:set, word] : [:usage]
+    end
+
+    # Whether the command line +line+ loosens a session whose own value is
+    # +current+ (chi send's early refusal, before it sends the line).
+    def self.loosens?(line, current)
+      kind, value = parse(line.to_s.strip.delete_prefix(NAME))
+      kind == :set && Guardrails::ParentPolicy.looser?(current, value)
+    end
+
+    # @param engine [Engine] #session
+    # @param save [#call] saves the session after a change
+    def initialize(engine:, save:)
+      @engine = engine
+      @save = save
+    end
+
+    # @param args [String] what follows /parent-answers
+    # @param user_ui [Boolean] a user at a UI typed it: it may loosen
+    # @return [Array(String, Boolean, Symbol)] the reply, whether the
+    #   session's value changed, and :ok or :error
+    def run(args, user_ui:)
+      session = @engine.session or return ["no session yet", false, :error]
+      kind, value = self.class.parse(args)
+      return [USAGE, false, :error] if kind == :usage
+      return [listing(session), false, :ok] if kind == :show
+      return ["#{listing(session)}\n(no change)", false, :ok] if value == session.parent_answers
+      return [REFUSED, false, :error] if Guardrails::ParentPolicy.looser?(session.parent_answers, value) && !user_ui
+
+      session.parent_answers = value
+      @save.call(session)
+      capped = Guardrails::ParentPolicy.capped_note(value)
+      [[listing(session), ("(#{capped})" if capped)].compact.join("\n"), true, :ok]
+    end
+
+    private
+
+    # "parent answers: standard (this session: standard; config.yml
+    # guardrails.parent_answers: soft)"
+    def listing(session)
+      config = Guardrails::ParentPolicy.current
+      effective = Guardrails::ParentPolicy.for_session(session)
+      own = session.parent_answers || "none"
+      # A hand-edited value that isn't a level: fail-closed, said here.
+      own = "#{own} (unreadable value, read as hard)" if session.parent_answers &&
+                                                         !Guardrails::ParentPolicy::ORDER.include?(session.parent_answers)
+      "parent answers: #{effective.name} (this session: #{own}; config.yml #{config.label})"
+    end
+  end
+end

data/lib/samagotchi/parent_report.rb

@@ -5,6 +5,8 @@ require "json"
 
 require_relative "cli/exit"
 require_relative "pending_question"
+require_relative "session"
+require_relative "guardrails/parent_policy"
 
 module Samagotchi
   # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
@@ -76,18 +78,20 @@ module Samagotchi
     # @param extra [Hash] more keys for the object (chi answer's
     #   answered_here: false)
     # @return [Hash] the --format json object
-    def json(result, session_id:, timeout: nil, extra: {})
+    # @param strategy [Guardrails::ParentPolicy::Strategy, nil] what a parent
+    #   may pick on the waited-for session (#strategy_for); nil: config.yml's
+    def json(result, session_id:, timeout: nil, extra: {}, strategy: nil)
       report = { status: status(result), session_id: session_id }
       report[:turn_id] = result.turn_id unless result.turn_id.to_s.empty?
       case report[:status]
       when "answered" then report[:text] = result.text.to_s
       when "question"
-        question = question(result.question)
+        question = question(result.question, strategy: strategy)
         report[:question] = question
         report[:answer_with] = answer_with(session_id, question)
       else
         report.merge!(stop_facts(result))
-        report[:detail] = detail(result, session_id: session_id, timeout: timeout)
+        report[:detail] = detail(result, session_id: session_id, timeout: timeout, strategy: strategy)
       end
       report.merge(extra)
     end
@@ -105,8 +109,8 @@ module Samagotchi
     end
 
     # @return [String] the JSON object as one line
-    def json_line(result, session_id:, timeout: nil, extra: {})
-      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra))
+    def json_line(result, session_id:, timeout: nil, extra: {}, strategy: nil)
+      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy))
     end
 
     # Print a wait's end the way the commands do: the JSON object on
@@ -115,17 +119,17 @@ module Samagotchi
     # @param command [String] "chi send", "chi answer"
     # @param extra [Hash] more keys for the JSON object (#json)
     # @return [Integer] the exit status
-    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {})
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {}, strategy: nil)
       if json
-        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra))
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy))
       elsif result.status == :done
         stdout.puts(result.text)
       else
         stdout.flush
         text = if result.status == :waiting_for_answer
-                 question_text(result.question, session_id: session_id)
+                 question_text(result.question, session_id: session_id, strategy: strategy)
                else
-                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id)}\n"
+                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id, strategy: strategy)}\n"
                end
         stderr.print("#{command}: #{text}")
       end
@@ -144,38 +148,102 @@ module Samagotchi
     # parent sees it.
     # kind is "question" for the model's own (the desk stores none),
     # "hook", "approval" or "continue" (the step-limit question, with the
-    # turn's limit).
+    # turn's limit). allowed_options: the options a parent may pick, by
+    # +strategy+ (nil: this process's guardrails.parent_answers;
+    # Guardrails::ParentPolicy), when that is not all of them.
     # @return [Hash]
-    def question(pending)
-      pending ||= PendingQuestion.new
+    def question(pending, strategy: nil)
+      pending = PendingQuestion.from_file(pending) || PendingQuestion.new
       approval = pending.approval.is_a?(Hash) ? symbolize(pending.approval) : nil
+      options = Array(pending.options).map(&:to_s)
+      allowed = allowed_options(pending, strategy: strategy)
       {
         id: pending.id.to_s,
         kind: (pending.kind || "question").to_s,
         header: blank(pending.header),
         text: pending.question.to_s,
-        options: Array(pending.options).map(&:to_s),
+        options: options,
         multi_select: !!pending.multi_select,
         allow_freeform: !!pending.allow_freeform,
+        allowed_options: (allowed unless allowed == options),
         limit: pending.limit,
         approval: approval&.slice(*APPROVAL_KEYS)
       }.compact
     end
 
     # The command that answers +question+; N is the parent's to fill in.
-    # An approval's is a deny: allowing it is the user's
-    # (Guardrails::ParentApprovals). A step-limit question's continues the
-    # turn (its Stop form is in #question_text).
+    # An approval's is a deny: a wider allow is the user's (#question_text
+    # lists an Allow once a parent may give). A step-limit question's
+    # continues the turn, or stops it where a parent may not continue (its
+    # other form is in #question_text).
     def answer_with(session_id, question)
       return "chi answer #{session_id} --question #{question[:id]} --option Deny --text WHY" if approval?(question)
+      return stop_command(session_id, question) if continue?(question) && !may_continue?(question)
       return "chi answer #{session_id} --question #{question[:id]} --option Continue" if continue?(question)
 
+      # The one option a parent may pick (cost-cap's Stop under hard).
+      only = Array(question[:allowed_options])
+      return "chi answer #{session_id} --question #{question[:id]} --option #{option_arg(only.first)}" if only.size == 1
+
       "chi answer #{session_id} --question #{question[:id]} --option N"
     end
 
-    # What a parent does with an approval.
+    # What a parent does with an approval it may not allow.
     DENY_AND_TELL = "deny it, and tell your user"
 
+    # The labels a parent may pick on +pending+ (a PendingQuestion, or a
+    # Hash with its fields) by +strategy+ (nil: this process's).
+    # @return [Array<String>]
+    def allowed_options(pending, strategy: nil)
+      pending = PendingQuestion.from_file(pending) || PendingQuestion.new
+      Guardrails::ParentPolicy.allowed_options(pending, strategy: policy(strategy))
+    end
+
+    # What a parent may pick on the session +session_id+: config.yml's
+    # level tightened by the session file's own parent_answers
+    # (Guardrails::ParentPolicy.for_session); config.yml's when there is no
+    # such session, hard (the strictest) when its file can't be read.
+    # @return [Guardrails::ParentPolicy::Strategy]
+    def strategy_for(session_id, state_dir:)
+      return Guardrails::ParentPolicy.current unless Session.exist?(session_id, state_dir: state_dir)
+
+      Guardrails::ParentPolicy.for_session(Session.load(session_id, state_dir: state_dir))
+    rescue ArgumentError, KeyError, TypeError, NoMethodError, SystemCallError, JSON::ParserError
+      Guardrails::ParentPolicy.strategy(Guardrails::ParentPolicy::HARD)
+    end
+
+    # +strategy+, or this process's config.yml's.
+    def policy(strategy) = strategy || Guardrails::ParentPolicy.current
+
+    # An approval's options a parent may allow (Allow once under soft).
+    def allowed_allows(question, strategy: nil)
+      question = question(question, strategy: strategy) unless question.is_a?(Hash) && question.key?(:text)
+      deny = Guardrails::Approval::DENY
+      question.fetch(:allowed_options, question[:options]).reject { |label| label == deny }
+    end
+
+    # What a parent does with an approval: deny it and tell its user, or
+    # give the Allow once its strategy lets it.
+    def approval_advice(question, strategy: nil)
+      allows = allowed_allows(question, strategy: strategy)
+      return DENY_AND_TELL if allows.empty?
+
+      "#{allows.join(" or ")} is yours to give (#{policy(strategy).label}); " \
+        "anything wider is up to your user: #{DENY_AND_TELL}"
+    end
+
+    # Whether a parent may answer Continue to a step-limit question.
+    def may_continue?(question, strategy: nil)
+      question = question(question, strategy: strategy) unless question.is_a?(Hash) && question.key?(:text)
+      question.fetch(:allowed_options, question[:options]).include?(Guardrails::ParentPolicy::CONTINUE)
+    end
+
+    def stop_command(session_id, question)
+      "chi answer #{session_id} --question #{question[:id]} --option Stop --text WHY"
+    end
+
+    def option_arg(label) = label.match?(/\A[\w.-]+\z/) ? label : label.inspect
+
     # The other way: the user answers it in chi (the web's bell and badge
     # say it waits), and a wait with no message waits past it.
     def leave_open(session_id)
@@ -203,20 +271,23 @@ module Samagotchi
     end
 
     # What a wait that ended without an answer says, one line.
-    def detail(result, session_id:, timeout: nil, turn_id: nil)
+    def detail(result, session_id:, timeout: nil, turn_id: nil, strategy: nil)
       attach = "chi --attach #{session_id}"
       case result.status
       when :waiting_for_answer
-        q = question(result.question)
+        q = question(result.question, strategy: strategy)
         if approval?(q)
-          "waiting for an approval: #{first_line(q[:text])}; #{DENY_AND_TELL}"
+          "waiting for an approval: #{first_line(q[:text])}; #{approval_advice(q, strategy: strategy)}"
+        elsif continue?(q) && !may_continue?(q)
+          "waiting at the step limit: #{first_line(q[:text])}; a parent may only stop it here " \
+            "(#{policy(strategy).label}): #{stop_command(session_id, q)}, or tell your user it waits"
         elsif continue?(q)
           "waiting at the step limit: #{first_line(q[:text])}; " \
             "answer Continue or Stop: chi answer #{session_id} --question #{q[:id]} --option Continue"
         else
           "waiting for an answer: #{first_line(q[:text])}; open it: #{attach} or the web"
         end
-      when :no_reply then "#{no_reply_line(result, session_id)}; #{attach} shows it"
+      when :no_reply then "#{no_reply_line(result, session_id, strategy: strategy)}; #{attach} shows it"
       when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
       when :worker_gone then "the worker is gone; #{attach} shows what happened"
       when :stopped then "the session was stopped (chi sessions stop)"
@@ -230,40 +301,61 @@ module Samagotchi
     # The whole question for stderr: header, text, numbered options, what
     # else it takes, and the commands that answer it.
     # @return [String] lines, newline-terminated
-    def question_text(pending, session_id:)
-      q = question(pending)
+    def question_text(pending, session_id:, strategy: nil)
+      q = question(pending, strategy: strategy)
       lines = ["waiting for an answer (#{q[:kind]}): #{q[:header] || first_line(q[:text])}"]
       text_lines = q[:text].strip.lines.map(&:rstrip)
       text_lines = text_lines.drop(1) unless q[:header]
       lines.concat(text_lines.map { |line| "  #{line}" })
       q[:options].each_with_index { |option, i| lines << "    #{i + 1}. #{option}" }
       if approval?(q)
-        lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
+        allows = allowed_allows(q)
+        if allows.empty?
+          lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
+        else
+          lines << "  #{approval_advice(q, strategy: strategy)}"
+          allows.each { |label| lines << "  allow: chi answer #{session_id} --question #{q[:id]} --option #{option_arg(label)}" }
+        end
         lines << "  deny: #{answer_with(session_id, q)}"
         lines << "  #{leave_open(session_id)}"
       elsif continue?(q)
-        lines << "  continue: #{answer_with(session_id, q)}"
-        lines << "  stop: chi answer #{session_id} --question #{q[:id]} --option Stop --text WHY (the text is optional; the model reads it)"
+        lines << if may_continue?(q)
+                   "  continue: #{answer_with(session_id, q)}"
+                 else
+                   "  continuing it is up to your user (#{policy(strategy).label}): stop it, or tell your user it waits"
+                 end
+        lines << "  stop: #{stop_command(session_id, q)} (the text is optional; the model reads it)"
         lines << "  #{message_drops(session_id)}"
       else
         lines << "  more than one allowed: repeat --option" if q[:multi_select]
         lines << "  free text allowed: --text" if q[:allow_freeform]
+        if q[:allowed_options]
+          lines << "  a parent may pick #{q[:allowed_options].map { |o| option_arg(o) }.join(", ")}; the others are up to your user"
+        end
         lines << "  answer: #{answer_with(session_id, q)}"
         lines << "  or open it: chi --attach #{session_id} or the web"
       end
       lines.map { |line| "#{line}\n" }.join
     end
 
-    def no_reply_line(result, session_id = nil)
+    def no_reply_line(result, session_id = nil, strategy: nil)
       case result.outcome
       when "failed" then failed_line(result)
-      when "canceled" then "the turn was canceled"
+      when "canceled"
+        # A turn its worker died in, settled by the next (TurnCheckpoint.settle).
+        result.cancel_reason == "worker_stopped" ? "the turn was canceled: its worker exited mid-turn" : "the turn was canceled"
       when "completed" then "the turn ended with no visible answer"
       when "not_continued" then "the turn was not continued (Stop); its work so far stays"
       when "removed" then "the queued message was removed before it ran; no turn ran for it"
       when "exhausted"
-        "the turn ran out of iterations#{" (#{result.limit} steps)" if result.limit} before it answered; " \
-          "chi send #{session_id} -m '/continue yes' continues it, a message drops it"
+        ran_out = "the turn ran out of iterations#{" (#{result.limit} steps)" if result.limit} before it answered"
+        strategy = policy(strategy)
+        if strategy.allow?(Guardrails::ParentPolicy::SPEND)
+          "#{ran_out}; chi send #{session_id} -m '/continue yes' continues it, a message drops it"
+        else
+          # No /continue yes hint: a parent may not continue it here.
+          "#{ran_out}; continuing it is up to your user (#{strategy.label}), a message drops it"
+        end
       else "the turn ended without a reply (canceled, failed or empty)"
       end
     end

data/lib/samagotchi/pending_question.rb

@@ -7,8 +7,12 @@ module Samagotchi
   # step-limit question (kind "continue").
   #
   # id: the question's uuid; question, options, header, multi_select,
-  # allow_freeform: what the UIs show; kind: nil for the model's own,
-  # "hook", "approval" or "continue"; hook: the asking hook's name;
+  # allow_freeform: what the UIs show; effects: each option's effect for
+  # a parent agent's answer, in option order (Guardrails::ParentPolicy;
+  # nil: untagged); user_only: only the user may pick an option that isn't
+  # a deny or a plain answer (an approval on chi's own config); kind: nil
+  # for the model's own, "hook", "approval" or "continue"; hook: the asking
+  # hook's name;
   # approval: the approval's facts (Guardrails::Approval.payload); relay: a
   # relayed approval's facts (Relay.card); limit, context: the step-limit
   # question's turn limit and offer context (ContinueOffer); status:
@@ -20,8 +24,8 @@ module Samagotchi
   # 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, :kind, :hook,
-                                :approval, :relay, :limit, :context, :status, :created_at, :relayed_to) do
+  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
     def initialize(**fields)
       super(**members.to_h { |m| [m, nil] }, **fields)
     end

data/lib/samagotchi/plugin/api.rb

@@ -18,6 +18,22 @@ module Samagotchi
       ANNOTATION_LABEL_MAX = 40
       ANNOTATIONS_MAX = 5
 
+      # 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).
+      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",
+        "ctx.context" => "0.32.0", "ctx.delegate" => "0.32.0", "ctx.scratch" => "0.32.0",
+        "fallback_for:" => "0.35.0", "ctx.fork" => "0.45.0", "ctx.frontend" => "0.49.0",
+        "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"
+      }.freeze
+
       # @param bundle [String]
       # @param label [String] "<file> (bundle <name>)": what hooks and
       #   failures are named by

data/lib/samagotchi/plugin/context.rb

@@ -29,7 +29,7 @@ module Samagotchi
     # The Engine's side of a Context: callables, so the Engine itself is
     # never handed out. +messages+ returns the conversation, +notify+ takes
     # (text, level, label, fallback_for:), +ask_user+ takes (question:, options:, header:,
-    # allow_freeform:, hook:) like the hook runtime's, +card+ takes
+    # allow_freeform:, hook:, and effects: when the plugin gave them) like the hook runtime's, +card+ takes
     # Engine#show_card's keywords and returns the id, +ask_model+ takes
     # (chat messages, timeout:, max_tokens:, cancel_controller:, model:: a
     # configured model ref, nil for the session's) and returns the answer
@@ -355,15 +355,21 @@ module Samagotchi
 
       # A single-select question through the question flow. Inside a
       # stream hook's handler (generation_progress) it asks no one (nil).
+      # @param effects [Hash{String => Symbol}, nil] what an option does, by
+      #   its label, for a parent agent's answer (Guardrails::ParentPolicy):
+      #   :spend (more time or money: a Continue), :permit (one call),
+      #   :permit_wide, :deny (a Stop); a label left out is a plain :answer.
+      #   Tag every option that spends or permits.
       # @return [Hash, nil] {selected:, freeform:, selected_indices:}, or nil
-      #   (no one to ask, cancelled, bad options)
-      def ask_user(question:, options:, header: nil, allow_freeform: false)
+      #   (no one to ask, cancelled, bad options or effects)
+      def ask_user(question:, options:, header: nil, allow_freeform: false, effects: nil)
+        tags = effects.nil? ? {} : { effects: effects }
         if (helper = event_helper(:ask_user))
-          return helper.call(question: question, options: options, header: header, allow_freeform: allow_freeform)
+          return helper.call(question: question, options: options, header: header, allow_freeform: allow_freeform, **tags)
         end
 
         @host.ask_user.call(question: question, options: options, header: header, allow_freeform: allow_freeform,
-                            hook: @label)
+                            hook: @label, **tags)
       end
 
       # Whether the running turn was cancelled (a long tool should stop).

data/lib/samagotchi/plugin/loader.rb

@@ -4,6 +4,7 @@ require_relative "api"
 require_relative "context"
 require_relative "../hooks"
 require_relative "../log"
+require_relative "../guardrails/load_failures"
 require_relative "../version"
 require_relative "../memory_bundle/manifest"
 require_relative "../memory_bundle/provenance"
@@ -71,7 +72,8 @@ module Samagotchi
       rescue Exception => e # rubocop:disable Lint/RescueException -- a plugin's SyntaxError or exit must not stop chi
         raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
 
-        failed(bundle_name, basename, "#{e.class}: #{e.message}", failures)
+        failed(bundle_name, basename, "#{e.class}: #{e.message}", failures,
+               location: file && Guardrails::LoadFailures.location(e, File.dirname(file)))
       end
 
       # Build +file+'s plugin with +settings+ and commit what its #register
@@ -136,10 +138,10 @@ module Samagotchi
         end
       end
 
-      def failed(bundle_name, basename, reason, failures)
+      def failed(bundle_name, basename, reason, failures, location: nil)
         Log.warn(TAG, "plugin_not_loaded", echo: "[samagotchi:plugins] bundle '#{bundle_name}' plugin '#{basename}' not loaded: #{reason}",
                                            bundle: bundle_name, file: basename)
-        failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: false)
+        failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: false, location: location)
         false
       end
     end