samagotchi 0.121.1 → 0.123.0

data/lib/samagotchi/guardrails/review_paths.rb

@@ -14,8 +14,19 @@ module Samagotchi
     # 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
+      # Home folders that hold keys and tokens, never read in a review turn
+      # (nor read or written in a pair turn).
+      # A pair turn neither reads nor writes these either: the shell's and
+      # git's config folders, the user's launch agents and ~/.local/bin (what
+      # runs at login or comes first on PATH).
+      HOME_SECRET_DIRS = %w[.ssh .gnupg .aws .config/gh .config/fish .config/git Library/LaunchAgents .local/bin].freeze
+      # Home files that start a shell, hold credentials or keep what was
+      # typed: a pair turn neither reads nor writes them (a review turn reads
+      # only inside the project anyway).
+      HOME_SECRET_FILES = %w[.zshrc .zshenv .zprofile .zlogin .bashrc .bash_profile .bash_login .profile .gitconfig
+                             .netrc .npmrc .pypirc .claude.json .zsh_history .bash_history .history .python_history
+                             .node_repl_history .psql_history .mysql_history .irb_history .lesshst
+                             .local/share/fish/fish_history].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
@@ -67,13 +78,34 @@ module Samagotchi
         nil
       end
 
-      private
+      # SECRET when one of +paths+ is on the read denylist (as given or as
+      # it resolves), wherever it is; nil otherwise. A pair turn's check
+      # (PairBoundary): it reads outside the project too, never these.
+      # @param paths [Array<String>] absolute, or relative to the cwd
+      # @return [Symbol, nil]
+      def secret_refusal(paths)
+        paths.each do |path|
+          given = File.expand_path(path)
+          return SECRET if secret?(given) || secret?(ProtectedPaths.real(given))
+        end
+        nil
+      end
+
+      # The denylist's dirs and home files, absolute (as given and as they
+      # resolve): a pair turn's command check asks whether a word it can't
+      # resolve (a glob, a $var) may lead into one.
+      # @return [Array<String>]
+      def denied_roots
+        @denied_roots ||= begin
+          roots = @denied_dirs.compact.map { |dir| File.expand_path(dir) }
+          roots += (HOME_SECRET_DIRS + HOME_SECRET_FILES).map { |name| File.join(@home, name) } unless @home.empty?
+          (roots + roots.map { |root| ProtectedPaths.real(root) }).uniq
+        end
+      end
 
+      # Whether +path+ (absolute) is on the read denylist.
       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) }
+        return true if denied_roots.any? { |root| ShellPaths.within?(path, root) }
 
         parts = path.split(File::SEPARATOR)
         return true if parts.any? { |part| SECRET_FILE.match?(part) }
@@ -82,6 +114,8 @@ module Samagotchi
         git_config?(parts)
       end
 
+      private
+
       # A config file anywhere under a .git dir (.git/config,
       # .git/modules/<sub>/config, a worktree's config.worktree).
       def git_config?(parts)

data/lib/samagotchi/guardrails/shell_lex.rb

@@ -87,8 +87,10 @@ module Samagotchi
       # as data (DataReaders) cut out, the <<TAG word and the terminator line
       # kept as written. This is what a rule's command: reads. A text the
       # lexer isn't sure of (unterminated) comes back as it was, and so does
-      # one it can't read: the safe default.
-      def self.code_text(text)
+      # one it can't read: the safe default. +keep_written+ false cuts every
+      # data body, a cat or tee writing it to a file too (a pair turn's check:
+      # text written to a file is data; where it goes is checked apart).
+      def self.code_text(text, keep_written: true)
         lexer = Lexer.new(text)
         tokens = lexer.tokens
         return text if lexer.unterminated?
@@ -104,7 +106,7 @@ module Samagotchi
 
             span = lexer.spans[i]
             cut = if bodies.include?(span)
-                    body_cut(text, span, words, redirected) if value == HEREDOC
+                    body_cut(text, span, words, redirected, keep_written) if value == HEREDOC
                   elsif value == SUBST
                     substitution_cut(text, tokens, i, span, words, position)
                   end
@@ -139,8 +141,8 @@ module Samagotchi
       # cat or tee writing a file may be run later (D1), and so may one
       # printing after an earlier exec sent the shell's output to a file
       # (+redirected+).
-      def self.body_cut(text, span, words, redirected)
-        return nil unless cut_body?(words, redirected)
+      def self.body_cut(text, span, words, redirected, keep_written = true)
+        return nil if keep_written && !cut_body?(words, redirected)
 
         [span, terminator_line(text[span])]
       end

data/lib/samagotchi/guardrails/shell_paths.rb

@@ -41,13 +41,22 @@ module Samagotchi
       # @param tmp_roots [Array<String>] where a .git/hooks part doesn't count
       def touches?(command, dirs:, text:, cwd:, home: Dir.home, env: ENV, tmp_roots: [])
         roots = dirs.compact.map { |dir| ProtectedPaths.real(dir.to_s.chomp("/")) }.reject(&:empty?).uniq
+        any_path?(command, text: text, cwd: cwd, home: home, env: env) { |path| names?(path, roots, tmp_roots) }
+      end
+
+      # Whether a word of +command+ names a path the block holds for (each
+      # word resolved as #touches? resolves it); a word that can't be
+      # resolved, a command with a $(…) or backticks, or one that doesn't
+      # lex, by the text match +text+ instead.
+      # @yieldparam path [String] an absolute path (not resolved for symlinks)
+      def any_path?(command, text:, cwd:, home: Dir.home, env: ENV)
         walk = Walk.new(cwd, home, env)
         tokens = ShellLex.lex(command.to_s)
         code = ShellLex.code_text(command.to_s)
         return true if tokens.any? { |_, value| value.include?(ShellLex::SUBST) } && code.match?(text)
 
         ShellLex.simple_commands(tokens).any? do |words|
-          walk.step(words).any? { |word, path| path ? names?(path, roots, tmp_roots) : word.match?(text) }
+          walk.step(words).any? { |word, path| path ? yield(path) : word.match?(text) }
         end
       rescue ArgumentError, EncodingError
         command.to_s.scrub.match?(text)

data/lib/samagotchi/guardrails/verdict.rb

@@ -38,6 +38,13 @@ module Samagotchi
       # System 1's judgment that decided an ask, when it did: {id:, p:}.
       attr_accessor :judgment
 
+      # An ask no stored approval answers (Gate#settle_ask): the one a
+      # participant's pair turn gets before a write outside the project
+      # (PairBoundary), which the owner decides each time.
+      attr_writer :fresh_ask
+
+      def fresh_ask? = @fresh_ask == true
+
       def initialize(call:)
         @call = call
         @decision = :allow

data/lib/samagotchi/guardrails.rb

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

data/lib/samagotchi/guardrails_command.rb

@@ -66,6 +66,7 @@ module Samagotchi
       parent_cannot_allow: "answered by a parent that could not allow",
       unanswered: "unanswered",
       no_approval: "no approval card",
+      participant: "asked by a participant's turn",
       no_question_id: "no question id"
     }.freeze
 
@@ -200,13 +201,17 @@ module Samagotchi
 
     # One card entry as an ask to judge: an Ask, a skip reason (:already_replayed,
     # :judged_live, :answered_by_parent, :parent_cannot_allow, :unanswered,
-    # :no_approval, :no_question_id), or nil for an entry that is not a
+    # :no_approval, :participant, :no_question_id), or nil for an entry that is not a
     # question at all.
     def ask_of(entry, session_id, judged, sessions_dir)
       return nil unless entry.is_a?(Hash) && entry[:type] == "question"
 
       pending = entry[:pending_question]
       return :no_approval unless pending.is_a?(Hash) && pending[:approval].is_a?(Hash)
+      # A participant's turn's ask is never System 1's to judge, live or here
+      # (GuardrailWiring#system_one_judge): no record of it is the user's
+      # rule-level decision (it offered once only).
+      return :participant if pending[:approval][:author]
 
       question_id = pending[:id].to_s
       return :no_question_id if question_id.empty?

data/lib/samagotchi/kernel_loop.rb

@@ -67,6 +67,10 @@ module Samagotchi
 
       def reminder_store = @kernel.reminder_store
       def peers = @kernel.peers
+
+      # The running participant turn's mode (KernelLoop#participant_mode:
+      # :pair, :review), nil for the owner's turns.
+      def participant_mode = @kernel.participant_mode&.call
       def model_key = @kernel.model_key
 
       # memory_read with the session's mutes applied: a blank name (the index)
@@ -179,6 +183,21 @@ module Samagotchi
     # Whether the current turn belongs to a participant, so pre-gate
     # refusals can defer to ReviewBoundary.
     attr_accessor :participant_turn
+    # The running participant turn's mode (a callable → :pair, :review or
+    # nil: GuardrailWiring#turn_mode): ToolRunner reads it. The Engine sets it.
+    attr_accessor :participant_mode
+    # Called before each generation, before the before_generation hook (a
+    # callable, nil: none): the Engine's check that may stop the turn (a
+    # pair turn past its participant's cap, Engine#guard_participant_spend).
+    attr_accessor :generation_guard
+
+    # The generation guard, if any; one that raises never breaks the turn.
+    def guard_generation
+      @generation_guard&.call
+    rescue StandardError => e
+      Log.warn(:turn, "generation_guard_failed", error: "#{e.class}: #{e.message}")
+      nil
+    end
 
     def participant_turn? = @participant_turn&.call == true
     # @return [LLM::TurnSettings] the turn's vision, sampling, thinking and
@@ -426,6 +445,7 @@ module Samagotchi
     def generate(turn, request)
       # Before the generation starts: a hook that waits (a question) isn't
       # the generation's time, and a Stop there leaves none started.
+      guard_generation
       fire_hook(:before_generation, { type: :before_generation, iteration: turn.iteration }) if @hooks
       raise Client::RequestCancelled, turn.cancel_controller.reason if turn.cancel_controller&.cancelled?
 

data/lib/samagotchi/llm/chat_loop.rb

@@ -389,6 +389,9 @@ module Samagotchi
         nil
       end
 
+      # The kernel's generation guard (KernelLoop#guard_generation).
+      def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation : nil
+
       # A hook failing must not break the turn (as in ToolRunner).
       def fire_hook(name, event)
         @kernel.hooks&.fire(name, event)
@@ -727,6 +730,7 @@ module Samagotchi
           observe_context(iteration, window)
           # Before the generation starts: a hook that waits (a question)
           # isn't the generation's time, and a Stop there leaves none started.
+          @loop.guard_generation
           @loop.fire_hook(:before_generation, { type: :before_generation, iteration: iteration })
           return [@cancel_controller.reason, "", ""] if @cancel_controller&.cancelled?
 

data/lib/samagotchi/log_line.rb

@@ -16,7 +16,7 @@ module Samagotchi
   # (debug dumps) are indented by four spaces and belong to the record above.
   module LogLine
     LEVELS = %w[DEBUG INFO WARN ERROR].freeze
-    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context broadcast].freeze
+    TAGS = %w[turn http worker bridge web attached repl idle recap hooks plugins guardrails config memory model context broadcast toolkit].freeze
     INDENT = "    "
 
     Record = Struct.new(:ts, :level, :tag, :pid, :sid, :event, :fields, :payload, keyword_init: true)

data/lib/samagotchi/memory_orphans.rb

@@ -51,6 +51,17 @@ module Samagotchi
       found && text(found)
     end
 
+    # A model-facing hint: report the name collision without giving the model
+    # a command that could move another live clone's memories.
+    def model_message(env: ENV, cwd: Dir.pwd)
+      found = find(env: env, cwd: cwd)
+      return unless found
+
+      name = File.basename(found.computed).sub(/_\h{8}\z/, "")
+      "a folder with the same project name (#{name}) exists with another path's hash; ask the user whether its " \
+        "memories belong to this project before using them."
+    end
+
     def text(found)
       computed = found.computed
       lead = "no project memories in #{computed}"

data/lib/samagotchi/participant_mode.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "delivery"
+
+module Samagotchi
+  # 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
+
+    # @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/plugin/api.rb

@@ -312,17 +312,20 @@ module Samagotchi
       # a bundle has) with +add+ declared and +remove+ left out, and
       # +prompt+: text the sessions on it get in their system prompt (nil:
       #   its base's, "" none; at most Toolkit::PROMPT_MAX characters);
-      #   +groups+: MCP source group names/globs (nil inherits its base).
+      #   +groups+: MCP source group names/globs (nil inherits its base);
+      #   +description+: optional classifier text, not included in prompts
+      #   (at most Toolkit::DESCRIPTION_MAX characters).
       #   A
       # name chi (full, lean, child) or another bundle has is a load error,
       # and so is a prompt that isn't text or is too long; a base that
       # doesn't resolve leaves the sessions on it with every tool
       # (Toolkit#resolve).
-      def toolkit(name, base:, add: [], remove: [], prompt: nil, groups: nil)
+      def toolkit(name, base:, add: [], remove: [], prompt: nil, groups: nil, description: nil)
         name = name.to_s
         raise ArgumentError, "toolkit name #{name.inspect} must be a-z, 0-9, _ and -" unless name.match?(TOOLKIT_NAME)
 
-        problem = Toolkit.prompt_error(prompt) || (Toolkit.groups_error(groups) unless groups == :all)
+        problem = Toolkit.prompt_error(prompt) || Toolkit.description_error(description) ||
+                  (Toolkit.groups_error(groups) unless groups == :all)
         raise ArgumentError, "toolkit #{name}: #{problem}" if problem
         raise ArgumentError, "this chi has no toolkits (plugins: false)" unless @registries.toolkits
         if Toolkit::BUILTIN_KITS.key?(name)
@@ -333,7 +336,7 @@ module Samagotchi
         raise ArgumentError, "toolkit #{name} is declared twice" if @toolkits.any? { |kit| kit.name == name }
 
         @toolkits << Toolkit::Kit.new(name: name, base: base, add: add, remove: remove, prompt: prompt,
-                                      groups: groups, source: @bundle)
+                                      groups: groups, source: @bundle, description: description)
         nil
       end
 

data/lib/samagotchi/process_group.rb

@@ -87,6 +87,19 @@ module Samagotchi
       nil
     end
 
+    # Whether +pid+ is stopped (SIGSTOP, Ctrl-Z; t: under a tracer): ps's
+    # state starts with T or t on macOS and Linux alike. Such a process
+    # takes no signal but KILL and answers no socket until it is continued.
+    # false when it isn't running or ps can't say.
+    def stopped?(pid)
+      return false unless signalable?(pid)
+
+      out, status = Open3.capture2("ps", "-o", "state=", "-p", pid.to_s, err: File::NULL)
+      status.success? && out.lstrip.start_with?("T", "t")
+    rescue SystemCallError, IOError
+      false
+    end
+
     # Field 22 (starttime); the command name (field 2) may hold spaces and
     # parentheses, so the fields are counted after its last ")".
     def proc_start_time(stat) = stat[/\A.*\)\s(.*)\z/m, 1]&.split&.[](19)

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

@@ -7,6 +7,7 @@ require_relative "session_chain"
 require_relative "recap_store"
 require_relative "guardrails/context"
 require_relative "guardrails/review_paths"
+require_relative "participant_mode"
 
 module Samagotchi
   autoload :SessionManager, File.expand_path("session_manager", __dir__)
@@ -75,6 +76,7 @@ module Samagotchi
       subjects = check_subjects(subjects, dir: dir)
       raise Refused, NO_SUBJECTS if subjects.empty?
 
+      setup = setup.with(toolkit_origin: "chosen")
       SessionManager.spawn_session(prompt: nil, preview: preview(subjects), working_directory: dir, model_name: model,
                                    setup: setup, review: SessionReview.new(subjects: subjects),
                                    note: note(subjects: subjects), note_source: NOTE_SOURCE, state_dir: state_dir)
@@ -103,7 +105,8 @@ module Samagotchi
       recap = RecapStore.read(Session.session_dir(source.id, state_dir: sd))
       session = SessionManager.spawn_session(
         prompt: nil, preview: preview(subjects, source: source), working_directory: dir, model_name: choice.model,
-        setup: SessionSetup.of(source), review: SessionReview.new(subjects: subjects, from: source.id),
+        setup: SessionSetup.of(source).with(toolkit_origin: "chosen"),
+        review: SessionReview.new(subjects: subjects, from: source.id),
         note: note(subjects: subjects, source: source, recap: recap, seed: seed), note_source: NOTE_SOURCE, state_dir: sd
       )
       warnings = [choice.warning, session.model_warning].compact
@@ -138,20 +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)
-      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 review 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

@@ -166,6 +166,7 @@ module Samagotchi
                  chi memory <ls|rm> [--scope project|system]   the memories; rm moves one to the bundle trash
                  chi bundle <install|upgrade|uninstall|status|diff|list|build|trash|new|test|check|try>
                  chi guardrails replay [--dry-run] [--threshold T] [--model M]   seed System 1's record from answered approvals
+                 chi toolkit report [--days N]   grade toolkit suggestions against the tools sessions used
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME

data/lib/samagotchi/session.rb

@@ -32,6 +32,7 @@ module Samagotchi
     STATUS_RUNNING = "running"
     STATUS_ERROR = "error"
     STATUS_STOPPED = "stopped"
+    TOOLKIT_ORIGINS = %w[chosen default inherited suggested].freeze
 
     # A stopped session's marker, <session dir>/stopped: a stop (chi
     # sessions stop, from another process) creates it instead of rewriting
@@ -222,6 +223,15 @@ module Samagotchi
       @toolkit = value.is_a?(Toolkit) ? value : Toolkit.from_file(value)
     end
 
+    # Why this session is on its toolkit. Files from before the field read
+    # as chosen, so an old default session is never newly suggested.
+    attr_reader :toolkit_origin
+
+    def toolkit_origin=(value)
+      origin = value.to_s
+      @toolkit_origin = TOOLKIT_ORIGINS.include?(origin) ? origin : "chosen"
+    end
+
     # The session's own settings (chi --set), a SessionConfig::Settings:
     # empty for none and for a session from before them. Its core part
     # ({key => value}: recap.enabled) is the file's config_settings, its
@@ -322,7 +332,7 @@ module Samagotchi
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   toolkit: nil, settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
+                   toolkit: nil, toolkit_origin: "chosen", settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
                    working_set_pins: [], review: nil)
       @id = id
       @metadata_version = metadata_version
@@ -355,6 +365,7 @@ module Samagotchi
       self.reasoning_history = reasoning_history
       self.appended_prompt_files = appended_prompt_files
       self.toolkit = toolkit
+      self.toolkit_origin = toolkit_origin
       self.settings = settings
       self.parent_answers = parent_answers
       self.working_set_pins = working_set_pins
@@ -464,6 +475,7 @@ module Samagotchi
         reasoning_history: setup.reasoning_history,
         appended_prompt_files: setup.appended_prompt_files,
         toolkit: setup.toolkit,
+        toolkit_origin: setup.toolkit_origin || "chosen",
         settings: setup.settings,
         parent_answers: setup.parent_answers,
         working_set_pins: setup.working_set_pins,
@@ -534,6 +546,7 @@ module Samagotchi
       "reasoning_history" => nil,
       "appended_prompt_files" => [],
       "toolkit" => nil,
+      "toolkit_origin" => "chosen",
       "bundle_settings" => {},
       "config_settings" => {},
       "interrupted_turn" => nil,