samagotchi 0.122.0 → 0.124.0

data/lib/samagotchi/participant_mode.rb

@@ -1,11 +1,85 @@
 # frozen_string_literal: true
 
+require_relative "delivery"
+
 module Samagotchi
-  # The rules for a participant's turn. P0 keeps every participant in review
-  # mode; this is the single resolver for the later mode split.
+  # The rules for a participant's turn: the one place that decides them.
+  # - :review — a review session (its review: key, chi review): the turn
+  #   only reads (Guardrails::ReviewBoundary);
+  # - :pair — a working session: the turn acts with the session's tools
+  #   under the owner's guardrails, asks go to the owner
+  #   (Guardrails::PairBoundary keeps secrets and owner-voiced tools out).
+  # No session (nil) is :review. A worker that doesn't name
+  # Delivery::PAIR_FEATURE runs every participant's turn as :review, so
+  # chi web and chi share ask .live, which reads the session's live worker,
+  # before they say what a participant's turn may do.
+  #
+  # .of is the session's: what a participant invited now gets. A turn's is
+  # .for_turn: :pair only for a participant whose grant was issued for it
+  # (Participants::Entry#mode / Grant#mode "pair", stamped at invite when
+  # the owner was shown that their turns act); a grant from before, or one
+  # issued while the session's worker predated pair turns, stays :review.
   module ParticipantMode
+    REVIEW = :review
+    PAIR = :pair
+
     module_function
 
-    def of(_session) = :review
+    # @param session [Session, nil]
+    # @param features [Array<String>, nil] the features of the worker that
+    #   runs the turn (WorkerSidecar#features); nil: this chi's own (the
+    #   worker itself, or the one a delivery will start)
+    # @return [Symbol] :review or :pair
+    def of(session, features: nil)
+      return REVIEW if session.nil? || !session.respond_to?(:review?) || session.review?
+      return REVIEW if features && !features.include?(Delivery::PAIR_FEATURE)
+
+      PAIR
+    end
+
+    # The mode a turn of the participant +entry+ (a Participants::Entry or a
+    # Web::Grants::Grant; nil: unknown) runs under in +session+.
+    # @return [Symbol]
+    def for_turn(session, entry, features: nil)
+      return REVIEW unless of(session, features: features) == PAIR
+      return REVIEW unless entry.respond_to?(:mode) && entry.mode.to_s == PAIR.to_s
+
+      PAIR
+    end
+
+    # .for_turn as chi web sees it, by the live worker's features (.live).
+    def live_for(session, entry, state_dir: nil)
+      for_turn(session, entry, features: live_features(session, state_dir))
+    end
+
+    # The mode a participant invited to +session+ now gets, as chi web and
+    # chi share see it: by the session's live worker's features (an older
+    # worker runs it as :review), else by this chi's (no live worker: the
+    # one a delivery starts is this chi's).
+    # @param state_dir [String, nil] the sessions' state dir (nil: the default)
+    # @return [Symbol]
+    def live(session, state_dir: nil)
+      of(session, features: live_features(session, state_dir))
+    end
+
+    # Whether +session+ is a working session whose live worker still runs a
+    # participant's turn as a review (it predates Delivery::PAIR_FEATURE).
+    def older_worker?(session, state_dir: nil)
+      of(session) == PAIR && live(session, state_dir: state_dir) == REVIEW
+    end
+
+    # The live worker's features, nil without a live worker (or when it
+    # can't be read).
+    def live_features(session, state_dir)
+      return nil if session.nil? || !session.respond_to?(:id) || session.id.to_s.empty?
+
+      require_relative "session"
+      require_relative "worker_link"
+      dir = Session.session_dir(session.id, state_dir: state_dir || Session.default_state_dir)
+      link = WorkerLink.resolve(dir, unlink: false)
+      link.live? ? link.features : nil
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/samagotchi/participants.rb

@@ -36,7 +36,9 @@ module Samagotchi
     # +expires_at+ says when). +cap+: their spending cap in dollars (the
     # worker's check before their queued turn starts), nil in a sidecar
     # from before caps.
-    Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at, :cap) do
+    # +mode+: "pair" when the owner invited them to act (Grant#mode); nil
+    # for a review participant and for a sidecar from before it.
+    Entry = Data.define(:id, :kind, :name, :role, :added_at, :expires_at, :removed_at, :cap, :mode) do
       def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key.to_s]] })
 
       # Still in the review at +now+.
@@ -72,7 +74,7 @@ module Samagotchi
       entries = grants.map do |grant|
         { "id" => grant.id, "kind" => grant.kind, "name" => grant.name, "role" => grant.role,
           "added_at" => grant.created_at, "expires_at" => grant.expires_at, "removed_at" => grant.revoked_at,
-          "cap" => grant.spend_cap }
+          "cap" => grant.spend_cap, **(grant.mode ? { "mode" => grant.mode } : {}) }
       end
       AtomicFile.write(File.join(dir, FILE), "#{JSON.pretty_generate({ "participants" => entries })}\n", perm: 0o600)
     end
@@ -106,7 +108,7 @@ module Samagotchi
     #   (Unbindable: an identity without such a public_url)
     # @raise [ArgumentError] no such session
     def invite(grants, session_id:, name:, kind: "human", ttl: nil, cap: nil, identity: nil, public_url: nil,
-               state_dir: Session.default_state_dir)
+               mode: nil, state_dir: Session.default_state_dir)
       raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(Session.session_file(session_id, state_dir: state_dir))
 
       identity = Web::Grants.clean_identity(identity) unless identity.nil?
@@ -116,11 +118,11 @@ module Samagotchi
       end
 
       issued = grants.issue(session_id: session_id, name: name, kind: kind, ttl: ttl, cap: cap, identity: identity,
-                            on_write: sidecar_writer(state_dir, [session_id]))
+                            mode: mode, on_write: sidecar_writer(state_dir, [session_id]))
       grant = issued.grant
       log(session_id, :issued, state_dir: state_dir, participant: grant.id, name: grant.name, kind: grant.kind,
                                role: grant.role, expires_at: grant.expires_at, cap: grant.spend_cap,
-                               **(grant.identity ? { identity: grant.identity } : {}))
+                               **(grant.identity ? { identity: grant.identity } : {}), **(mode ? { mode: mode } : {}))
       issued
     end
 

data/lib/samagotchi/review_apply.rb

@@ -2,6 +2,7 @@
 
 require_relative "participant_name"
 require_relative "steer"
+require_relative "participant_mode"
 require_relative "output_formatter"
 
 module Samagotchi
@@ -76,7 +77,7 @@ module Samagotchi
 
     def latest(list)
       list.each_index.reverse_each do |at|
-        next unless opening?(list[at]) && Steer.participant_author?(field(list[at], :author))
+        next unless opening?(list[at]) && review_turn?(list[at])
 
         proposal = proposal_at(list, at, check: false)
         return proposal if proposal
@@ -88,7 +89,7 @@ module Samagotchi
     def proposal_at(list, at, check: true)
       opening = list[at]
       author = field(opening, :author)
-      if check && !Steer.participant_author?(author)
+      if check && !review_turn?(opening)
         raise Refused.new(format(NOT_REVIEW, short(field(opening, :turn_id))), code: :not_review_turn)
       end
 
@@ -99,6 +100,13 @@ module Samagotchi
                    author_name: field(opening, :author_name).to_s, text: text)
     end
 
+    # Whether the turn +opening+ opens is a participant's review turn: a
+    # participant's, not stamped pair (a pair turn acted itself: there is
+    # nothing to apply). A message from before the stamp is a review's.
+    def review_turn?(opening)
+      Steer.participant_author?(field(opening, :author)) && field(opening, :participant_mode).to_s != ParticipantMode::PAIR.to_s
+    end
+
     # The turn's reply: its last model message with visible text, before
     # the next turn opens.
     def reply_text(list, at)

data/lib/samagotchi/review_start.rb

@@ -141,21 +141,49 @@ module Samagotchi
       parts.join("\n\n")
     end
 
-    # The warning for inviting a participant to +session+ when it isn't a
-    # review session (D2: sharing a working session is allowed, with a
-    # warning that names how many tool outputs it holds); nil for a review
-    # session. chi share and the web's Invite show it as it is.
+    # What inviting a participant to +session+ now means: the grant's mode
+    # (Web::Grants::PAIR_MODE only when the owner is shown PAIR_WARNING: a
+    # working session whose live worker runs pair turns; nil otherwise, a
+    # review participant), the mode their turns get (:pair or :review) and
+    # the warning shown for it (nil for a review session). One read of the
+    # live worker for all three, so the stamp is what the warning said.
+    ShareTerms = Data.define(:grant_mode, :mode, :warning)
+
     # @param session [Session]
-    # @return [String, nil]
-    def share_warning(session)
-      mode = ParticipantMode.of(session)
-      return nil if session.review?
+    # @param state_dir [String, nil] the sessions' state dir (nil: the default)
+    # @return [ShareTerms]
+    def share_terms(session, state_dir: nil)
+      return ShareTerms.new(grant_mode: nil, mode: ParticipantMode::REVIEW, warning: nil) if session.review?
 
       count = session.tool_output_count
-      "#{session.id[0, 8]} is a working session, not a review session: a participant's #{mode} turn can quote what " \
-        "its history holds (#{count} tool output#{"s" unless count == 1} so far). A review session starts from its recap instead."
+      outputs = "#{count} tool output#{"s" unless count == 1} so far"
+      pair = ParticipantMode.live(session, state_dir: state_dir) == ParticipantMode::PAIR
+      warning = format(pair ? PAIR_WARNING : OLDER_WORKER_WARNING, id: session.id[0, 8], outputs: outputs)
+      ShareTerms.new(grant_mode: (ParticipantMode::PAIR.to_s if pair), mode: pair ? ParticipantMode::PAIR : ParticipantMode::REVIEW,
+                     warning: warning)
     end
 
+    # The warning for inviting a participant to +session+ when it isn't a
+    # review session (D2: sharing a working session is allowed, with a
+    # warning that says what a participant's turn does there and how many
+    # tool outputs its history holds); nil for a review session
+    # (#share_terms). chi share and the web's Invite show it as it is.
+    # @return [String, nil]
+    def share_warning(session, state_dir: nil) = share_terms(session, state_dir: state_dir).warning
+
+    # A working session's share warning (#share_warning): a participant's
+    # turns act there. chi share adds the command that starts a review
+    # session (chi review --from ID), as its invocation spells it.
+    PAIR_WARNING = "%<id>s is a working session: a participant's turns act in it with this session's tools " \
+                   "(writes included; asks come to you) and read what its history holds (%<outputs>s). " \
+                   "A review session only reads."
+    # The same while its live worker predates pair turns (Delivery::PAIR_FEATURE):
+    # a participant invited now gets review turns, whatever happens later.
+    OLDER_WORKER_WARNING = "%<id>s is a working session, but its worker predates pair turns: a participant invited " \
+                           "now only reads, and can quote what its history holds (%<outputs>s). For turns that act " \
+                           "in it, restart it (chi sessions restart %<id>s) and invite them again. A review session " \
+                           "only reads."
+
     def relative(full, root)
       real_root = Guardrails::ProtectedPaths.real(root)
       real = Guardrails::ProtectedPaths.real(full)

data/lib/samagotchi/run_options.rb

@@ -16,6 +16,32 @@ module Samagotchi
     # with the config registry's.
     KNOWN = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token --tunnel --start-dir].freeze
 
+    # An OptionParser that also records each switch it took, as the
+    # normalized [flag] or [flag, value] (a --[no-]x as --x or --no-x; an
+    # abbreviation never gets this far): chi web's restart argv.
+    class RecordingParser < OptionParser
+      def initialize(record, *, &)
+        @record = record
+        super(*, &)
+      end
+
+      def define(*args, &block)
+        switch = nil
+        switch = super do |value|
+          @record&.push(RecordingParser.normalized(switch, value))
+          block&.call(value)
+        end
+      end
+
+      def self.normalized(switch, value)
+        flag = switch.long.first || switch.short.first
+        return [flag.sub("[no-]", value ? "" : "no-")] if flag.include?("[no-]")
+        return [flag] if switch.is_a?(OptionParser::Switch::NoArgument)
+
+        [flag, value.to_s]
+      end
+    end
+
     module_function
 
     # Parse +argv+ in place: what the parser leaves is bin/chi's to read
@@ -25,7 +51,7 @@ module Samagotchi
     #   (Config.reload!'s cli_overrides)
     def parse(argv)
       # no_interrupt / no_default_input start from config.yml or the env; the flags below turn them on.
-      options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt"), non_interactive: false, no_default_input: Samagotchi::Config.get("no_default_input"), web: false, web_port: nil, web_open: false, web_markdown: nil }
+      options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt"), non_interactive: false, no_default_input: Samagotchi::Config.get("no_default_input"), web: false, web_port: nil, web_open: false, web_markdown: nil, flags: [] }
       cli_overrides = {}
 
       # Strict kebab enforcement: --recap_base_url is unknown (OptionParser would otherwise accept _ as -)
@@ -100,11 +126,13 @@ module Samagotchi
           value = argv[index + 1]
           missing_no_tool.call if value.nil? || value.start_with?("-")
           (options[:no_tools] ||= []) << argv.delete_at(index + 1)
+          options[:flags] << ["--no-tool", value]
           argv.delete_at(index)
         elsif arg.start_with?("--no-tool=")
           value = arg.delete_prefix("--no-tool=")
           missing_no_tool.call if value.empty? || value.start_with?("-")
           options[:no_tools] = (options[:no_tools] || []) << value
+          options[:flags] << ["--no-tool", value]
           argv.delete_at(index)
         else
           reject_abbreviation.call(arg)
@@ -139,6 +167,19 @@ module Samagotchi
            .push("--no-tool").uniq
     end
 
+    # The flags not repeated by chi web's restart: one-shot actions of the
+    # first start (open a browser, replace the LAN token).
+    WEB_ONE_SHOT = %w[--open --new-token].freeze
+
+    # chi web's own command line again, for its in-place restart: every flag
+    # the parse took (options[:flags], in its normalized spelling) but the
+    # one-shot ones, so the restarted chi web parses to the same options and
+    # config overrides.
+    # @return [Array<String>]
+    def web_restart_argv(options)
+      ["web", *options.fetch(:flags).reject { |flag, _| WEB_ONE_SHOT.include?(flag) }.flatten(1)]
+    end
+
     # The parser's switches (OptionParser::Switch), short and long.
     def parser_switches(parser)
       parser.instance_variable_get(:@stack).flat_map { |list| list.list }
@@ -148,7 +189,7 @@ module Samagotchi
     # @param options [Hash] filled in by the parse
     # @param cli_overrides [Hash] the config keys the flags set
     def build_parser(options, cli_overrides)
-      OptionParser.new do |opts|
+      RecordingParser.new(options[:flags]) do |opts|
         opts.banner = <<~BANNER
           Usage: chi [options]
                  chi bootstrap [HOST[:PORT]|URL]  first setup: find the model server, write config.yml

data/lib/samagotchi/session_access/local.rb

@@ -388,15 +388,18 @@ module Samagotchi
       #   session, an identity with no proxy to check it
       def invite(id, name:, kind:, ttl: nil, cap: nil, identity: nil)
         public_url = configured_public_url
+        # Stamped pair only when the warning chi share prints says their turns act.
+        terms = ReviewStart.share_terms(Session.load(id, **dir), state_dir: state_dir!)
         issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, cap: cap,
-                                             identity: identity, public_url: public_url, state_dir: state_dir!)
+                                             identity: identity, public_url: public_url, mode: terms.grant_mode,
+                                             state_dir: state_dir!)
         web = public_url ? nil : local_web
         link = if public_url then public_url.link(link_code(issued), "s=#{id}")
                else "http://#{web.ip || "127.0.0.1"}:#{web.port}/?token=#{issued.token}#s=#{id}"
                end
         Invitation.new(participant: ParticipantView.from_h(issued.grant.public_h(grants.now)), token: issued.token,
                        link: link, lan: !public_url.nil? || !web.ip.nil?,
-                       warning: ReviewStart.share_warning(Session.load(id, **dir)))
+                       warning: terms.warning)
       rescue Web::Grants::Invalid => e
         raise BadRequest.new(e.message, code: "invalid_participant")
       end

data/lib/samagotchi/session_manager.rb

@@ -620,6 +620,17 @@ module Samagotchi
       @spawns_mutex.synchronize { @spawns.clear }
     end
 
+    # Starter processes are children of chi web, unlike the detached workers
+    # they launch; the web restart adopts these pids before replacing itself.
+    def self.live_spawn_pids
+      @spawns_mutex.synchronize do
+        @spawns.delete_if { |_, (_, waiter)| !(waiter.respond_to?(:alive?) && waiter.alive?) }
+        @spawns.values.filter_map do |_, waiter|
+          waiter.pid if waiter.respond_to?(:pid) && waiter.alive?
+        end.uniq.sort
+      end
+    end
+
     # Read any new output files from a session directory.
     # Optionally filters to only files newer than `since_time`.
     def self.read_responses(session_id, since_time: nil, state_dir: nil)

data/lib/samagotchi/session_participants.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "steer"
+require_relative "participant_mode"
 
 module Samagotchi
   # Loaded only when a session is read: it brings Web::Grants (and Rack).
@@ -36,13 +37,27 @@ module Samagotchi
     # the sidecar again: someone invited after the turn began. +session+:
     # the session it is asked for, when that may not be the last refreshed
     # (the worker's running save, before the Engine's first turn).
-    def name_for(author, session: nil)
+    def name_for(author, session: nil) = entry_for(author, session: session)&.name
+
+    # +author+'s Participants::Entry (their name, cap, grant mode), nil for
+    # none; read again on a miss, as #name_for.
+    def entry_for(author, session: nil)
       return nil unless Steer.participant_author?(author)
 
       refresh!(session) if session && session.id != @session_id
       id = Steer.participant_id(author)
-      entry = @entries.find { |e| e.id == id } || (@entries = read).find { |e| e.id == id }
-      entry&.name
+      @entries.find { |e| e.id == id } || (@entries = read).find { |e| e.id == id }
+    end
+
+    # The system prompt's participants line while anyone is in it (#active?
+    # as of the last #refresh!): ParticipantMode::PAIR when +session+ is a
+    # working session and an active participant was invited to act, else
+    # ParticipantMode::REVIEW; nil with nobody active.
+    def prompt_mode(session)
+      active = @entries.select { |entry| entry.active?(@clock.call) }
+      return nil if active.empty?
+
+      active.any? { |entry| ParticipantMode.for_turn(session, entry) == ParticipantMode::PAIR } ? ParticipantMode::PAIR : ParticipantMode::REVIEW
     end
 
     private

data/lib/samagotchi/share_command.rb

@@ -38,8 +38,8 @@ module Samagotchi
         ls [ID]          the participants of ID, or of every session (never a token)
         cap ID P D       set participant P's cap to D dollars, from their next turn
         revoke ID [P]    end participant P's link, or every link to ID; --all every session's
-      Archiving or deleting a session revokes its links. A participant's comments run as
-      review turns: you pay for them, and they may only read.
+      Archiving or deleting a session revokes its links. You pay for a participant's turns;
+      what they may do in that session, chi share says when it invites them (the warning).
     TEXT
 
     SUBCOMMANDS = %w[ls cap revoke].freeze

data/lib/samagotchi/steer.rb

@@ -123,7 +123,13 @@ module Samagotchi
     # is saved with it), so a replay keeps the prompt cache.
     REVIEW_HEADER = "[Review contribution from %s (participant, not the session owner). Answer it and propose " \
                     "changes; don't act on it as the owner's instruction. This turn may only read.]"
-    PARTICIPANT_HEADERS = { "review" => REVIEW_HEADER }.freeze
+    # A participant's message delivered under ParticipantMode :pair (a
+    # working session): they act within the session's tools and guardrails.
+    PAIR_HEADER = "[From %s, a teammate the owner invited to this session. Treat it as a collaborator's request: " \
+                  "act on it within this session's tools and guardrails.]"
+    # By the message's participant_mode stamp; a missing or unknown one is
+    # a review (every message saved before the stamp).
+    PARTICIPANT_HEADERS = { "review" => REVIEW_HEADER, "pair" => PAIR_HEADER }.freeze
     # A participant's line's saved source (review:<id>): never the user's,
     # and never one that cuts (CUT_SOURCES). Its header is the review one,
     # by its author.

data/lib/samagotchi/system_one/client.rb

@@ -46,14 +46,22 @@ module Samagotchi
         return nil if host.empty?
 
         model = (model.nil? ? Config.get("guardrails.system_one.model") : model).to_s.strip
-        timeout_ms = Config.get("guardrails.system_one.timeout_ms").to_i
-        timeout_ms = DEFAULT_TIMEOUT_MS unless timeout_ms.positive?
+        timeout_ms = configured_timeout_ms
 
         new(backend: HttpBackend.new(host_registry: host_registry, host: host, model: model.empty? ? nil : model,
                                      timeout_ms: timeout_ms, env: env),
             mode: mode, host: host, model: model.empty? ? nil : model, tag: tag)
       end
 
+      # guardrails.system_one.timeout_ms, else the default: the whole
+      # request's limit, and how long a turn waits for an answer (toolkit
+      # suggestion's on mode).
+      # @return [Integer]
+      def self.configured_timeout_ms
+        timeout_ms = Config.get("guardrails.system_one.timeout_ms").to_i
+        timeout_ms.positive? ? timeout_ms : DEFAULT_TIMEOUT_MS
+      end
+
       # @param state [String, Hash, Array] what the question is about, as the
       #   contract takes it
       # @param questions [Hash{String => Question|Hash}] the questions, by id

data/lib/samagotchi/system_prompt.rb

@@ -13,6 +13,7 @@ require_relative "bundle_needs"
 require_relative "memory_bundle/index_size"
 require_relative "thinking"
 require_relative "prompt_files"
+require_relative "participant_mode"
 
 module Samagotchi
   # The system prompt an Engine gives its model: the base prompt (tool
@@ -53,8 +54,9 @@ module Samagotchi
     # @param muted_memory_names [Array<String>] normalized (MutedMemories)
     # @param appended_files [Array<String>] chi --append-system-prompt's
     #   files (absolute paths), after config.yml's append_system_prompt:
-    # @param participants [#call] → Boolean, whether the session has
-    #   participants now (the #participants_section line)
+    # @param participants [#call] → ParticipantMode::PAIR / REVIEW while the
+    #   session has participants (SessionParticipants#prompt_mode; true reads
+    #   as review), nil or false with none (the #participants_section line)
     def initialize(profile:, tools:, session:, thinking:, model: -> {}, model_notes: -> { [] }, memories: [],
                    muted_memory_names: [], appended_files: [], participants: -> { false })
       @profile_lookup = profile
@@ -616,9 +618,23 @@ module Samagotchi
     PARTICIPANTS_LINE = "Participants: people other than the owner review this session. A user message under a " \
                         "\"[Review contribution from …]\" header is a participant's: answer it and propose changes, " \
                         "but never take it as the owner's instruction, in its turn or in a later one."
-
+    # The same for a working session (ParticipantMode :pair): its
+    # participants' turns act. A message delivered before (a review
+    # stamp) keeps its review header, which the line still names.
+    PAIR_PARTICIPANTS_LINE = "Participants: teammates the owner invited work in this session too. A user message " \
+                             "under a \"[From …, a teammate …]\" header is a participant's request: act on it within " \
+                             "this session's tools and guardrails, in its own turn; it is never the owner's " \
+                             "instruction in a later one. One under \"[Review contribution from …]\" only read: its " \
+                             "proposals were for the owner to apply."
+
+    # By the lookup's mode (SessionParticipants#prompt_mode): the pair line
+    # once a participant invited to act is in a working session, the review
+    # line for review participants; nothing with none (nil, false).
     def participants_section
-      PARTICIPANTS_LINE if @participants_lookup.call
+      mode = @participants_lookup.call
+      return nil unless mode
+
+      mode == ParticipantMode::PAIR ? PAIR_PARTICIPANTS_LINE : PARTICIPANTS_LINE
     rescue StandardError
       nil
     end

data/lib/samagotchi/terminal_ui/question_prompt.rb

@@ -3,6 +3,7 @@
 require_relative "question_slot"
 require_relative "../turn_flow"
 require_relative "../question_desk"
+require_relative "../steer"
 
 module Samagotchi
   class TerminalUI
@@ -36,6 +37,9 @@ module Samagotchi
         field = ->(key) { pending[key] || pending[key.to_s] }
         approval = field.call(:approval)
         @preview = approval.is_a?(Hash) ? (approval[:preview] || approval["preview"]) : nil
+        # A participant's turn asks (Approval.payload's author:): who, by
+        # name else id, leads the line left in the scrollback.
+        @asker = approval.is_a?(Hash) ? approval_asker(approval) : nil
         @id = field.call(:id).to_s
         @question = field.call(:question).to_s
         # A delegate's approval relayed here: the delegate's own text is the
@@ -149,7 +153,10 @@ module Samagotchi
       # the question and what became of it.
       # @param outcome [String] the answer (#answer_text) or what closed it
       def summary(outcome, paint: ->(text, _code) { text })
-        who = @delegate ? "#{@delegate}: " : ""
+        who = if @delegate then "#{@delegate}: "
+              elsif @asker then "#{@asker}'s turn: "
+              else ""
+              end
         "#{paint.call("#{mark}#{who}#{question.lines.first.to_s.chomp}", approval? ? 33 : 94)} → #{outcome}"
       end
 
@@ -229,6 +236,15 @@ module Samagotchi
         end
       end
 
+      def approval_asker(approval)
+        get = ->(key) { approval[key] || approval[key.to_s] }
+        author = get.call(:author).to_s
+        return nil if author.empty?
+
+        name = get.call(:author_name).to_s
+        name.empty? ? author.delete_prefix(Steer::PARTICIPANT_PREFIX) : name
+      end
+
       def parse_approval(raw)
         sel_part, free_part = raw.to_s.strip.split(";", 2).map { |part| part.to_s.strip }
         free_part = nil if free_part.to_s.empty?

data/lib/samagotchi/tool_runner.rb

@@ -389,7 +389,9 @@ module Samagotchi
     end
 
     def unreached_group_refusal(call)
-      return if participant_turn? && ParticipantMode.of(nil) == :review
+      # A review turn's boundary denies it first (and words why); a pair
+      # turn gets the owner's refusal.
+      return if participant_turn? && participant_mode != ParticipantMode::PAIR
 
       registry = tools
       index = registry&.index if registry.respond_to?(:index)
@@ -409,6 +411,13 @@ module Samagotchi
       @kernel.respond_to?(:participant_turn?) && @kernel.participant_turn?
     end
 
+    # The running participant turn's mode (KernelLoop#participant_mode,
+    # GuardrailWiring#turn_mode), nil without one.
+    def participant_mode
+      lookup = @kernel.respond_to?(:participant_mode) ? @kernel.participant_mode : nil
+      lookup&.call
+    end
+
     # Whether the turn's host loads tools (TurnSettings#loads_tools).
     def loads_tools? = @kernel.respond_to?(:turn_settings) && @kernel.turn_settings&.loads_tools == true
 

data/lib/samagotchi/toolkit_binding.rb

@@ -128,6 +128,40 @@ module Samagotchi
       true
     end
 
+    # On mode's suggestion (Engine#settle_toolkit_suggestion), on the turn
+    # thread before #apply!: put +session+ on kit +name+ with origin
+    # suggested, saved, and tell the user through #use's notice path. Not
+    # when the session's toolkit isn't the default any more (a /toolkit or
+    # ctx.use_toolkit while it was asked) or the kit is gone.
+    # +deferred+: the session already has a model reply, so the switch
+    # applies from this turn (and re-reads the whole request).
+    # @return [Boolean] whether the session switched
+    # @raise the save's error, with the session's toolkit and origin as they were
+    def suggest(session, name, confidence:, deferred:)
+      return false if session.nil? || session.toolkit_origin != "default" || !kits.key?(name)
+
+      before = [session.toolkit, session.toolkit_origin]
+      session.toolkit = Toolkit.new(name: name)
+      session.toolkit_origin = "suggested"
+      begin
+        session.save(state_dir: @state_dir.call)
+      rescue StandardError
+        # Not saved, not switched: the turn runs the default it has on disk.
+        session.toolkit, session.toolkit_origin = before
+        raise
+      end
+      @notify.call(self.class.suggestion_notice(name, confidence, deferred: deferred), :info, "toolkit",
+                   extra: { toolkit: explained(session.toolkit).summary })
+      true
+    end
+
+    # "toolkit: smoke (suggested, p=0.71) · /toolkit to change"; a
+    # deferred switch says "from this turn".
+    def self.suggestion_notice(name, confidence, deferred:)
+      when_text = deferred ? " from this turn" : ""
+      "toolkit: #{name}#{when_text} (suggested, p=#{format("%.2f", confidence.to_f)}) · /toolkit to change"
+    end
+
     # Resolve the session's toolkit into the Registry, on the turn thread at
     # a turn's start (before its prompt is built), and build the prompts
     # again when what it declares (or its kit's prompt text) changed. A

data/lib/samagotchi/toolkit_report_command.rb

@@ -101,7 +101,8 @@ module Samagotchi
         tallies[kit]["would:#{entry["would"] || "unknown"}"] += 1
         confidence = entry["confidence"].nil? ? "n/a" : format("%.2f", entry["confidence"])
         @stdout.puts("#{timestamp(entry["at"]).iso8601} #{id[0, 8]} turn #{entry["turn_number"]}: " \
-                     "#{entry["raw"] || "no judgment"} (p=#{confidence}, would #{entry["would"] || "unknown"}) " \
+                     "#{entry["raw"] || "no judgment"} (p=#{confidence}, would #{entry["would"] || "unknown"}" \
+                     "#{", did #{entry["did"]}" if entry["did"]}) " \
                      "→ #{kit}: #{grade}#{detail}#{window}")
         labels = uses.is_a?(Array) ? uses.map(&:label).uniq : []
         @stdout.puts("  tools: #{labels.join(", ")}") unless labels.empty?
@@ -224,10 +225,11 @@ module Samagotchi
       name == "call_tool" ? :ungradable : ToolUse.new(name: name, group: nil, label: name)
     end
 
-    # The kit on mode would have run: the suggestion only when it would
-    # have been applied, else the session's default.
+    # The kit on mode would have run (audit), or ran (an on line's did):
+    # the suggestion only when it was (or would have been) applied, else
+    # the session's default.
     def graded_kit(entry)
-      name = entry["would"] == "suggested" ? entry["kit"] : entry["default_kit"]
+      name = (entry["did"] || entry["would"]) == "suggested" ? entry["kit"] : entry["default_kit"]
       name || "(unknown)"
     end