samagotchi 0.121.1 → 0.123.0

data/lib/samagotchi/engine.rb

@@ -41,6 +41,8 @@ require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
 require_relative "toolkit_binding"
+require_relative "participant_mode"
+require_relative "toolkit_suggest"
 require_relative "tool_loads"
 require_relative "answer_tail"
 require_relative "archive_store"
@@ -156,6 +158,8 @@ module Samagotchi
       @no_interrupt = no_interrupt
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
+      @toolkit_audit_thread = nil
+      @toolkit_warmup_thread = nil
       @host_registry = host_registry || HostRegistry.new
       # A model given here (a worker's session model) is the one it runs,
       # so its host is checked; the config default is only checked once it
@@ -237,7 +241,7 @@ module Samagotchi
       # start: their names for the messages they wrote.
       @participants = SessionParticipants.new(state_dir: -> { session_state_dir })
       # Whether the system prompt carries the participants line.
-      @participants_line = false
+      @participants_line = nil
       # 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
@@ -378,6 +382,9 @@ module Samagotchi
       @kernel.session_dir = -> { @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir) }
       @kernel.guardrail_gate = @guardrail_wiring.gate
       @kernel.participant_turn = -> { Steer.participant_author?(turn_author) }
+      @kernel.participant_mode = -> { @guardrail_wiring.turn_mode }
+      # A pair turn stops once its participant passed their cap.
+      @kernel.generation_guard = -> { guard_participant_spend }
       # The turn-end warm-up; the kernel asks it for a slot pin per request.
       @prompt_warmup = PromptWarmup.new
       @kernel.warmup = @prompt_warmup
@@ -407,7 +414,10 @@ module Samagotchi
         # from config on every ask, and the running turn's cancel controller
         # closes a judgment that is no longer wanted.
         system_one: -> { SystemOne::Client.from_config(host_registry: @host_registry) },
-        cancel_controller: -> { active_cancel_controller }
+        cancel_controller: -> { active_cancel_controller },
+        # A participant's turn: their name on the owner's card, their
+        # grant's mode for the turn's (GuardrailWiring#turn_mode).
+        participant: ->(author) { @participants.entry_for(author, session: @session) }
       )
     end
     private :build_guardrail_wiring
@@ -1082,6 +1092,10 @@ module Samagotchi
 
     # How long #shutdown waits for the running anytime commands, in all.
     SHUTDOWN_JOIN_SECONDS = 3.0
+    # How long #shutdown waits for a running toolkit audit ask (a one-shot
+    # -p --non-interactive exits right after its turn); a slower ask goes
+    # unlogged.
+    TOOLKIT_AUDIT_JOIN_SECONDS = 1.0
 
     # The REPL or the session's worker is leaving (/exit, an idle exit, a
     # crash, TERM): stop the idle jobs, give the running anytime commands
@@ -1107,6 +1121,9 @@ module Samagotchi
 
         thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max)
       end
+      @toolkit_audit_thread&.join(TOOLKIT_AUDIT_JOIN_SECONDS)
+      # The warm-up's answer is dropped anyway.
+      stop_toolkit_warmup
       left = threads.count(&:alive?)
       Log.warn(:plugins, "anytime_commands_left", count: left) if left.positive?
       @plugin_tasks.kill_leftovers
@@ -1387,6 +1404,34 @@ module Samagotchi
 
     def session_state_dir = @session_state_dir || Session.default_state_dir
 
+    # Whether a participant's pair turn must stop, read before each of its
+    # generations (#guard_participant_spend): author ("p:<id>") → why (their
+    # link ended, or they passed their cap), nil while it may go on. The
+    # Worker sets it (Worker#participant_turn_stop); without one (the REPL)
+    # nothing is checked mid-turn.
+    attr_writer :participant_stop
+
+    # What a participant turn's stop is attributed to (HookRoutes#stop_turn).
+    PARTICIPANTS_HOOK = "participants"
+
+    # Before each generation (KernelLoop#generation_guard): a pair turn whose
+    # participant's link ended, or whose spend (Engine#metrics: their
+    # finished turns, this one's finished generations, their side requests)
+    # passed their cap, stops on the plugins' stop path (cost-cap's,
+    # work-cap's), with its notice. A generation's own cost is known only
+    # once it ends, so a turn can pass the cap by its last generation. The
+    # turn-start check is the Worker's (Worker#participant_refusal); a
+    # review turn only reads, and keeps to it.
+    def guard_participant_spend
+      author = turn_author
+      return if author.nil? || @participant_stop.nil?
+      return unless @guardrail_wiring.turn_mode == ParticipantMode::PAIR
+
+      reason = @participant_stop.call(author) or return
+      hook_stop_turn(reason, PARTICIPANTS_HOOK)
+    end
+    private :guard_participant_spend
+
     # The running turn's metrics so far, saved as a turn a worker died in
     # would leave them (SessionMetrics#persist's running_turn): a worker's
     # turn checkpoint (TurnCheckpoint) calls it when it writes.
@@ -1492,14 +1537,15 @@ module Samagotchi
       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.
+    # Reads the session's participants at a turn's start; the first to join,
+    # the first invited to act (a pair participant: the line's words) and
+    # the last to leave rebuild the system prompt (its participants line),
+    # once each: a turn in between sends the same prefix.
     def refresh_participants!(session)
-      active = @participants.refresh!(session).active?
-      return if active == @participants_line
+      line = @participants.refresh!(session).prompt_mode(session)
+      return if line == @participants_line
 
-      @participants_line = active
+      @participants_line = line
       @prompt_builder.reset!
     end
     private :refresh_participants!
@@ -1516,6 +1562,14 @@ module Samagotchi
       Steer.author_fields(author, @participants.name_for(author, session: session))
     end
 
+    # A participant's opening message keeps the rules it was delivered under
+    # (ParticipantMode), stamped before any request carries it, so its header
+    # never changes when the session's mode does.
+    def participant_mode_fields(author)
+      mode = Steer.participant_author?(author) && @guardrail_wiring.turn_mode
+      mode ? { participant_mode: mode.to_s } : {}
+    end
+
     # Why a turn stopped (TurnEndings#stop_facts).
     def stop_facts(event) = @turn_endings.stop_facts(event)
     private :stop_facts
@@ -2124,10 +2178,16 @@ module Samagotchi
       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.author, session: session))
+      turn_started.merge!(author_fields(turn.origin.author, session: session),
+                          participant_mode_fields(turn.origin.author))
       emit_event(turn.on_event, turn.tag(turn_started))
       raise image_error if image_error
 
+      # On mode's ask starts here too; the turn joins it before
+      # apply_toolkit! below, so its latency hides behind the probes and
+      # the init wait.
+      toolkit_suggestion = start_toolkit_suggestion(turn)
+
       # The window and the profile probes run after run_turn's probe-cancel
       # swap, so a Stop cuts them; a failure ends the turn as turn_failed.
       # The cache itself was dropped at the previous turn's end, so this
@@ -2142,7 +2202,10 @@ module Samagotchi
       refuse_images!(turn.settings.vision) unless image_refs.empty?
       # A Stop during the probes: the turn ends before the load-failure
       # warnings, which show once, so the next turn still shows them.
-      return false if turn.controller.cancelled?
+      if turn.controller.cancelled?
+        toolkit_suggestion&.abandon(:canceled)
+        return false
+      end
 
       announce_guardrail_failures(turn.on_event)
       # Plugins' slow setup that brings tools (an MCP server's first
@@ -2155,9 +2218,12 @@ module Samagotchi
       # session's toolkit (a /toolkit change since the last turn): what the
       # prompt built next declares, unchanged until the next turn's start.
       apply_staged_tools!
+      # On mode: the suggested kit, before anything is declared (a Stop
+      # during the wait is caught by the check below).
+      settle_toolkit_suggestion(turn, toolkit_suggestion)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
-      # A Stop during the wait above: the turn ends here,
+      # A Stop during the waits above: the turn ends here,
       # before the hooks run or a reminder is used up.
       return false if turn.controller.cancelled?
 
@@ -2174,6 +2240,10 @@ module Samagotchi
 
       turn_messages(turn, image_refs)
       true
+    ensure
+      # A turn that ended (a failure, an Interrupt) before it settled the
+      # ask: its line says so. Nothing once it was settled.
+      toolkit_suggestion&.abandon(:failed)
     end
     private :prepare_turn
 
@@ -2289,7 +2359,7 @@ module Samagotchi
 
       unless turn.continue
         user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin.author),
-                         MessageTime::KEY => turn.at }
+                         **participant_mode_fields(turn.origin.author), MessageTime::KEY => turn.at }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt
@@ -2712,6 +2782,213 @@ module Samagotchi
     def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
     private :apply_toolkit!
 
+    # Start the toolkit classifier after :turn_started, for audit and on
+    # mode alike (one eligibility, one snapshot, one thread). All session
+    # and tool-registry reads happen here; the thread receives only this
+    # snapshot. Audit never blocks: the thread logs its line. On mode
+    # returns the ask's Pending, which the turn joins before apply_toolkit!
+    # (#settle_toolkit_suggestion), with the turn's controller as the
+    # request's cancel controller.
+    # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
+    def start_toolkit_suggestion(turn)
+      mode = Config.get("toolkit.suggest.mode").to_s
+      return if mode == "off"
+
+      joined = mode == "on"
+      session = turn.session
+      default = Toolkit.of(session.toolkit)
+      log = toolkit_suggestion_log
+      # The predicate checks the session first; the kits (memory kits are
+      # read from disk) and the log (read whole) only when it gets there.
+      kits = nil
+      candidates = nil
+      return unless ToolkitSuggest.eligible?(
+        session: session, prompt: turn.prompt, author: turn.origin.author,
+        candidate_count: lambda {
+          kits = @toolkit_binding.kits
+          candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
+          candidates.size
+        },
+        last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
+        defer_turns: Config.get("toolkit.suggest.defer_turns"),
+        defer_tokens: Config.get("toolkit.suggest.defer_tokens")
+      )
+
+      # One ask at a time: an eligible turn while the last one still runs
+      # goes unasked, and says so.
+      if @toolkit_audit_thread&.alive?
+        Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
+        return
+      end
+
+      client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+      return unless client
+
+      # D7: on a shared single-slot server audit's free ask would compete
+      # with the turn's prefill, and any ask evicts the session's cached
+      # prefix: on mode asks only on a first turn there (nothing is cached
+      # yet worth keeping), never on the deferred path.
+      if (!joined || ToolkitSuggest.model_reply?(session.messages)) && toolkit_judge_shares_local_host?(client.host)
+        Log.info(:toolkit, "toolkit_suggest_shared_host_skipped", session_id: session.id, host: client.host)
+        return
+      end
+
+      # The warm-up's only value is the cache: the real ask never queues
+      # behind it.
+      stop_toolkit_warmup
+
+      # Rules, not tool lists: this runs before await_init_tasks and
+      # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
+      # registered yet; the report expands the rules (ToolkitSuggest.rules).
+      snapshots = candidates.map do |kit|
+        ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
+                                      rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
+      end.freeze
+      default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
+                                                       rules: ToolkitSuggest.rules(default.resolve(kits)))
+      core_tools = @tools.entries(toolkit: nil).select(&:core?).map { |entry| entry.name.dup.freeze }.freeze
+      state = ToolkitSuggest.question(
+        default: default, kits: kits, project: File.basename(session.project_root.to_s),
+        prompt: turn.prompt
+      ).last
+      snapshot = ToolkitSuggest::Snapshot.new(
+        session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
+        default: default_snapshot, candidates: snapshots, core_tools: core_tools,
+        state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
+      )
+      threshold = Config.get("toolkit.suggest.threshold")
+      pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
+                                            timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
+      # On mode: cut by a Stop while the turn waits (Pending#wait), not
+      # by one after it went on; audit's ask is never cut.
+      controller = joined ? pending.cancel_controller : nil
+      @toolkit_audit_thread = Thread.new do
+        judged = nil
+        begin
+          judged = ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
+                                        cancel_controller: controller)
+        rescue LLM::RequestCancelled
+          nil
+        rescue StandardError => e
+          ToolkitSuggest.warn(e)
+        ensure
+          pending.finish(judged)
+        end
+      end
+      joined ? pending : nil
+    rescue StandardError => e
+      ToolkitSuggest.warn(e)
+      nil
+    end
+    private :start_toolkit_suggestion
+
+    # On mode, before apply_toolkit!: wait for the ask (#start_toolkit_
+    # suggestion) up to System 1's timeout from its start, or until a Stop,
+    # and put the session on a candidate picked with confidence ≥ threshold
+    # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
+    # other outcome (the default, below threshold, undecided, no judgment,
+    # a timeout, a Stop) leaves the session on its default. Nothing here
+    # sends a request; prepare_turn's cancel check ends a stopped turn. A
+    # Stop wins over an answer already in (Pending#wait checks it first).
+    def settle_toolkit_suggestion(turn, pending)
+      return if pending.nil?
+
+      outcome, judged = pending.wait(turn.controller)
+      unless outcome == :answered
+        Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
+        return
+      end
+      return if judged.nil?
+
+      pending.record(toolkit_suggestion_outcome(turn.session, judged))
+    rescue StandardError => e
+      ToolkitSuggest.warn(e)
+      pending&.record("failed")
+    end
+    private :settle_toolkit_suggestion
+
+    # What the turn does with an answered ask, as the log line's did:
+    # suggested (switched), chosen (the toolkit isn't the default any
+    # more), unavailable (the kit is gone), defer or default.
+    def toolkit_suggestion_outcome(session, judged)
+      case judged.would
+      when "suggested"
+        return "chosen" unless session.toolkit_origin == "default"
+        return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
+
+        switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
+                                                                            deferred: ToolkitSuggest.model_reply?(session.messages))
+        switched ? "suggested" : "chosen"
+      when "defer" then "defer"
+      else "default"
+      end
+    end
+    private :toolkit_suggestion_outcome
+
+    # On mode, as an idle worker starts (Worker#start_background): one ask
+    # with the real question and a stand-in prompt, on its own thread,
+    # never logged and never waited for, so System 1's server has the
+    # question's prefix cached for the first prompt. Only for a session a
+    # first prompt could be asked for: origin default, no model reply, not
+    # a delegate child or a review session, at least two candidates; and
+    # not when the worker starts on a first prompt (that ask comes at once).
+    def warm_toolkit_suggestion!
+      return unless Config.get("toolkit.suggest.mode").to_s == "on"
+
+      session = @session
+      return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
+      return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
+
+      default = Toolkit.of(session.toolkit)
+      kits = @toolkit_binding.kits
+      return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
+
+      client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+      return unless client
+      # D7: on the model's own single-slot server it would evict the
+      # session's cached prefix for a question that may never come.
+      return if toolkit_judge_shares_local_host?(client.host)
+
+      project = File.basename(session.project_root.to_s)
+      @toolkit_warmup_thread = Thread.new do
+        ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
+      end
+    rescue StandardError => e
+      ToolkitSuggest.warn(e)
+      nil
+    end
+    public :warm_toolkit_suggestion!
+
+    # A still-running warm-up, stopped: a real ask (or the worker leaving)
+    # doesn't wait behind it.
+    def stop_toolkit_warmup
+      @toolkit_warmup_thread&.kill
+      @toolkit_warmup_thread = nil
+    end
+    private :stop_toolkit_warmup
+
+    def toolkit_suggestion_log
+      path = ToolkitSuggest.log_path(session_state_dir)
+      SystemOne::Log.new(dir: File.dirname(path), file: File.basename(path),
+                         warn: lambda { |reason|
+                           Log.warn(:toolkit, "toolkit_suggest_log_failed", echo: "[samagotchi:toolkit] #{reason}")
+                         })
+    end
+    private :toolkit_suggestion_log
+
+    # D7: System 1's host is the session's model server, and a local one
+    # (a single-slot Splash or llama.cpp): the same name, or two hosts:
+    # entries for one server root (scheme, host, port).
+    def toolkit_judge_shares_local_host?(judge_name)
+      model_host, = @host_registry.host_for_model(effective_model_name)
+      return false if model_host.nil? || model_host.remote?
+      return true if judge_name.to_s.strip.casecmp?(model_host.name.to_s)
+
+      judge = @host_registry.find_entry(judge_name)
+      !judge.nil? && judge.root_url.downcase == model_host.root_url.downcase
+    end
+    private :toolkit_judge_shares_local_host?
+
     # The session's toolkit (see #initialize for when).
     def build_toolkit_binding
       ToolkitBinding.new(

data/lib/samagotchi/event_fanout.rb

@@ -56,7 +56,6 @@ module Samagotchi
       @announce_or_hold = announce_or_hold
       @working_set_emitted = nil
     end
-    # rubocop:enable Metrics/ParameterLists
 
     # Always return a handler so raw kernel loop events reach the persistent
     # SessionObserver (and thus the analytics collector) even when there is no

data/lib/samagotchi/gem_update.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "open3"
 require "rbconfig"
 require "rubygems/package"
+require "time"
 require_relative "version"
 require_relative "redacted_inspect"
 
@@ -22,12 +23,14 @@ module Samagotchi
     end
 
     LATEST_URL = URI("https://rubygems.org/api/v1/versions/samagotchi/latest.json")
+    RELEASES_URL = URI("https://rubygems.org/api/v1/versions/samagotchi.json")
     # Not SAMAGOTCHI_UPDATE_GEM: that is the env form of config update.gem.
     LOCAL_ENV = "SAMAGOTCHI_UPDATE_GEM_FILE"
     TIMEOUT = 5
 
     # source is what `gem install` takes: the gem's name, or a .gem file.
     Latest = Struct.new(:version, :source, keyword_init: true)
+    Release = Data.define(:version, :created_at, :prerelease)
 
     # Runs a command without a shell; [output, success].
     class Runner
@@ -57,7 +60,7 @@ module Samagotchi
       local = @env[LOCAL_ENV].to_s
       return Latest.new(version: Gem::Package.new(local).spec.version.to_s, source: local) unless local.empty?
 
-      version = JSON.parse(@fetcher.call.to_s)["version"].to_s
+      version = JSON.parse(fetch_body(LATEST_URL).to_s)["version"].to_s
       raise Error, "rubygems.org answered without a version" if version.empty? || !Gem::Version.correct?(version)
 
       Latest.new(version: version, source: "samagotchi")
@@ -67,6 +70,29 @@ module Samagotchi
       raise Error, "#{e.class}: #{e.message}".lines.first.strip
     end
 
+    # @return [Array<Release>] rubygems releases, or the one local smoke gem
+    def releases
+      local = @env[LOCAL_ENV].to_s
+      return [local_release(local)] unless local.empty?
+
+      records = JSON.parse(fetch_body(RELEASES_URL).to_s)
+      raise Error, "rubygems.org answered without a releases list" unless records.is_a?(Array)
+
+      records.map do |record|
+        version = record["number"].to_s
+        created_at = record["created_at"].to_s
+        unless Gem::Version.correct?(version) && !created_at.empty? && [true, false].include?(record["prerelease"])
+          raise Error, "rubygems.org answered with an invalid release"
+        end
+
+        Release.new(version: version, created_at: Time.iso8601(created_at), prerelease: record["prerelease"])
+      end
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "#{e.class}: #{e.message}".lines.first.strip
+    end
+
     def newer?(latest, current = VERSION)
       Gem::Version.new(latest.version) > Gem::Version.new(current)
     end
@@ -83,9 +109,20 @@ module Samagotchi
 
     private
 
-    def fetch
-      Net::HTTP.start(LATEST_URL.host, LATEST_URL.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
-        request = Net::HTTP::Get.new(LATEST_URL)
+    def local_release(path)
+      version = Gem::Package.new(path).spec.version
+      Release.new(version: version.to_s, created_at: File.mtime(path), prerelease: version.prerelease?)
+    end
+
+    def fetch_body(url)
+      return @fetcher.call if @fetcher.arity.zero?
+
+      @fetcher.call(url)
+    end
+
+    def fetch(url = LATEST_URL)
+      Net::HTTP.start(url.host, url.port, use_ssl: true, open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        request = Net::HTTP::Get.new(url)
         request["User-Agent"] = USER_AGENT
         response = http.request(request)
         raise Error, "rubygems.org answered #{response.code}" unless response.code == "200"

data/lib/samagotchi/guardrail_wiring.rb

@@ -15,6 +15,7 @@ require_relative "edit_preview"
 require_relative "system_one"
 require_relative "tool_activity"
 require_relative "turn_origin"
+require_relative "participant_mode"
 
 module Samagotchi
   # An Engine's tool guardrails: who can approve (the interface), the YAML
@@ -44,8 +45,11 @@ module Samagotchi
     # @param system_one [#call] → SystemOne::Client or nil: the judgment client
     #   (nil while `guardrails.system_one.mode` is off or no host is set)
     # @param cancel_controller [#call] → the running turn's CancellationController, nil
+    # @param participant [#call] (author) → the participant's
+    #   Participants::Entry (participants.json: their name, their grant's
+    #   mode), nil for none
     def initialize(scratch:, hooks:, tools:, session:, model_key:, cancelled:, ask:, model_name: -> {},
-                   notify: ->(_message) {}, system_one: -> {}, cancel_controller: -> {})
+                   notify: ->(_message) {}, system_one: -> {}, cancel_controller: -> {}, participant: ->(_author) {})
       @scratch = scratch
       @hooks_lookup = hooks
       @tools_lookup = tools
@@ -57,6 +61,8 @@ module Samagotchi
       @notify = notify
       @system_one = system_one
       @cancel_controller = cancel_controller
+      @participant = participant
+      @turn_mode = nil
       # Bundle name → the rules last loaded from it whole, kept while the
       # installed version needs a newer chi; [name, version] said so once.
       @loaded_bundle_rules = {}
@@ -95,12 +101,24 @@ module Samagotchi
     end
 
     # A turn starts: its origin (Engine#run_turn's TurnOrigin; nil or a
-    # Hash is read as one, TurnOrigin.of), and the git facts read afresh.
+    # Hash is read as one, TurnOrigin.of), the git facts read afresh, and
+    # a participant's turn's mode decided once for the whole turn
+    # (#turn_mode).
     def begin_turn(origin)
       @origin = TurnOrigin.of(origin)
       @git = Guardrails::GitInfo.new
+      author = turn_author
+      @turn_entry = author && @participant.call(author)
+      @turn_mode = author && ParticipantMode.for_turn(@session_lookup.call, @turn_entry)
     end
 
+    # The running participant turn's mode (ParticipantMode.for_turn: :pair
+    # only in a working session for a participant invited to act), decided
+    # at its start; nil for the owner's turns. The boundary in #checks, the
+    # Engine's stamp and mid-turn stop, and ToolRunner read it.
+    # @return [Symbol, nil]
+    attr_reader :turn_mode
+
     # Who wrote the running turn when it isn't the session's owner (its
     # origin's participant author); nil for the owner's turns and every
     # other origin.
@@ -125,23 +143,34 @@ 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. 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).
+    # its once/session scopes) when a strict rule asks too. The
+    # participant's boundary comes before both, by the session's
+    # ParticipantMode: a review turn's (ReviewBoundary) or a pair turn's
+    # (PairBoundary). Either denies what a participant's turn may not do,
+    # never asks about it; both are no-ops for the owner's turns.
     def checks
       rules = self.rules
-      [@failures, review_boundary, rules.hook_asks, protected_paths,
+      [@failures, participant_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.
+    # The boundary for a participant's turn in this session (#checks).
+    def participant_boundary
+      @turn_mode == ParticipantMode::PAIR ? pair_boundary : review_boundary
+    end
+
+    # A participant's review turn's boundary (Guardrails::ReviewBoundary): 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
 
+    # A participant's pair turn's boundary (Guardrails::PairBoundary): a
+    # no-op unless the running turn's author is a participant's.
+    def pair_boundary
+      @pair_boundary ||= Guardrails::PairBoundary.new(author: -> { turn_author }, root: -> { boundary_root })
+    end
+
     # The delegate child's boundary (Guardrails::ChildBoundary); nil for
     # any other session.
     def child_boundary
@@ -263,8 +292,12 @@ module Samagotchi
       label = verdict.targets&.label ||
               ToolActivity.plugin_label(acts_as || verdict.call[:name].to_s, registry: @tools_lookup.call)
       # verdict.call is the call that will run (a hook may have replaced it).
+      # A participant's turn's ask names them and offers once only
+      # (Approval.payload's author:), whichever session it is.
+      author = turn_author
       payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call),
-                                                      only: (SCRATCH_SCOPES if @scratch))
+                                                      only: (SCRATCH_SCOPES if @scratch), author: author,
+                                                      author_name: (@turn_entry&.name if author))
       # A call on chi's own config, hooks or guardrails is the user's to
       # allow, never a parent agent's (Guardrails::ParentPolicy).
       payload[:user_only] = Guardrails::ParentApprovals.protected_facts?(payload[:approval])
@@ -310,7 +343,8 @@ module Samagotchi
     # System 1's judgment of an ask, written to the log before the user is
     # asked, with the decision it led to: "auto" (it answered for the user),
     # "asked" (on mode, the user decides) or "audit" (audit mode). A
-    # participant's review turn is never judged, and no client (mode off, no
+    # participant's turn (review or pair) is never judged, so never
+    # auto-allowed: its asks go to the owner. No client (mode off, no
     # host) means no line at all. A judgment that fails is logged with p nil,
     # so the failures are in the log too.
     # @return [Hash, nil] {id:, p:, auto:}, nil when nothing was written