samagotchi 0.105.0 → 0.107.0

data/lib/samagotchi/client_id.rb

@@ -34,12 +34,16 @@ module Samagotchi
     PLUGIN = "plugin"
     # A relayed answer (RelayVerifier): relay:<parent8>.
     RELAY_PREFIX = "relay:"
+    # A participant's review turn: review:<participant id> (chi web stamps
+    # it from the participant's token, never from the request's body).
+    REVIEW_PREFIX = "review:"
 
-    # Input a human typed: a web tab, a chi TUI, chi send, and nil (a
-    # worker's initial prompt; a web client may send none). An allowlist:
-    # delegates, plugins, reminders, context changes and any id chi doesn't
-    # know are not.
-    HUMAN_PREFIXES = [WEB_PREFIX, TUI_PREFIX].freeze
+    # Input a human typed: a web tab, a chi TUI, chi send, a participant
+    # (review:, a person or an agent they run: never automatic input), and
+    # nil (a worker's initial prompt; a web client may send none). An
+    # allowlist: delegates, plugins, reminders, context changes and any id
+    # chi doesn't know are not.
+    HUMAN_PREFIXES = [WEB_PREFIX, TUI_PREFIX, REVIEW_PREFIX].freeze
     HUMAN_IDS = [CLI_SEND].freeze
 
     # A person at a screen that shows a command's reply and can answer it
@@ -47,16 +51,17 @@ module Samagotchi
     INTERACTIVE_PREFIXES = [WEB_PREFIX, TUI_PREFIX].freeze
 
     # A turn's origin by its sender (#origin, LastTurn#origin): the ids chi
-    # runs turns for on its own, by prefix; system:reminder is "reminder",
-    # anything else "client".
+    # runs turns for on its own, by prefix, and a participant's ("review");
+    # system:reminder is "reminder", anything else "client".
     ORIGIN_PREFIXES = { DELEGATE_PREFIX => "delegate", CHILD_PREFIX => "delegate_report",
-                        CONTEXT_PREFIX => "context", TASK_PREFIX => "task" }.freeze
+                        CONTEXT_PREFIX => "context", TASK_PREFIX => "task", REVIEW_PREFIX => "review" }.freeze
 
     module_function
 
     # What sent a turn: "delegate" (a delegating parent), "delegate_report"
     # (a child's report), "context" (a context wake), "task" (a task finish
-    # wake), "reminder", else "client" (a person, chi send, a plugin, nil).
+    # wake), "review" (a participant), "reminder", else "client" (the
+    # owner, chi send, a plugin, nil).
     # @return [String]
     def origin(client_id)
       id = client_id.to_s
@@ -81,5 +86,12 @@ module Samagotchi
       id = client_id.to_s
       HUMAN_IDS.include?(id) || HUMAN_PREFIXES.any? { |prefix| id.start_with?(prefix) }
     end
+
+    # The client id a participant's turn carries (chi web's, from their
+    # grant): review:<participant id>.
+    def review(participant_id) = "#{REVIEW_PREFIX}#{participant_id}"
+
+    # Whether +client_id+ is a participant's (review:).
+    def review?(client_id) = client_id.to_s.start_with?(REVIEW_PREFIX)
   end
 end

data/lib/samagotchi/config.rb

@@ -311,6 +311,11 @@ module Samagotchi
       Entry.new(key: "web.annotate_presets",     yaml_path: %w[web annotate_presets],     type: :string, default: "Agreed|Could you please elaborate?", expose: %i[env config cli], lifecycle: :web_start),
       # What a file ref (a tool row's file, a diff line) opens on this machine: a preset (vscode, vscode-insiders, cursor, zed, none) or a URL template with {path} and an optional {line} (Web::Editor).
       Entry.new(key: "web.editor",               yaml_path: %w[web editor],               type: :string, default: "vscode",        expose: %i[env config cli], lifecycle: :web_start),
+      # Participants (chi share): a new grant's lifetime (Nh or Nd, 1h to 30d), and what a grant without its own
+      # takes: its spending cap in dollars ($0 to $1000) and how many of its turns may wait (0 to 20). Read when used.
+      Entry.new(key: "web.participants.expires", yaml_path: %w[web participants expires], type: :string, default: "7d", expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),
+      Entry.new(key: "web.participants.cap",     yaml_path: %w[web participants cap],     type: :float,  default: 2.0,  expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),
+      Entry.new(key: "web.participants.queue",   yaml_path: %w[web participants queue],   type: :integer, default: 3,   expose: %i[env config], lifecycle: :next_matching_turn_display_poll_write),
 
       Entry.new(key: "no_interrupt",             yaml_path: %w[no_interrupt],             type: :bool,   default: false,            expose: %i[env config cli], lifecycle: :next_cli_run),
       Entry.new(key: "no_default_input",         yaml_path: %w[no_default_input],         type: :bool,   default: false,            expose: %i[env config cli], lifecycle: :next_cli_run),
@@ -609,7 +614,7 @@ module Samagotchi
           elsif MAP_ENTRY_KEYS.key?(key)
             map_entry_problems(key, value)
           elsif value.is_a?(Hash) && (known_sections.include?(key) || ENTRIES.any? { |e| e.yaml_path.size > 1 && e.section == key })
-            value.keys.filter_map { |leaf| key_problem("#{key}.#{leaf}") }
+            value.flat_map { |leaf, inner| leaf_problems("#{key}.#{leaf}", inner) }
           elsif known_sections.include?(key)
             # An all-commented section is nil; recap: false turns recaps off.
             value.nil? || (key == "recap" && value == false) ? [] : ["config: '#{key}' must be a mapping of settings; ignored"]
@@ -619,6 +624,16 @@ module Samagotchi
         end + model_ref_problems(data)
       end
 
+      # A section's leaf: a key the registry knows, or a mapping of a
+      # third level (web.participants.cap) whose keys it knows.
+      def leaf_problems(path, value)
+        if value.is_a?(Hash) && ENTRIES.any? { |e| e.key.start_with?("#{path}.") }
+          value.keys.filter_map { |leaf| key_problem("#{path}.#{leaf}") }
+        else
+          [key_problem(path)].compact
+        end
+      end
+
       # What a model ref in config.yml won't do as written: an alias whose
       # target is another alias (aliases apply once, ModelRef), a ref that
       # starts with "<host>/" (only ':' names a host).

data/lib/samagotchi/continue_offer.rb

@@ -3,6 +3,7 @@
 require "time"
 require_relative "last_turn"
 require_relative "log"
+require_relative "steer"
 
 module Samagotchi
   # A session worker's continue offer: what it announces when a turn runs out
@@ -34,12 +35,18 @@ module Samagotchi
     # @param max_iterations [#call] (no_interrupt) → Integer
     # @param queue_command [#call] (line, client_id:) queues a session
     #   command as a card's (Bridge#queue_command, card: true)
-    def initialize(engine:, turn_flow:, run_turn:, max_iterations:, queue_command: nil)
+    # +participant_refused+ (author → reason or nil): why a participant's
+    # turn may no longer run ("revoked", "cap_reached": Worker's check).
+    # @param save [#call] saves the session (a refused Continue's Stop)
+    def initialize(engine:, turn_flow:, run_turn:, max_iterations:, queue_command: nil, participant_refused: ->(_) {},
+                   save: -> {})
       @engine = engine
+      @save = save
       @turn_flow = turn_flow
       @run_turn = run_turn
       @max_iterations = max_iterations
       @queue_command = queue_command
+      @participant_refused = participant_refused
       # A question was posted since the last close (it may have been
       # answered or superseded meanwhile).
       @asked = false
@@ -87,7 +94,14 @@ module Samagotchi
     # it ends (chi answer --option Stop).
     # It carries the offer turn's enqueued_id, so a wait on that turn
     # (ReplyWait's turn:) ends on it too.
+    # A Continue on the offer of a participant who may no longer run a turn
+    # (revoked, expired, at the cap since) is decided here, before anything
+    # says "resume": it ends the offer as a Stop does (#refuse_continue).
     def announce_resolved(result, command)
+      if result.resume && (reason = refusal_of_offer_author)
+        return refuse_continue(reason, command)
+      end
+
       @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command.client_id)
       return if result.resume
 
@@ -124,12 +138,24 @@ module Samagotchi
     # never began leaves it to no other.
     # The continue turn is the offer turn's: its origin carries that turn's
     # enqueued_id, so its last_turn, its reply file and its checkpoint mark
-    # do too, and a wait on that turn (chi answer) gets its reply.
+    # do too, and a wait on that turn (chi answer) gets its reply; and its
+    # author, so a participant's turn continues as theirs, inside the
+    # review boundary and on their spend (never as the owner's). One whose
+    # participant may no longer run a turn isn't continued.
     def run_continue_turn(command)
+      # Refused as it was answered (#announce_resolved): the offer is gone.
+      return @continue_steer = nil unless awaiting?
+
       offer = @turn_flow.offer
       resume_from = @turn_flow.resume_from
       enqueued_id = offer_turn_id
+      author = Steer.sender_author(@engine.session&.last_turn&.author)
       close("answered")
+      if author && (reason = @participant_refused.call(author))
+        @continue_steer = nil
+        return @engine.synchronize_events { refuse_continue(reason, command) }
+      end
+
       steer = @continue_steer
       @continue_steer = nil
       begin
@@ -140,7 +166,7 @@ module Samagotchi
           Log.warn(:worker, "turn_not_begun", continue: true, error: e.class.name, msg: e.message)
           return announce_offer(offer)
         end
-        origin = { client_id: command.client_id, enqueued_id: enqueued_id }.compact
+        origin = { client_id: command.client_id, enqueued_id: enqueued_id, author: author }.compact
         @run_turn.call(nil, continue: true, origin: origin, resumed: true, resume_from: resume_from,
                             max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
           if error
@@ -165,6 +191,37 @@ module Samagotchi
 
     private
 
+    def refusal_of_offer_author
+      author = Steer.sender_author(@engine.session&.last_turn&.author)
+      author && @participant_refused.call(author)
+    end
+
+    # The offer of a participant refused since (+reason+: revoked,
+    # cap_reached) ends as a Stop: announced as "refused" (with a notice
+    # for the owner), the model reads it wasn't continued, last_turn says
+    # not_continued with the offer turn's enqueued_id (a wait on it ends),
+    # and awaiting_continue? goes false (idle exit, /exit, the held
+    # participant turns go on). The question goes with the next close.
+    # Called with the event log held.
+    def refuse_continue(reason, command)
+      author = @engine.session&.last_turn&.author
+      enqueued_id = offer_turn_id
+      @engine.announce(type: :continue_resolved, decision: "refused", reason: reason.to_s, client_id: command.client_id)
+      @engine.announce(type: :hook_notice, hook: "participants", level: :warn, between_turns: true,
+                       text: format(REFUSED_NOTICE, who: author.to_s.delete_prefix("p:"), reason: REFUSED_WHY.fetch(reason.to_s, reason.to_s)))
+      @turn_flow.abort_continue!
+      session = @engine.session
+      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3), enqueued_id: enqueued_id) if session
+      @continue_steer = nil
+      close("answered")
+      @save.call
+      nil
+    end
+
+    REFUSED_NOTICE = "Not continued: participant %<who>s's turn %<reason>s."
+    REFUSED_WHY = { "revoked" => "is refused (their link was revoked or expired)",
+                    "cap_reached" => "is refused (they reached their review cap)" }.freeze
+
     # The enqueued_id of the turn the offer stands for: the exhausted
     # turn's last_turn (a canceled continue turn's carries the same id);
     # nil when it ran no input (a reminder turn, a delegate's first).

data/lib/samagotchi/delivery.rb

@@ -48,6 +48,16 @@ module Samagotchi
                   "restart it (chi sessions restart ID, or the web's update badge) and send again"
     }.freeze
 
+    # A worker that runs participants' turns inside the review boundary
+    # (Bridge::FEATURES): one without it would run theirs with the owner's
+    # tools, so none is sent to it.
+    REVIEW_FEATURE = "review_turns"
+    REVIEW_UNAVAILABLE = {
+      "error" => "review_unavailable",
+      "detail" => "this session's worker predates participants' turns, so it has no review boundary; " \
+                  "the owner must restart it (chi sessions restart ID, or the web's update badge)"
+    }.freeze
+
     # Whether it is the one every sender defaulting to a step boundary uses.
     def self.next_step?(value) = parse(value) == NEXT_STEP
 

data/lib/samagotchi/engine.rb

@@ -85,6 +85,7 @@ require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
 require_relative "prompt_warmup"
 require_relative "working_set"
+require_relative "participants_watch"
 require_relative "session_participants"
 
 module Samagotchi
@@ -224,6 +225,8 @@ module Samagotchi
       @participants = SessionParticipants.new(state_dir: -> { session_state_dir })
       # Whether the system prompt carries the participants line.
       @participants_line = false
+      # Who is in the review now, and who came or went (#announce_participants).
+      @participants_watch = ParticipantsWatch.new(session_id: -> { @session&.id }, state_dir: -> { session_state_dir })
       @session = nil
       @session_observer = SessionObserver.new
       @metrics = SessionMetrics.new
@@ -595,9 +598,12 @@ module Samagotchi
     # recreate a deleted session's folder; the folder itself may not exist
     # yet before a first turn). Safe from any thread: the recap's, a
     # plugin's, the turn's.
+    # A side request counts against the participant who caused it
+    # (#side_author), its usage's own author when it names one.
     # @param usage [SideUsage]
     # @return [void]
     def note_side_usage(usage)
+      usage = usage.with(author: side_author(usage.kind)) if usage.author.nil?
       synchronize_events do
         block = @metrics.add_side(usage)
         @session_observer.notify(type: :side_usage, kind: usage.kind, side: block)
@@ -609,6 +615,24 @@ module Samagotchi
       @metrics.persist(state_dir: session_state_dir)
     end
 
+    # Who caused a side request of +kind+ now: the running turn's author (a
+    # plugin's ctx.ask_model in it), the last turn's for the idle recap
+    # (it recaps that turn); nil, the owner's, for anything else (an owner
+    # command's ask_model between turns).
+    # @return [String, nil]
+    def side_author(kind)
+      return nil unless turn_running? || kind.to_s == RECAP_SIDE_KIND
+
+      Steer.sender_author(@guardrail_wiring.turn_author)
+    end
+
+    RECAP_SIDE_KIND = "recap"
+
+    # The running turn's author when a participant wrote it, else nil
+    # (ctx.turn_author, the hooks' author).
+    # @return [String, nil]
+    def turn_author = turn_running? ? Steer.sender_author(@guardrail_wiring.turn_author) : nil
+
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
 
@@ -797,7 +821,7 @@ module Samagotchi
     # UIs need in the event log, emitted outside any turn's stream.
     ANNOUNCEABLE_EVENTS = %i[turn_enqueued turn_dequeued input_merged prompt_restored continue_offered continue_resolved
                              command_queued command_ran context_added card hook_notice guardrail_warning
-                             plugin_init_started plugin_init_finished working_set_updated].freeze
+                             plugin_init_started plugin_init_finished working_set_updated participants_changed].freeze
 
     # Put a transport-level event into the ordered event log. Unlike turn
     # events it reaches only persistent observers (no turn sink, no memory
@@ -1186,6 +1210,11 @@ module Samagotchi
                                 price_host: model.host_name)
       kit_prompt = kit_prompt_stats
       snapshot = snapshot.merge(kit_prompt: kit_prompt) if kit_prompt
+      # Each participant's spend under their name (participants.json's).
+      if (spend = snapshot[:spend_by_author])
+        named = spend.to_h { |author, row| [author, row.merge(name: @participants.name_for(author, session: @session))] }
+        snapshot = snapshot.merge(spend_by_author: named)
+      end
       # The session's own settings (chi --set), as --set names them.
       settings = @session&.settings&.flat || {}
       snapshot = snapshot.merge(settings: settings) unless settings.empty?
@@ -1302,6 +1331,8 @@ module Samagotchi
     #     that served model under served: (#served_expected_by)
     #   :recap_enabled [Boolean]   whether an idle recap is configured, with
     #     :recap_min_user_turns and :recap_inactivity_seconds (nil when not)
+    #   :participants  [Array<Hash>] who is in the review now ({id:, name:,
+    #     kind:}; ParticipantsWatch#active), [] for nobody
     def session_state_snapshot
       served_pair = served_model(probe: false)
       metrics = @metrics.snapshot
@@ -1330,7 +1361,8 @@ module Samagotchi
         **setting_chips(SessionSetting::ALL, model),
         recap_enabled: !@recap.nil?,
         recap_min_user_turns: @recap&.min_user_turns,
-        recap_inactivity_seconds: @recap&.inactivity&.to_i
+        recap_inactivity_seconds: @recap&.inactivity&.to_i,
+        participants: @participants_watch.active
       }
     end
 
@@ -1473,6 +1505,17 @@ module Samagotchi
                                        **stop_facts(event))
     end
 
+    # A participant joined (invited) or left (revoked, expired) since the
+    # last look: :participants_changed to the observers (ParticipantsWatch;
+    # the worker looks on its idle tick). The first look announces nobody.
+    # @return [ParticipantsWatch::Change, nil]
+    def announce_participants
+      change = @participants_watch.changes or return nil
+
+      announce(change.to_event)
+      change
+    end
+
     # Reads the session's participants at a turn's start; the first to join
     # and the last to leave rebuild the system prompt (its participants
     # line), once each: a turn in between sends the same prefix.
@@ -1640,7 +1683,8 @@ module Samagotchi
         event_routes: @event_routes,
         question_desk: -> { @question_desk },
         cancel_controller: -> { active_cancel_controller },
-        steer: ->(text, source) { steer(text, source: source) }
+        steer: ->(text, source) { steer(text, source: source) },
+        turn_author: -> { turn_author }
       )
     end
     private :build_hook_routes
@@ -2105,6 +2149,9 @@ module Samagotchi
       turn_started[:resumed] = true if turn.resumed?
       turn_started[:images] = image_refs unless image_refs.empty?
       turn_started[:cut_after] = steer_cut_after
+      # A participant's turn names them (author, author_name) for the UIs'
+      # badge; the owner's turn_started stays as it was.
+      turn_started.merge!(author_fields(turn.origin, session: session))
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
@@ -2256,7 +2303,9 @@ module Samagotchi
       # Inject due reminders as a tail system message (after history, before
       # the new user prompt) to preserve prefix KV cache. Mutating the head
       # system prompt invalidates cache for the entire prefix.
-      due_reminders = @reminder_queue.inject!(turn.messages)
+      # Not into a participant's turn: the owner's reminders are the owner's,
+      # and would be used up there under the review boundary.
+      due_reminders = Steer.participant_author?(turn.origin&.dig(:author)) ? [] : @reminder_queue.inject!(turn.messages)
       if due_reminders.any?
         emit_event(turn.on_event, {
           type: :reminder_injected,
@@ -2617,12 +2666,18 @@ module Samagotchi
     end
 
     # Restore the current session's conversation to a #messages_checkpoint.
+    # Between turns the working set is announced when that changed it (a
+    # !rollback or a canceled continue dropping the turn's tool calls, the
+    # set emptied too), so the page doesn't keep the dropped items until
+    # the next request.
     # @param checkpoint [Array<Hash>]
     # @return [Array<Hash>] the session's messages
     def rollback_to(checkpoint)
       raise ArgumentError, "no current session" unless @session
 
-      replace_session_messages(@session, clone_messages(checkpoint))
+      messages = replace_session_messages(@session, clone_messages(checkpoint))
+      announce_working_set unless turn_running?
+      messages
     end
 
     # Clone a messages array (shallow dup of each element).
@@ -2826,7 +2881,8 @@ module Samagotchi
         prompt_files: -> { @prompt_builder&.prompt_files || [] },
         frontend: -> { interface },
         cost: -> { @metrics.cost },
-        usage: -> { @metrics.usage }
+        usage: -> { @metrics.usage },
+        turn_author: -> { turn_author }
       )
     end
 

data/lib/samagotchi/guardrail_wiring.rb

@@ -113,11 +113,21 @@ module Samagotchi
 
     # The gate's core checks, in order. A delegate child's boundary comes
     # before the rules, so its ask keeps the child-boundary rule id (and
-    # its once/session scopes) when a strict rule asks too.
+    # its once/session scopes) when a strict rule asks too. The review
+    # boundary comes before both: a participant's turn is denied what it
+    # may not do, never asked about it (deny is sticky, so no later vote
+    # can turn it into a question).
     def checks
       rules = self.rules
-      [@failures, rules.hook_asks, protected_paths, (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch),
-       child_boundary, rules].compact
+      [@failures, review_boundary, rules.hook_asks, protected_paths,
+       (@scratch_writes ||= Guardrails::ScratchWrites.new if @scratch), child_boundary, rules].compact
+    end
+
+    # A participant's turn's boundary (Guardrails::ReviewBoundary): in
+    # every session, a no-op unless the running turn's author is a
+    # participant's.
+    def review_boundary
+      @review_boundary ||= Guardrails::ReviewBoundary.new(author: -> { turn_author }, root: -> { boundary_root })
     end
 
     # The delegate child's boundary (Guardrails::ChildBoundary); nil for

data/lib/samagotchi/guardrails/review_boundary.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "review_paths"
+require_relative "../toolkit"
+require_relative "../steer"
+
+module Samagotchi
+  module Guardrails
+    # A participant's turn may only read (D3, D4: it proposes, the owner
+    # applies). A core check, on in every guardrails mode and with
+    # guardrails.enabled: false, active only while the running turn's author
+    # is a participant (GuardrailWiring#checks); the owner's turns never get
+    # it. It denies, never asks (nobody on the participant's side may
+    # approve, and the owner's approval would be the participant's text
+    # acting with the owner's power), every call outside the review kit
+    # (Toolkit::REVIEW_TOOLS). Not forget_outputs: it would replace the
+    # owner's earlier tool outputs with a note of the participant's, which
+    # later owner turns read as their own output, with no review header.
+    #   read: ReviewPaths: only under the session's project root, never a file of
+    #     the read denylist (chi's state and config dirs, home secret dirs,
+    #     project secret files), checked on the path as given and as it
+    #     resolves (a symlink in the project to ~/.ssh is ~/.ssh);
+    #   memory_read: the project scope only, named (no fallback to system);
+    #   anything else, call_tool's real target included: a call_tool of a
+    #     built-in reaches the gate as that built-in (ToolRunner#unwrapped),
+    #     so what is left of call_tool is a plugin or MCP tool, denied in v1.
+    # The declared tools stay the session's (no prompt rebuild per author),
+    # so a participant turn's model may still try a write: it is denied
+    # here, with the header's "This turn may only read" to keep it rare.
+    class ReviewBoundary
+      RULE = "review-boundary"
+      SOURCE = "core"
+      ALLOWED = Toolkit::REVIEW_TOOLS
+      PROJECT_SCOPE = "project"
+
+      ADVICE = "This is a participant's review turn: answer from what you can read and propose any change as " \
+               "text or a diff for the owner to apply."
+      NOT_IN_KIT = "a participant's review turn may only read (read, memory_read): %s is not allowed"
+      OUTSIDE = "a participant's review turn reads only inside the session's project"
+      SECRET = "a participant's review turn can't read secrets or chi's own files"
+      HOME_ROOT = "a participant's review turn reads only inside a project, and this session's folder is the " \
+                  "home folder or above it"
+      READ_REFUSALS = { ReviewPaths::OUTSIDE => OUTSIDE, ReviewPaths::SECRET => SECRET, ReviewPaths::HOME_ROOT => HOME_ROOT }.freeze
+      MEMORY_SCOPE = "a participant's review turn reads project memories only: call memory_read with scope: project"
+
+      # @param author [#call] → String, nil: the running turn's author
+      #   (GuardrailWiring#turn_author); the check is off unless it is a
+      #   participant's (Steer.participant_author?)
+      # @param root [#call] → String, nil: the session's project root (the
+      #   work tree top of its folder); nil denies every read
+      # @param denied_dirs [#call] → Array<String>: chi's own dirs (state,
+      #   config: sessions, grants, the web token, memories and .bundles,
+      #   config.yml, hooks)
+      # @param home [#call] → String, nil
+      def initialize(author:, root:, denied_dirs: -> { ReviewPaths.chi_dirs }, home: -> { Dir.home })
+        @author = author
+        @root = root
+        @denied_dirs = denied_dirs
+        @home = home
+      end
+
+      # Vote on +verdict+ (its call and targets).
+      def check(verdict)
+        return verdict unless Steer.participant_author?(@author.call)
+
+        reason = refusal(verdict)
+        return verdict unless reason
+
+        verdict.deny!(reason, rule: RULE, source: SOURCE, decided_by: "core", advice: ADVICE)
+      end
+
+      private
+
+      def refusal(verdict)
+        call = verdict.call || {}
+        tool = call[:name].to_s
+        return format(NOT_IN_KIT, tool_label(tool, verdict.targets)) unless ALLOWED.include?(tool)
+
+        case tool
+        when "read" then read_refusal(verdict.targets&.paths || [])
+        when "memory_read" then MEMORY_SCOPE unless call[:scope].to_s.strip.downcase == PROJECT_SCOPE
+        end
+      end
+
+      # A plugin or MCP tool behind call_tool names what it acts as.
+      def tool_label(tool, targets)
+        acts_as = targets&.acts_as
+        acts_as && acts_as != tool ? "#{tool} (#{acts_as})" : tool
+      end
+
+      def read_refusal(paths)
+        paths_check = ReviewPaths.new(root: @root.call, denied_dirs: @denied_dirs.call, home: @home.call)
+        READ_REFUSALS[paths_check.refusal(paths)]
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/review_paths.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "protected_paths"
+require_relative "shell_paths"
+require_relative "../paths"
+
+module Samagotchi
+  module Guardrails
+    # What a participant may read (the shared-sessions plan's §2): a file
+    # under the session's project root that isn't on the read denylist
+    # (chi's state and config dirs, home secret dirs, project secret files),
+    # checked on the path as given and as it resolves (a symlink in the
+    # project to ~/.ssh is ~/.ssh). ReviewBoundary asks it for every read of
+    # a participant's turn; a review session's subjects (chi review, the
+    # participant page's Plan) go through the same check.
+    class ReviewPaths
+      # Home folders that hold keys and tokens, never read in a review turn.
+      HOME_SECRET_DIRS = %w[.ssh .gnupg .aws].freeze
+      # Project files that hold secrets, by a path part's name: .env*,
+      # netrc, keys and certificates, anything named credentials, package
+      # registry tokens (.npmrc, .pypirc), ssh keys, terraform state, a
+      # secrets file; and a git config (.git/config, a submodule's
+      # .git/modules/x/config), checked apart.
+      SECRET_FILE = /\A(?:\.env.*|[._]netrc|.*\.(?:pem|key|p12|pfx|tfstate(?:\.backup)?)|.*credentials.*|
+                       \.npmrc|\.pypirc|\.git-credentials|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|secrets?\.(?:ya?ml|json))\z/xi
+      # The .docker/config.json kind: a dot dir's config holding tokens.
+      SECRET_DIR_FILES = { ".docker" => "config.json", ".kube" => "config" }.freeze
+      GIT_DIR = ".git"
+
+      # Why a path can't be read (#refusal).
+      OUTSIDE = :outside
+      SECRET = :secret
+      HOME_ROOT = :home_root
+
+      # chi's state dir and config dir, as Paths has them now.
+      def self.chi_dirs = [Paths.state_dir, File.join(Paths.config_home, Paths::APP_DIR)]
+
+      # @param root [String, nil] the session's project root (the work tree
+      #   top of its folder); nil or blank refuses every path
+      # @param denied_dirs [Array<String>] chi's own dirs (state, config:
+      #   sessions, grants, the web token, memories and .bundles,
+      #   config.yml, hooks)
+      # @param home [String, nil]
+      def initialize(root:, denied_dirs: ReviewPaths.chi_dirs, home: Dir.home)
+        @root = root.to_s
+        @denied_dirs = denied_dirs
+        @home = home.to_s
+      end
+
+      # Why +paths+ can't all be read, or nil when they can: OUTSIDE (no
+      # path, no root, or a path outside the root), HOME_ROOT (the root is
+      # the home folder or above it) or SECRET.
+      # @param paths [Array<String>] absolute, or relative to the cwd
+      # @return [Symbol, nil]
+      def refusal(paths)
+        return OUTSIDE if paths.empty? || @root.empty?
+
+        real_root = ProtectedPaths.real(@root)
+        return HOME_ROOT if !@home.empty? && ShellPaths.within?(ProtectedPaths.real(@home), real_root)
+
+        paths.each do |path|
+          given = File.expand_path(path)
+          real = ProtectedPaths.real(given)
+          return OUTSIDE unless ShellPaths.within?(real, real_root)
+          return SECRET if secret?(given) || secret?(real)
+        end
+        nil
+      end
+
+      private
+
+      def secret?(path)
+        dirs = @denied_dirs.compact.map { |dir| File.expand_path(dir) }
+        dirs += dirs.map { |dir| ProtectedPaths.real(dir) }
+        dirs += HOME_SECRET_DIRS.map { |dir| File.join(@home, dir) } unless @home.empty?
+        return true if dirs.any? { |dir| ShellPaths.within?(path, dir) }
+
+        parts = path.split(File::SEPARATOR)
+        return true if parts.any? { |part| SECRET_FILE.match?(part) }
+        return true if parts.each_cons(2).any? { |dir, file| SECRET_DIR_FILES[dir.downcase] == file.downcase }
+
+        git_config?(parts)
+      end
+
+      # A config file anywhere under a .git dir (.git/config,
+      # .git/modules/<sub>/config, a worktree's config.worktree).
+      def git_config?(parts)
+        git = parts.index { |part| part.casecmp?(GIT_DIR) } or return false
+        parts[(git + 1)..].any? { |part| part.downcase.start_with?("config") }
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails.rb

@@ -13,6 +13,7 @@ require_relative "guardrails/approvals"
 require_relative "guardrails/protected_paths"
 require_relative "guardrails/scratch_writes"
 require_relative "guardrails/child_boundary"
+require_relative "guardrails/review_boundary"
 require_relative "guardrails/load_failures"
 require_relative "guardrails/rules"
 require_relative "guardrails/gate"

data/lib/samagotchi/hook_routes.rb

@@ -22,11 +22,13 @@ module Samagotchi
     # @param question_desk     [#call] → QuestionDesk
     # @param cancel_controller [#call] → the running turn's CancellationController, nil
     # @param steer             [#call] (text, source) → steers the running turn
-    def initialize(event_routes:, question_desk:, cancel_controller:, steer:)
+    # @param turn_author       [#call] → the running turn's participant author, nil
+    def initialize(event_routes:, question_desk:, cancel_controller:, steer:, turn_author: -> {})
       @event_routes = event_routes
       @question_desk = question_desk
       @cancel_controller = cancel_controller
       @steer = steer
+      @turn_author = turn_author
       @unknown_fallbacks = Set.new
     end
 
@@ -40,7 +42,8 @@ module Samagotchi
         ask_user: ->(question) { ask_user(question) },
         stop_turn: ->(reason:, hook:) { stop_turn(reason, hook) },
         steer: ->(text:, hook:) { @steer.call(text, source(hook)) },
-        stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) }
+        stop_generation: ->(reason:, hook:) { stop_generation(reason, hook) },
+        turn_author: @turn_author
       )
     end