samagotchi 0.84.0 → 0.86.0

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_report.rb

@@ -5,6 +5,7 @@ require "json"
 
 require_relative "cli/exit"
 require_relative "pending_question"
+require_relative "guardrails/parent_policy"
 
 module Samagotchi
   # How a wait's end (ReplyWait::Result) reads to whoever runs chi as a
@@ -34,8 +35,9 @@ module Samagotchi
     # @param result [ReplyWait::Result]
     # @return [String] answered, question, failed, canceled, limit (the
     #   turn ran out of iterations, nobody asked), not_continued (a Stop
-    #   answered the step-limit question), no_answer, error, worker_gone,
-    #   stopped or running
+    #   answered the step-limit question), removed (the queued message was
+    #   taken back before it ran), no_answer, error, worker_gone, stopped
+    #   or running
     def status(result)
       case result.status
       when :done then "answered"
@@ -46,6 +48,7 @@ module Samagotchi
         when "canceled" then "canceled"
         when "exhausted" then "limit"
         when "not_continued" then "not_continued"
+        when "removed" then "removed"
         else "no_answer"
         end
       when :error then "error"
@@ -142,38 +145,86 @@ 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
+    # this process's guardrails.parent_answers (Guardrails::ParentPolicy),
+    # when that is not all of them.
     # @return [Hash]
     def question(pending)
-      pending ||= PendingQuestion.new
+      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)
       {
         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 this process's strategy.
+    # @return [Array<String>]
+    def allowed_options(pending)
+      pending = PendingQuestion.from_file(pending) || PendingQuestion.new
+      Guardrails::ParentPolicy.allowed_options(pending, strategy: Guardrails::ParentPolicy.current)
+    end
+
+    # An approval's options a parent may allow (Allow once under soft).
+    def allowed_allows(question)
+      question = question(question) 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)
+      allows = allowed_allows(question)
+      return DENY_AND_TELL if allows.empty?
+
+      "#{allows.join(" or ")} is yours to give (#{Guardrails::ParentPolicy.current.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)
+      question = question(question) 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)
@@ -207,7 +258,10 @@ module Samagotchi
       when :waiting_for_answer
         q = question(result.question)
         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)}"
+        elsif continue?(q) && !may_continue?(q)
+          "waiting at the step limit: #{first_line(q[:text])}; a parent may only stop it here " \
+            "(#{Guardrails::ParentPolicy.current.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"
@@ -236,16 +290,29 @@ module Samagotchi
       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)}"
+          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 (#{Guardrails::ParentPolicy.current.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
@@ -255,12 +322,21 @@ module Samagotchi
     def no_reply_line(result, session_id = 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 = Guardrails::ParentPolicy.current
+        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
@@ -111,8 +111,9 @@ module Samagotchi
         cached = @session_settings
         return cached.last if cached && cached.first == id
 
-        merged = id ? overlay(@settings, session_values) : @settings
-        @session_settings = [id, merged].freeze
+        values = session_values(id) if id
+        merged = id ? overlay(@settings, values || {}) : @settings
+        @session_settings = [id, merged].freeze unless id && values.nil?
         merged
       end
 
@@ -354,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).
@@ -435,14 +442,17 @@ module Samagotchi
         nil
       end
 
-      # The session's own values for this bundle ({} without any, or when
-      # the Host can't tell them).
-      def session_values
+      # The session's own values for this bundle ({} without any; nil when
+      # the Host couldn't tell them, so #settings can retry).
+      def session_values(id)
         values = @host.setup&.call&.bundle_settings
         values.is_a?(Hash) ? values.fetch(@bundle, {}) : {}
       rescue StandardError => e
-        @log.warn("session_settings_unread", error: "#{e.class}: #{e.message}")
-        {}
+        unless (@session_settings_unread ||= {}).key?(id)
+          @session_settings_unread[id] = true
+          @log.warn("session_settings_unread", error: "#{e.class}: #{e.message}")
+        end
+        nil
       end
 
       def overlay(config, values)

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

data/lib/samagotchi/question_desk.rb

@@ -10,8 +10,7 @@ require_relative "log"
 require_relative "pending_question"
 require_relative "question_answer"
 require_relative "tools/ask_user_question"
-require_relative "guardrails/parent_approvals"
-require_relative "guardrails/parent_continue"
+require_relative "guardrails/parent_policy"
 
 module Samagotchi
   # An Engine's question flow: the one open question (ask_user_question, a
@@ -36,18 +35,25 @@ module Samagotchi
     class NotPending < ArgumentError; end
 
     # Raised by #answer when a parent agent's answer (chi answer's client
-    # id) allows an approval further than this worker's
-    # guardrails.parent_approvals lets it (Guardrails::ParentApprovals), or
-    # continues a turn turn.parent_continue keeps it from
-    # (Guardrails::ParentContinue). The question stays open; transports map
+    # id) picks an option this worker's strategy keeps parents from
+    # (Guardrails::ParentPolicy). The question stays open; transports map
     # it to 403.
     class Refused < StandardError
-      # @return [Symbol] :off, :once_only, :protected or :stop_only
+      # @return [Symbol] ParentPolicy.refusal's: :user_only, :permit_wide,
+      #   :permit or :spend
       attr_reader :reason
 
-      def initialize(reason)
+      def initialize(reason, pending:, strategy:)
         @reason = reason
-        super(reason == :stop_only ? "a parent may not continue this turn" : "a parent may not allow this approval (#{reason})")
+        @pending = pending
+        @strategy = strategy
+        super("a parent may not pick that option here (#{reason})")
+      end
+
+      # The line for the parent (ParentPolicy.message).
+      # @param typed [Boolean] typed at a ? prompt (the REPL)
+      def detail(typed: false)
+        Guardrails::ParentPolicy.message(reason, pending: @pending, strategy: @strategy, typed: typed)
       end
     end
 
@@ -290,7 +296,7 @@ module Samagotchi
     # @param freeform [String, nil]
     # @param client_id [String, nil] who answers
     # @param parent_agent [Boolean, nil] the answer is a parent agent's, so
-    #   it is held to guardrails.parent_approvals on an approval and doesn't
+    #   it is held to Guardrails::ParentPolicy and doesn't
     #   bring the session back to the lists; nil: chi answer's client id says so
     # @return [QuestionAnswer] the answer; a parent agent's carries by: "parent_agent"
     # @raise [NotPending, ArgumentError, Refused]
@@ -300,8 +306,7 @@ module Samagotchi
       fm = nil if fm.empty?
       parent_agent = client_id.to_s == ClientId::CLI_ANSWER if parent_agent.nil?
       # Read before the lock (config may touch the disk); this worker's own.
-      parent_setting = Guardrails::ParentApprovals.setting if parent_agent
-      parent_continue = Guardrails::ParentContinue.allowed? if parent_agent
+      strategy = Guardrails::ParentPolicy.current if parent_agent
       standing = nil
       answer = @lock.synchronize do
         pending = @pending
@@ -313,10 +318,7 @@ module Samagotchi
         raise NotPending, "question already answered" if @answer
         raise NotPending, "question #{pending.status}" unless pending.status.to_s == "pending"
 
-        answer = validated_answer(pending, sel, fm, parent_agent: parent_agent, parent_setting: parent_setting)
-        if parent_agent && (reason = Guardrails::ParentContinue.refusal(pending, sel, allowed: parent_continue))
-          raise Refused, reason
-        end
+        answer = validated_answer(pending, sel, fm, parent_agent: parent_agent, strategy: strategy)
 
         if @standing
           # No waiter: cleared here, so a second answer finds none.
@@ -401,9 +403,13 @@ module Samagotchi
     # web), single-select, kind "hook". A --non-interactive run has no one
     # to ask: nil at once. Anything but an answer (a sync handler's text, no
     # answer, cancelled) is nil too.
+    # @param effects [Hash, nil] label => effect for a parent agent's answer
+    #   (Guardrails::ParentPolicy); a label left out is "answer". A label
+    #   the options don't have, or an effect it doesn't know, makes the ask
+    #   invalid (nil, warned), like bad options.
     # @return [Hash, nil] {selected:, freeform:, selected_indices:} (a plain
     #   Hash: the bundle boundary)
-    def ask_for_hook(question, options, header, allow_freeform, hook)
+    def ask_for_hook(question, options, header, allow_freeform, hook, effects: nil)
       return nil if @interface_lookup.call == :non_interactive
 
       opts = Tools::AskUserQuestion.normalize_options(options)
@@ -411,9 +417,16 @@ module Samagotchi
         Log.warn(:hooks, "ask_user_invalid", echo: "[samagotchi:hooks] #{hook} asked with invalid options (2-8 strings)", hook: hook.to_s)
         return nil
       end
+      tags = Guardrails::ParentPolicy.option_tags(opts, effects)
+      if tags == false
+        Log.warn(:hooks, "ask_user_invalid",
+                 echo: "[samagotchi:hooks] #{hook} asked with invalid effects (option label => " \
+                       "#{Guardrails::ParentPolicy::EFFECTS.join("|")})", hook: hook.to_s)
+        return nil
+      end
 
       fields = { question: question.to_s, options: opts, header: header, multi_select: false,
-                 allow_freeform: !!allow_freeform, kind: "hook", hook: hook.to_s }.compact
+                 allow_freeform: !!allow_freeform, effects: tags, kind: "hook", hook: hook.to_s }.compact
       answer = open_question(fields)
       return nil unless answer.is_a?(QuestionAnswer)
 
@@ -493,11 +506,11 @@ module Samagotchi
 
     # An answer to +pending+, checked: the selections are its options (value
     # == label in v1), one for a single-select, one or a text when required,
-    # and a parent agent's within guardrails.parent_approvals. Under the
+    # and a parent agent's within its strategy (ParentPolicy). Under the
     # question lock: checked against the question pending now.
     # @return [QuestionAnswer]
     # @raise [ArgumentError, Refused]
-    def validated_answer(pending, sel, fm, parent_agent:, parent_setting:)
+    def validated_answer(pending, sel, fm, parent_agent:, strategy:)
       opts = Array(pending.options)
       invalid = sel.reject { |v| opts.include?(v) }
       raise ArgumentError, "invalid selection: #{invalid.join(", ")} (valid: #{opts.join(", ")})" unless invalid.empty?
@@ -505,10 +518,10 @@ module Samagotchi
       raise ArgumentError, "selection required" if pending.multi_select == false && sel.empty? && fm.nil?
 
       indices = sel.map { |v| opts.index(v) }
-      # The one whose answer settles the approval (Approval.settle, by index).
-      if parent_setting
-        reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: parent_setting)
-        raise Refused, reason if reason
+      # By index, as the effects (and Approval.settle) read it.
+      if strategy
+        reason = Guardrails::ParentPolicy.refusal(pending, indices, strategy: strategy)
+        raise Refused.new(reason, pending: pending, strategy: strategy) if reason
       end
       QuestionAnswer.new(id: pending.id.to_s, selected: sel, freeform: fm, selected_indices: indices.compact,
                          by: parent_agent ? "parent_agent" : nil)

data/lib/samagotchi/queued_command.rb

@@ -9,10 +9,11 @@ module Samagotchi
   # question's answer), whose line the UIs leave out. The worker adds
   # where it waits (Worker#on_command): +mid_turn+ (the policy it got:
   # :queue, :refuse, :loop), +after_seq+ (the event count then, so a
-  # turn's end knows it came before) and +after_file+ (the input file it
-  # runs after, a basename).
-  QueuedCommand = Data.define(:command_id, :client_id, :line, :card, :mid_turn, :after_seq, :after_file) do
-    def initialize(command_id:, line:, client_id: nil, card: false, mid_turn: nil, after_seq: nil, after_file: nil) = super
+  # turn's end knows it came before), +after_file+ (the input file it runs
+  # after, a basename) and +enqueued_id+ (a file-delivered command's sender).
+  QueuedCommand = Data.define(:command_id, :client_id, :line, :card, :mid_turn, :after_seq, :after_file, :enqueued_id) do
+    def initialize(command_id:, line:, client_id: nil, card: false, mid_turn: nil, after_seq: nil, after_file: nil,
+                   enqueued_id: nil) = super
 
     # A new command with a fresh id.
     def self.mint(line, client_id: nil, card: false)

data/lib/samagotchi/relay.rb

@@ -6,7 +6,9 @@ module Samagotchi
   # A delegate's approval reopened as the parent session's own (the
   # approval relay): the same kind "approval" and the same approval facts,
   # so every UI shows it as it shows the parent's own approvals, the diff
-  # included, and Guardrails::ParentApprovals judges it the same way. The
+  # included, and Guardrails::ParentPolicy judges it the same way: the
+  # child's effects and user_only come along (an older child's question
+  # has none; the policy derives them from the approval facts). The
   # question text names the delegate and its task over the child's own
   # text; `relay:` says which child and which of its questions it answers.
   # A relay of a relay (a grandchild's) grows relay.chain.
@@ -37,6 +39,8 @@ module Samagotchi
         header: header(who, more),
         multi_select: false,
         allow_freeform: pending.allow_freeform.nil? || !!pending.allow_freeform,
+        # Same order: only the session option's label changes.
+        **{ effects: pending.effects, user_only: pending.user_only }.compact,
         kind: Guardrails::Approval::KIND,
         approval: facts,
         relay: { id: relay_id, child_id: child.id, child_short: short, child_question_id: pending.id.to_s,