samagotchi 0.85.0 → 0.86.0

data/lib/samagotchi/guardrails/approval.rb

@@ -15,6 +15,7 @@ module Samagotchi
       KIND = "approval"
       HEADER = "Approve tool call?"
       DENY = "Deny"
+      ONCE = "Allow once"
 
       module_function
 
@@ -27,7 +28,9 @@ module Samagotchi
       #   write: the card shows its diff, the question text one change line
       # @param only [Array<String>, nil] offer no scope beyond these (a
       #   scratch session: once, session); "once" when none is left
-      # @return [Hash] open_question fields
+      # @return [Hash] open_question fields; its caller adds user_only:
+      #   (ParentApprovals.protected_facts? on approval:, a file that
+      #   requires this one)
       def payload(verdict, label: nil, preview: nil, only: nil)
         scopes = offered_scopes(verdict, only: only)
         targets = verdict.targets
@@ -37,6 +40,7 @@ module Samagotchi
           header: HEADER,
           multi_select: false,
           allow_freeform: true,
+          effects: effects(scopes),
           kind: KIND,
           approval: {
             tool: targets&.tool || verdict.call[:name].to_s,
@@ -61,6 +65,12 @@ module Samagotchi
         }
       end
 
+      # Each option's effect for a parent's answer (ParentPolicy): once
+      # permits one call, a wider scope more, Deny denies.
+      def effects(scopes)
+        scopes.map { |scope| scope == "once" ? "permit" : "permit_wide" } + ["deny"]
+      end
+
       def args_for_card(targets)
         return nil if targets.nil? || targets.command || !targets.paths.empty?
 
@@ -101,7 +111,7 @@ module Samagotchi
       def label(scope, verdict)
         place = verdict.targets&.repo_root ? "in this repo (#{verdict.targets.repo_name})" : "in this directory"
         case scope
-        when "once" then "Allow once"
+        when "once" then ONCE
         when "session" then "Allow this call for the session"
         when "repo" then "Allow this call #{place}"
         when "rule" then "Allow rule #{verdict.rule} #{place}"

data/lib/samagotchi/guardrails/load_failures.rb

@@ -7,7 +7,18 @@ module Samagotchi
     # guardrail that silently vanished is the failure this guards against);
     # the rest are only announced.
     class LoadFailures
-      Failure = Struct.new(:what, :reason, :required, :group, keyword_init: true)
+      # +location+: "path:line" of the first frame of the error inside the
+      # bundle that failed (nil when none is), for `chi bundle check`.
+      Failure = Struct.new(:what, :reason, :required, :group, :location, keyword_init: true)
+
+      # "path:line" where +error+ was raised inside +dir+ (its first
+      # backtrace frame there; a SyntaxError's own file:line), or nil.
+      def self.location(error, dir)
+        prefix = "#{File.expand_path(dir)}/"
+        frame = Array(error.backtrace).find { |line| line.start_with?(prefix) }
+        frame ||= error.message.lines.first if error.is_a?(SyntaxError)
+        frame&.start_with?(prefix) ? frame[/\A[^:]+:\d+/] : nil
+      end
 
       def initialize
         @list = []
@@ -16,8 +27,11 @@ module Samagotchi
 
       # @param what [String] e.g. "hook guard.rb (config)"
       # @param group [Symbol, nil] what loads it again (#drop): :rules
-      def add(what, reason, required:, group: nil)
-        @mutex.synchronize { @list << Failure.new(what: what, reason: reason, required: required, group: group) }
+      # @param location [String, nil] Failure#location
+      def add(what, reason, required:, group: nil, location: nil)
+        @mutex.synchronize do
+          @list << Failure.new(what: what, reason: reason, required: required, group: group, location: location)
+        end
       end
 
       # Forget a group's failures before it loads again.

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -7,29 +7,18 @@ require_relative "../hooks/loader"
 require_relative "approval"
 require_relative "verdict"
 require_relative "protected_paths"
-require_relative "parent_continue"
 
 module Samagotchi
   module Guardrails
-    # What a parent agent may allow on an approval (guardrails.parent_approvals,
-    # config.yml only): off, a deny only; once, "Allow once" too, never a
-    # wider scope. `chi answer` checks it before it posts; the worker checks
-    # it again for an answer marked as chi answer's (CLIENT_ID), with its own
-    # config. A convention for an honest but eager parent, not a security
-    # boundary: any local process can post to the Bridge, with or without
-    # the marker.
-    #
-    # An option allows when Approval.settle would allow it: its index is
-    # below the approval's scopes. The scope is read by index, never by
-    # label. When the scopes are missing or don't fit the options, it fails
-    # closed: only a last option labelled Deny denies.
-    #
-    # Whatever the setting, an approval for a call on chi's own config dir
-    # (config.yml, memories/.bundles' rules), the hooks dir or the approval
-    # store is the user's alone (:protected): "Allow once" on a config.yml
-    # rewrite would be "allow everything" from then on.
+    # The facts a parent agent's answer is judged by (ParentPolicy): who
+    # answers as a parent (#parent_process?), what an approval is
+    # (#approval?, its #scopes) and which approvals are the user's alone
+    # (#protected?): a call on chi's own config dir (config.yml,
+    # memories/.bundles' rules), the hooks dir or the approval store, since
+    # "Allow once" on a config.yml rewrite would be "allow everything" from
+    # then on. Also chi's dirs and text for the guardrails' own rules
+    # (Targets, the shell rules).
     module ParentApprovals
-      KEY = "guardrails.parent_approvals"
       # Set by chi's execute and task_create for the commands they run: a
       # chi started there answers as a parent (#parent_process?).
       PARENT_SESSION_ENV = "SAMAGOTCHI_PARENT_SESSION"
@@ -56,7 +45,7 @@ module Samagotchi
       module_function
 
       # Whether an answer typed into this process is a parent agent's (so
-      # this setting applies to it): stdin isn't a terminal (a pipe, a file,
+      # ParentPolicy applies to it): stdin isn't a terminal (a pipe, a file,
       # /dev/null), or an agent marker is set. A person at chi --attach or
       # the REPL has a terminal and no marker.
       def parent_process?(env: ENV, stdin: $stdin)
@@ -65,35 +54,14 @@ module Samagotchi
         !(stdin.respond_to?(:tty?) && stdin.tty?)
       end
 
-      # This process's setting: "once" or "off" (anything else is off).
-      def setting
-        Config.get(KEY).to_s == "once" ? "once" : "off"
-      end
-
-      # Why a parent may not give this answer, or nil.
-      # @param pending [Hash] the pending question (symbol or string keys)
-      # @param indices [Array<Integer, nil>] the selected options' places
-      # @param setting [String, nil] "off" or "once"
-      # @return [Symbol, nil] :protected (chi's own config: the user's
-      #   alone), :off (no allow at all), :once_only, or nil
-      def refusal(pending, indices, setting:)
-        return nil unless approval?(pending)
-
-        scopes = scopes(pending)
-        allows = Array(indices).reject { |index| deny?(pending, scopes, index) }
-        return nil if allows.empty?
-        return :protected if protected?(pending)
-        return :off unless setting.to_s == "once"
-        return nil if scopes && allows.all? { |index| index.is_a?(Integer) && index >= 0 && scopes[index] == "once" }
-
-        :once_only
-      end
-
       # Whether +pending+ asks about a call on chi's own config, hooks,
       # guardrail rules or approvals: by its rule, its paths or its command
       # (the dirs as this process's environment and config.yml name them).
-      def protected?(pending)
-        facts = pending.approval
+      def protected?(pending) = protected_facts?(pending.approval)
+
+      # #protected? on an approval's facts (Approval.payload's approval:),
+      # at ask time.
+      def protected_facts?(facts)
         return false unless facts.is_a?(Hash)
         return true if PROTECTED_RULES.include?(fetch(facts, :rule).to_s)
         return true if fetch(facts, :source).to_s == ProtectedPaths::SOURCE
@@ -120,21 +88,6 @@ module Samagotchi
           .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?).uniq
       end
 
-      # The refusal as a line for the parent: deny, and tell the user.
-      # Never how to allow it (the web, chi --attach): that is the user's.
-      # @param reason [Symbol] what #refusal returned
-      # @param typed [Boolean] the answer was typed at a ? prompt (the
-      #   REPL), not given to chi answer
-      def message(reason, typed: false)
-        deny = typed ? "deny it (n; WHY), and tell your user" : "deny it (--option Deny --text WHY), and tell your user"
-        case reason
-        when :stop_only then ParentContinue.message
-        when :protected then "this call changes chi's own config, hooks or guardrails, and only the user can allow it: #{deny}"
-        when :off then "allowing a tool call is up to the user: #{deny}"
-        else "only Allow once (#{KEY}: once) can be given here: #{deny}"
-        end
-      end
-
       # An approval: its kind says so, or it carries approval facts.
       def approval?(pending)
         pending.kind.to_s == Approval::KIND || !pending.approval.nil?
@@ -151,15 +104,6 @@ module Samagotchi
         scopes
       end
 
-      def deny?(pending, scopes, index)
-        return false unless index.is_a?(Integer) && index >= 0
-
-        options = options(pending)
-        return index >= scopes.size && index < options.size if scopes
-
-        index == options.size - 1 && options[index].to_s == Approval::DENY
-      end
-
       def options(pending) = Array(pending.options)
 
       def fetch(hash, key)

data/lib/samagotchi/guardrails/parent_policy.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+require_relative "../pending_question"
+require_relative "approval"
+require_relative "parent_approvals"
+
+module Samagotchi
+  module Guardrails
+    # What a parent agent may answer on a session's question: one check for
+    # every asker (an approval, the step-limit Continue, a plugin's or a
+    # hook's ask_user, a relayed delegate approval). The asker tags each
+    # option with its effect (PendingQuestion#effects); a strategy says
+    # which effects a parent may pick. `chi answer` checks it before it
+    # posts; the worker's QuestionDesk checks it again, with its own config,
+    # for an answer marked as a parent agent's. A convention for an honest
+    # but eager parent, not a security boundary.
+    #
+    # Strategies (guardrails.parent_answers, config.yml only): hard = answer
+    # and deny; standard = + spend; soft (the default) = + permit.
+    #
+    # Effects: answer (an untagged option), deny, spend (more time and
+    # tokens: Continue), permit (one call: Allow once), permit_wide (more
+    # than one call: a session, repo or rule scope). A parent never picks
+    # permit_wide; on a user_only question (chi's own config, hooks or
+    # guardrails) it picks only deny or answer. Text alone and a dismissal
+    # always pass.
+    module ParentPolicy
+      ANSWER = "answer"
+      DENY = "deny"
+      SPEND = "spend"
+      PERMIT = "permit"
+      PERMIT_WIDE = "permit_wide"
+      EFFECTS = [ANSWER, DENY, SPEND, PERMIT, PERMIT_WIDE].freeze
+      # The effects a parent may pick with no setting at all.
+      ALWAYS = [ANSWER, DENY].freeze
+      # Beyond-the-strategy reasons, widest first (#refusal).
+      WIDEST_FIRST = [PERMIT_WIDE, PERMIT, SPEND].freeze
+
+      # The step-limit question (ContinueOffer).
+      CONTINUE_KIND = "continue"
+      CONTINUE = "Continue"
+      STOP = "Stop"
+      # Its shape, for a /continue yes sent as a command (#continue_refusal).
+      CONTINUE_QUESTION = PendingQuestion.new(kind: CONTINUE_KIND, options: [CONTINUE, STOP], effects: [SPEND, DENY])
+
+      KEY = "guardrails.parent_answers"
+      HARD = "hard"
+      STANDARD = "standard"
+      SOFT = "soft"
+
+      # A strategy: its name and the effects a parent may pick under it.
+      Strategy = Data.define(:name, :allowed) do
+        def allow?(effect) = allowed.include?(effect.to_s)
+
+        # How a refusal names the setting: "guardrails.parent_answers: hard".
+        def label = "#{KEY}: #{name}"
+      end
+
+      STRATEGIES = {
+        HARD => Strategy.new(name: HARD, allowed: ALWAYS),
+        STANDARD => Strategy.new(name: STANDARD, allowed: [*ALWAYS, SPEND].freeze),
+        SOFT => Strategy.new(name: SOFT, allowed: [*ALWAYS, SPEND, PERMIT].freeze)
+      }.freeze
+
+      module_function
+
+      # This process's strategy (config.yml only; Config makes an invalid
+      # value hard and warns).
+      # @return [Strategy]
+      def current = strategy(Config.get(KEY))
+
+      # The named strategy; anything else is hard, the strictest.
+      # @return [Strategy]
+      def strategy(name) = STRATEGIES.fetch(name.to_s, STRATEGIES[HARD])
+
+      # @return [Array<String>] the effects +strategy+ lets a parent pick
+      def allowed_effects(strategy) = strategy.allowed
+
+      # Each option's effect, in option order. Tagged questions carry them;
+      # an untagged one (asked by an older worker, a relayed card built
+      # from an older child's question) gets them derived as before:
+      # an approval's from its scopes, the step-limit question's from its
+      # labels, anything else's all answer.
+      # @param pending [PendingQuestion]
+      # @return [Array<String>]
+      def effects_of(pending)
+        options = Array(pending.options)
+        tags = pending.effects
+        return options.each_index.map { |index| tag(tags[index]) } if tags.is_a?(Array)
+        return approval_effects(pending, options) if ParentApprovals.approval?(pending)
+        return options.map { |label| continue_effect(label) } if pending.kind.to_s == CONTINUE_KIND
+
+        options.map { ANSWER }
+      end
+
+      # Whether only the user may pick a non-deny/answer option. Unset on an
+      # approval (an older worker's): worked out from its facts here. A
+      # relayed card: the child's flag, or this process's own look at it.
+      def user_only?(pending)
+        return true if pending.user_only == true
+        return false unless ParentApprovals.approval?(pending)
+        return false if pending.user_only == false && !pending.relay
+
+        ParentApprovals.protected?(pending)
+      end
+
+      # Why a parent may not give this answer, or nil.
+      # @param pending [PendingQuestion]
+      # @param indices [Array<Integer, nil>] the selected options' places
+      # @param strategy [Strategy]
+      # @return [Symbol, nil] :user_only, :permit_wide, :permit or :spend
+      def refusal(pending, indices, strategy:)
+        effects = effects_of(pending)
+        picked = Array(indices).map { |index| effect_at(effects, index) }
+        return nil if picked.empty?
+        return :user_only if user_only?(pending) && picked.any? { |effect| !ALWAYS.include?(effect) }
+
+        WIDEST_FIRST.each do |effect|
+          return effect.to_sym if picked.include?(effect) && !strategy.allow?(effect)
+        end
+        nil
+      end
+
+      # The refusal as a line for the parent: what to answer instead, or
+      # tell the user. Never how to allow it (the web, chi --attach): that
+      # is the user's.
+      # @param reason [Symbol] what #refusal returned
+      # @param typed [Boolean] the answer was typed at a ? prompt (the
+      #   REPL), not given to chi answer
+      def message(reason, pending:, strategy:, typed: false)
+        deny = deny_label(pending)
+        case reason.to_sym
+        when :spend
+          if pending.kind.to_s == CONTINUE_KIND
+            return "a parent agent may only stop this turn here (#{strategy.label}): answer #{STOP} " \
+                   "(--option #{STOP} --text WHY), or tell your user it waits"
+          end
+
+          "a parent agent may not pick #{tagged_labels(pending, SPEND)} here (#{strategy.label}): #{instead(deny, typed, "answer")}"
+        when :user_only
+          "this call changes chi's own config, hooks or guardrails, and only the user can allow it: #{instead(deny, typed)}"
+        when :permit_wide
+          # An approval whose scopes don't fit its options has no permit
+          # option: its once is still what a parent may give.
+          permits = tagged_labels(pending, PERMIT)
+          permits = Approval::ONCE if permits.empty? && ParentApprovals.approval?(pending)
+          if strategy.allow?(PERMIT) && !permits.empty?
+            "only #{permits} (#{strategy.label}) can be given here: #{instead(deny, typed)}"
+          else
+            "#{allowing(pending)} is up to the user: #{instead(deny, typed)}"
+          end
+        else "#{allowing(pending)} is up to the user: #{instead(deny, typed)}"
+        end
+      end
+
+      # Why a parent agent may not continue a turn with /continue yes (a
+      # command: chi send -m, a piped attach), or nil: the step-limit
+      # question's Continue, checked the same way.
+      # @return [String, nil] the refusal line
+      def continue_refusal(strategy: current)
+        reason = refusal(CONTINUE_QUESTION, [0], strategy: strategy)
+        reason && message(reason, pending: CONTINUE_QUESTION, strategy: strategy)
+      end
+
+      # The labels a parent may pick on +pending+ under +strategy+.
+      # @return [Array<String>]
+      def allowed_options(pending, strategy:)
+        user_only = user_only?(pending)
+        Array(pending.options).zip(effects_of(pending)).filter_map do |label, effect|
+          next nil if user_only && !ALWAYS.include?(effect)
+
+          label.to_s if strategy.allow?(effect)
+        end
+      end
+
+      # The question's deny-tagged option's label, or nil.
+      def deny_label(pending)
+        index = effects_of(pending).index(DENY)
+        index && Array(pending.options)[index].to_s
+      end
+
+      # What the parent does instead: deny with the question's own deny
+      # option and tell the user, or (none) tell the user it waits.
+      def instead(deny, typed, verb = "deny it")
+        return "tell your user it waits" unless deny
+
+        how = typed ? "n; WHY" : "--option #{deny} --text WHY"
+        verb == "answer" ? "answer #{deny} (#{how}), or tell your user it waits" : "#{verb} (#{how}), and tell your user"
+      end
+
+      def allowing(pending)
+        ParentApprovals.approval?(pending) ? "allowing a tool call" : "allowing it"
+      end
+
+      def tagged_labels(pending, effect)
+        Array(pending.options).zip(effects_of(pending)).filter_map { |label, tag| label.to_s if tag == effect }.join(" or ")
+      end
+
+      # An index it can't place counts as the widest effect (fail closed).
+      def effect_at(effects, index)
+        return PERMIT_WIDE unless index.is_a?(Integer) && index >= 0 && index < effects.size
+
+        effects[index]
+      end
+
+      # A tag as given; an unknown one fails closed.
+      def tag(value)
+        return ANSWER if value.nil?
+
+        EFFECTS.include?(value.to_s) ? value.to_s : PERMIT_WIDE
+      end
+
+      # A plugin's or a hook's effects (label => effect, ask_user's
+      # effects:) as the options' tags, in option order; a label left out
+      # is answer (QuestionDesk#ask_for_hook, and the test kit's Recorder).
+      # @return [Array<String>, nil, false] the tags; nil for none given;
+      #   false when invalid (not a Hash, a label the options don't have,
+      #   an effect not in EFFECTS)
+      def option_tags(options, effects)
+        return nil if effects.nil?
+        return false unless effects.is_a?(Hash)
+
+        given = effects.to_h { |label, effect| [label.to_s, effect.to_s] }
+        return false unless (given.keys - Array(options).map(&:to_s)).empty?
+        return false unless (given.values - EFFECTS).empty?
+
+        Array(options).map { |label| given.fetch(label.to_s, ANSWER) }
+      end
+
+      # When the scopes fit the options: once permits, another scope
+      # permits wide, the options past them deny. When they don't (missing,
+      # malformed): only a last option labelled Deny denies.
+      def approval_effects(pending, options)
+        scopes = ParentApprovals.scopes(pending)
+        if scopes
+          return options.each_index.map do |index|
+            next DENY if index >= scopes.size
+
+            scopes[index] == "once" ? PERMIT : PERMIT_WIDE
+          end
+        end
+
+        options.each_with_index.map do |label, index|
+          index == options.size - 1 && label.to_s == Approval::DENY ? DENY : PERMIT_WIDE
+        end
+      end
+
+      def continue_effect(label)
+        case label.to_s
+        when CONTINUE then SPEND
+        when STOP then DENY
+        else ANSWER
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/verdict.rb

@@ -16,10 +16,13 @@ module Samagotchi
       # command source for attached context (it runs later, ungated); chi
       # broadcast, which is the user's; the bundle's asks before a memory
       # that reaches the system prompt, or a model overlay, is written (a
-      # parent model would be writing a model's prompt). Only the user may
-      # allow them (ParentApprovals).
+      # parent model would be writing a model's prompt); and the bundle's
+      # asks before answering chi's questions around chi answer (a parent
+      # allowing one would answer a grandchild's question as the user).
+      # Only the user may allow them (ParentApprovals.protected?,
+      # ParentPolicy's user_only).
       PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd chi-broadcast prompt-memory-write
-                           model-overlay-write].freeze
+                           model-overlay-write chi-answer-piped chi-answer-http].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 

data/lib/samagotchi/hook_routes.rb

@@ -36,7 +36,9 @@ module Samagotchi
     def runtime
       Hooks::Runtime.new(
         notify: ->(text:, level:, hook:, fallback_for: nil) { notify(text, level, hook, fallback_for: fallback_for) },
-        ask_user: ->(question:, options:, header:, allow_freeform:, hook:) { ask_user(question, options, header, allow_freeform, hook) },
+        ask_user: lambda { |question:, options:, header:, allow_freeform:, hook:, effects: nil|
+          ask_user(question, options, header, allow_freeform, hook, effects: effects)
+        },
         stop_turn: ->(reason:, hook:) { stop_turn(reason, hook) },
         steer: ->(text:, hook:) { @steer.call(text, source(hook)) },
         stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) }
@@ -86,8 +88,8 @@ module Samagotchi
     # to ask: nil at once. Anything but an answer (a sync handler's text, no
     # answer, cancelled) is nil too.
     # @return [Hash, nil] {selected:, freeform:, selected_indices:}
-    def ask_user(question, options, header, allow_freeform, hook)
-      @question_desk.call.ask_for_hook(question, options, header, allow_freeform, hook)
+    def ask_user(question, options, header, allow_freeform, hook, effects: nil)
+      @question_desk.call.ask_for_hook(question, options, header, allow_freeform, hook, effects: effects)
     end
 
     # Cancel the running turn (reason :hook), after a notice that says why.

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -3,6 +3,7 @@
 require_relative "registry"
 require "digest"
 require_relative "../log"
+require_relative "../guardrails/load_failures"
 require_relative "../memory_bundle/bundle_hook"
 require_relative "../memory_bundle/provenance"
 require_relative "../memory_bundle/manifest"
@@ -90,7 +91,8 @@ module Samagotchi
               raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
 
               Log.error(:hooks, "bundle_hook_load_failed", echo: "[samagotchi:hooks] bundle '#{bundle_name}' hook '#{basename}' failed to load: #{e.class}: #{e.message}", bundle: bundle_name, hook: basename.to_s, error: e.class.name)
-              failures&.add(what, "#{e.class}: #{e.message}", required: fail_closed)
+              failures&.add(what, "#{e.class}: #{e.message}", required: fail_closed,
+                                  location: Guardrails::LoadFailures.location(e, File.dirname(hooks_dir)))
             end
           end
           loaded

data/lib/samagotchi/hooks/registry.rb

@@ -111,8 +111,8 @@ module Samagotchi
     # callables, each given the hook's label. +notify+ takes
     # (text:, level:, hook:, and fallback_for: when the hook gave one: what
     # the line stands in for, HookRoutes#notify) and shows one line to the
-    # user; +ask_user+ takes (question:, options:, header:, allow_freeform:, hook:) and
-    # returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
+    # user; +ask_user+ takes (question:, options:, header:, allow_freeform:, hook:, and
+    # effects: when the hook gave them) and returns the answer hash or nil; +stop_turn+ takes (reason:, hook:) and
     # cancels the running turn (true when it did); +steer+ takes (text:,
     # hook:) and puts the text into the running turn (Engine#steer, true
     # when queued); +stop_generation+ takes (reason:, hook:) and cuts the
@@ -270,9 +270,11 @@ module Samagotchi
       #     to the user; fallback_for: :display marks a line that stands in
       #     for the answer's display (event[:present]), which a UI that
       #     renders the display's links leaves out (HookRoutes#notify)
-      #   event[:ask_user].call(question:, options:, header: nil, allow_freeform: false)
+      #   event[:ask_user].call(question:, options:, header: nil, allow_freeform: false, effects: nil)
       #     -> {selected:, freeform:, selected_indices:} or nil (no one to
-      #     ask, cancelled, bad options)
+      #     ask, cancelled, bad options or effects); effects: tags the
+      #     options a parent agent may not simply pick, by label
+      #     ({ "Run it" => :permit }, see Plugin::Context#ask_user)
       #   event[:stop_turn].call(reason) -> true when the turn was cancelled;
       #     in a before_tool_call event it also denies the call; from
       #     after_turn / session_end it does nothing (false)
@@ -347,6 +349,10 @@ module Samagotchi
         end
       end
 
+      # The events bundle hooks are registered for (any symbol Api#on took).
+      # @return [Array<Symbol>]
+      def bundle_events = @mutex.synchronize { @bundle_hooks.keys }
+
       # @return [Integer] total number of registered hooks (bundle + plain)
       def size
         @mutex.synchronize do
@@ -383,9 +389,10 @@ module Samagotchi
           @runtime&.notify&.call(**notice)
           nil
         }
-        event[:ask_user] ||= lambda { |question:, options:, header: nil, allow_freeform: false|
+        event[:ask_user] ||= lambda { |question:, options:, header: nil, allow_freeform: false, effects: nil|
           @runtime&.ask_user&.call(question: question, options: options, header: header,
-                                   allow_freeform: allow_freeform, hook: event[:hook])
+                                   allow_freeform: allow_freeform, hook: event[:hook],
+                                   **(effects.nil? ? {} : { effects: effects }))
         }
         event[:stop_turn] ||= lambda { |reason|
           next false if TURN_OVER_EVENTS.include?(event[:type])

data/lib/samagotchi/hooks.rb

@@ -26,5 +26,10 @@ module Samagotchi
   #                         event also has context: and targets: (docs/guardrails.md)
   #   :after_tool_call    — after tool execution, before result injection
   module Hooks
+    # Every event a hook can be registered for, in a turn's order
+    # (docs/hooks.md). Plugin::Api#on takes any symbol: `chi bundle check`
+    # warns on one not here.
+    EVENTS = %i[session_start before_turn before_generation generation_progress after_generation before_tool_call
+                after_tool_call after_turn session_end].freeze
   end
 end

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)