samagotchi 0.119.0 → 0.121.0

data/lib/samagotchi/review_command.rb

@@ -110,7 +110,9 @@ module Samagotchi
       @stdout.puts("#{id}  #{what}#{subjects} · idle")
       @stdout.puts("warning: #{created.model_warning}") if created.model_warning
       @stdout.puts("open it: #{@access.invocation.open_it(id[0, 8])}")
-      @stdout.puts("invite someone: #{@access.invocation.command("share #{id[0, 8]} --name NAME")}")
+      # Behind a proxy that names the user, a link can be bound to them.
+      identity = " --identity EMAIL" if @access.identity_header
+      @stdout.puts("invite someone: #{@access.invocation.command("share #{id[0, 8]} --name NAME#{identity}")}")
     end
 
     def refused(message)

data/lib/samagotchi/run_options.rb

@@ -14,7 +14,7 @@ module Samagotchi
   module RunOptions
     # The flags an underscored spelling is refused for (--recap_base_url),
     # 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].freeze
+    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
 
     module_function
 
@@ -223,6 +223,8 @@ module Samagotchi
         opts.on("--tunnel PROVIDER", %w[tailscale],
                 "`chi web`: reach it over https from your tailnet through Tailscale Serve (never Funnel), for this run; " \
                 "turned off on exit") { |v| options[:tunnel] = v }
+        opts.on("--start-dir DIR", "`chi web`: the folder it starts in (web.start_dir; default: this one): its page opens on that " \
+                                   "folder's project, and a new session from the all view starts there") { |v| options[:start_dir] = v }
         opts.on("--scope VALUE", %w[project all],
                 "Which sessions `chi web` and `chi sessions list` show: project (the default: this folder's git project; " \
                 "every session outside a repo) or all") { |v| options[:scope] = v }

data/lib/samagotchi/session_access/contract.rb

@@ -123,6 +123,9 @@ module Samagotchi
         "share --agent" => SUPPORTED,
         "share --expires" => SUPPORTED,
         "share --cap" => SUPPORTED,
+        # A chi web without bound grants (Remote#invite checks its
+        # bound_grants feature) is refused, never sent the identity.
+        "share --identity" => SUPPORTED,
         "share cap" => SUPPORTED,
         "share ls" => SUPPORTED,
         "share ls --format" => SUPPORTED,
@@ -150,7 +153,7 @@ module Samagotchi
                         --llm-context-budget --toolkit --tool --no-tool --set --parent-answers --no-interrupt
                         --no-default-input --dir --version -h --help],
         LOCAL_ONLY => %w[--no-shared --non-interactive -v --verbose --append-system-prompt --memory --mute --profile
-                         --port --open --new-token --tunnel --scope --web-markdown --no-web-markdown]
+                         --port --open --new-token --tunnel --start-dir --scope --web-markdown --no-web-markdown]
       }.freeze
       # A short run flag's name in a refusal.
       RUN_WORDS = { "-v" => "--verbose" }.freeze

data/lib/samagotchi/session_access/local.rb

@@ -370,12 +370,16 @@ module Samagotchi
       # and port when one runs on the LAN (the port it recorded, else
       # web.port), else 127.0.0.1 (+lan+ false: the link opens on this
       # machine only).
+      # A grant bound to +identity+ needs that public_url with an identity
+      # header (Participants.invite).
       # @return [Invitation]
       # @raise [ArgumentError] no such session
-      # @raise [BadRequest] a bad name, kind or ttl, an archived session
-      def invite(id, name:, kind:, ttl: nil, cap: nil)
-        issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, cap: cap, state_dir: state_dir!)
+      # @raise [BadRequest] a bad name, kind, ttl or identity, an archived
+      #   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
+        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!)
         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}"
@@ -387,6 +391,13 @@ module Samagotchi
         raise BadRequest.new(e.message, code: "invalid_participant")
       end
 
+      # The header this machine's chi web names the signed-in user in (a
+      # link can be bound to an email: chi share --identity), nil when it
+      # has no such proxy: config's web.public_url with
+      # web.proxy.identity_header, or a running chi web --tunnel's.
+      # @return [String, nil]
+      def identity_header = configured_public_url&.identity_header
+
       # @return [Array<ParticipantView>] the ones it revoked
       def revoke_participants(id = nil, participant: nil)
         Participants.revoke(grants, session_id: id, id: participant, state_dir: state_dir!)
@@ -440,7 +451,7 @@ module Samagotchi
         configured = Config.get("web.public_url")
         return Web::Running.live_public_url(path: Web::Running.path(state_dir: state_dir!)) if configured.to_s.strip.empty?
 
-        Web::PublicUrl.from_config(url: configured)
+        Web::PublicUrl.from_config(url: configured, identity_header: Config.get("web.proxy.identity_header"))
       rescue Web::PublicUrl::Invalid
         nil
       end

data/lib/samagotchi/session_access/remote.rb

@@ -122,7 +122,7 @@ module Samagotchi
         end
       end
 
-      ACCESS_ERRORS = [TokenRevoked, TokenExpired, NotPermitted, TooManyTurns, CapReached].freeze
+      ACCESS_ERRORS = [TokenRevoked, TokenExpired, TokenBound, NotPermitted, TooManyTurns, CapReached].freeze
 
       # --- ids and sessions
 
@@ -252,15 +252,37 @@ module Samagotchi
       end
 
       # @param ttl [Integer, nil] seconds; nil: the grant's default
+      # @param identity [String, nil] bind the grant to this email: only a
+      #   chi web with bound grants (BOUND_FEATURE) is asked; an older one
+      #   would ignore it and issue a grant anyone could open
       # @return [Invitation]
-      # @raise [BadRequest] a bad name, kind or ttl, an archived session
-      def invite(id, name:, kind:, ttl: nil, cap: nil)
-        reply = request(:post, "#{session_path(id)}/participants", body: { name: name, kind: kind, ttl: ttl, cap: cap }.compact)
+      # @raise [BadRequest] a bad name, kind, ttl or identity, an archived
+      #   session, an identity that chi web has no proxy to check
+      # @raise [RemoteTooOld] an identity, and a chi web without bound grants
+      def invite(id, name:, kind:, ttl: nil, cap: nil, identity: nil)
+        require_feature!(BOUND_FEATURE) unless identity.nil?
+        body = { name: name, kind: kind, ttl: ttl, cap: cap, identity: identity }.compact
+        reply = request(:post, "#{session_path(id)}/participants", body: body)
         raise_refusal(reply) unless reply.status == 201
 
         json = reply.json
-        Invitation.new(participant: ParticipantView.from_h(json.fetch("participant")), token: json.fetch("token"),
-                       link: json.fetch("link"), lan: json["lan"] == true, warning: json["warning"])
+        participant = ParticipantView.from_h(json.fetch("participant"))
+        check_bound!(id, participant, identity)
+        Invitation.new(participant: participant, token: json.fetch("token"), link: json.fetch("link"),
+                       lan: json["lan"] == true, warning: json["warning"])
+      end
+
+      # Web::App::BOUND_FEATURE: POST …/participants takes an identity.
+      BOUND_FEATURE = "bound_grants"
+
+      # The header that chi web names the signed-in user in (GET
+      # /api/info's proxy), nil when it has no such proxy, or is a chi
+      # web from before it said.
+      # @return [String, nil]
+      def identity_header
+        check_server!
+        header = @proxy.is_a?(Hash) ? @proxy["identity_header"] : nil
+        header.is_a?(String) && !header.empty? ? header : nil
       end
 
       # Revokes one participant (+participant+), a session's, or with no
@@ -602,6 +624,7 @@ module Samagotchi
         if reply.json.is_a?(Hash)
           @version = reply.json["version"]
           @features = Array(reply.json["features"])
+          @proxy = reply.json["proxy"]
         end
         problem = Remote.info_problem(@entry, reply)
         raise problem if problem
@@ -611,6 +634,18 @@ module Samagotchi
 
       def too_old(version) = Remote.too_old_message(@entry, version)
 
+      # A grant asked bound to +identity+ came back bound to it, or is
+      # revoked at once (its link never printed) and refused: belt and
+      # braces behind BOUND_FEATURE.
+      # @raise [RemoteFailed]
+      def check_bound!(id, participant, identity)
+        return if identity.nil? || participant.identity == identity.to_s.strip.downcase
+
+        revoke_participants(id, participant: participant.id)
+        raise RemoteFailed, "#{@entry.label}: its chi web issued #{participant.id} unbound, so chi revoked it: " \
+                            "update chi there (chi update)"
+      end
+
       def strategy_or_hard(json) = strategy_of(json) || Guardrails::ParentPolicy.strategy(Guardrails::ParentPolicy::HARD)
 
       # chi web's 404 for a path no route takes (#serve_static's), not a
@@ -730,7 +765,7 @@ module Samagotchi
       # chi web's answer/dismiss reply as the worker's Bridge would have
       # given it: 503 not_live is no worker (nil), 504 the Bridge's 408, 501
       # not_supported its 404 for a route it lacks, 409 question_not_pending
-      # its 409; the rest as it came.
+      # its 409, 502 bridge_secret its 403 (BridgeSecret); the rest as it came.
       def bridge_reply(reply)
         json = reply.json.is_a?(Hash) ? reply.json : {}
         case [reply.status, json["error"]]
@@ -738,6 +773,7 @@ module Samagotchi
         in [404, "not_found"] then nil
         in [504, _] then BridgeClient::Response.new(status: 408, body: reply.body)
         in [501, "not_supported"] then BridgeClient::Response.new(status: 404, body: JSON.generate(json.merge("error" => "not_found")))
+        in [502, BridgeSecret::ERROR] then BridgeClient::Response.new(status: 403, body: reply.body)
         else BridgeClient::Response.new(status: reply.status, body: reply.body)
         end
       end

data/lib/samagotchi/session_access.rb

@@ -51,6 +51,13 @@ module Samagotchi
       def initialize(label) = super("#{label}: #{ParticipantMessages::TOKEN_EXPIRED}")
     end
 
+    # 401 token_bound: a link bound to one account, used without that
+    # account's sign-in (chi --remote doesn't go through the proxy).
+    class TokenBound < AuthRefused
+      CODE = "token_bound"
+      def initialize(label) = super("#{label}: #{ParticipantMessages::TOKEN_BOUND}")
+    end
+
     # 403 not_permitted: a participant's token on a route only the session's
     # owner may use.
     class NotPermitted < RemoteFailed
@@ -94,8 +101,11 @@ module Samagotchi
     # (Web::Grants::Grant#public_h): never its token or digest. +state+
     # "active", "revoked" or "expired".
     # +cap+ dollars and +queue+ turns (nil from a chi web before them).
+    # +identity+ the email the grant is bound to, nil for any.
     ParticipantView = Data.define(:id, :session_id, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
-                                  :revoked_by, :last_used_at, :state, :cap, :queue) do
+                                  :revoked_by, :last_used_at, :state, :cap, :queue, :identity) do
+      def initialize(identity: nil, **) = super
+
       def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key] || hash[key.to_s]] })
     end
 

data/lib/samagotchi/session_manager.rb

@@ -689,7 +689,7 @@ module Samagotchi
         raise RestartRefused.new(session_id, :unsupported, version: sidecar.version)
       end
 
-      reply = BridgeClient.new(session_id: session_id, port: sidecar.port).request_exit(client_id: client_id, restart: true)
+      reply = BridgeClient.for_sidecar(session_id, sidecar).request_exit(client_id: client_id, restart: true)
       raise RestartRefused.new(session_id, reply.json&.fetch("reason", nil) || :failed) if reply.status == 409
       raise RestartRefused.new(session_id, :failed) unless reply.status == 200
 

data/lib/samagotchi/sessions_command.rb

@@ -371,8 +371,7 @@ module Samagotchi
     # @return [Array(Hash, nil, Boolean, String, nil)]
     def stats_snapshot_for(session)
       dir = Samagotchi::Session.session_dir(session.id)
-      if (port = Samagotchi::BridgeClient.sidecar_port(dir))
-        client = Samagotchi::BridgeClient.new(session_id: session.id, port: port, read_timeout: STATS_TIMEOUT)
+      if (client = Samagotchi::BridgeClient.discover(session.id, session_dir: dir, read_timeout: STATS_TIMEOUT))
         body = client.get_json("stats")&.dig("metrics")
         if body.is_a?(Hash)
           return [TerminalUI::EventRenderer.deep_symbolize_keys(body), true, nil]

data/lib/samagotchi/share_command.rb

@@ -22,13 +22,16 @@ module Samagotchi
     include CLI::Command
 
     USAGE = <<~TEXT
-      Usage: chi share ID --name NAME [--agent] [--expires 3d] [--cap 2]
+      Usage: chi share ID --name NAME [--identity EMAIL] [--agent] [--expires 3d] [--cap 2]
              chi share ls [ID] [--format text|json]
              chi share cap ID PARTICIPANT DOLLARS
              chi share revoke ID [PARTICIPANT] | --all
         ID --name NAME   invite NAME to review session ID: prints the link they open (chi web on
                          the LAN, web.host: lan) and its QR code at a terminal. The link is shown
                          once; chi keeps only a digest of its token.
+          --identity EMAIL  bind the link to that account: it opens only through chi web's auth proxy
+                         signed in as EMAIL (web.public_url with web.proxy.identity_header, or
+                         chi web --tunnel tailscale); a forwarded link opens for nobody else
           --agent        the participant is an agent (the same link, used as a Bearer token)
           --expires N    Nh or Nd, 1h to 30d (default 7d, web.participants.expires)
           --cap DOLLARS  what their turns may cost you, $0 to $1000 (default $2, web.participants.cap)
@@ -50,6 +53,7 @@ module Samagotchi
     # The invite's flags (chi share ID …), and ls's and revoke's.
     FLAGS = CLI::Flags.new(help: HELP_WORDS) do |f|
       f.value "--name"
+      f.value "--identity"
       f.switch "--agent"
       f.value "--expires"
       f.value "--cap"
@@ -91,9 +95,9 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       send(:"run_#{@sub || "invite"}", parsed.options, parsed.args)
-    rescue SessionAccess::BadRequest => e
+    rescue SessionAccess::BadRequest, Web::Grants::BadIdentity => e
       usage_error(e.message)
-    rescue Web::Grants::Corrupt => e
+    rescue Web::Grants::Unwritable => e
       error_line("#{command_name}: #{e.message}")
       CLI::Exit::FAILED
     rescue ArgumentError => e
@@ -116,9 +120,13 @@ module Samagotchi
       cap = options[:cap] && dollars(options[:cap])
       return usage_error(CAP_USAGE) if cap == false
 
+      identity = options[:identity] && Web::Grants.clean_identity(options[:identity])
+
       id = @access.resolve(args.first)
-      invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap)
+      invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap,
+                                      identity: identity)
       print_invitation(id, invitation)
+      warn_unbound(invitation.participant)
       @changes = [[:joined, invitation.participant.id]]
       0
     end
@@ -186,10 +194,21 @@ module Samagotchi
       0
     end
 
+    # Decision B: an unbound link behind a proxy that could bind it opens
+    # for anyone the proxy lets in who holds it.
+    def warn_unbound(row)
+      return unless row.identity.nil? && (header = @access.identity_header)
+
+      error_line("#{command_name}: warning: #{format(UNBOUND_WARNING, header: header)}")
+    end
+
+    UNBOUND_WARNING = "this link isn't bound to an account: anyone the proxy lets in who gets it can open it " \
+                      "(--identity EMAIL binds it to the email %<header>s carries)"
+
     def print_invitation(id, invitation)
       row = invitation.participant
       @stdout.puts("#{row.id}  #{row.name} (#{row.kind}, #{row.role}) · session #{id[0, 8]} · expires " \
-                   "#{local(row.expires_at, "%Y-%m-%d %H:%M")} · cap #{money(row.cap)}")
+                   "#{local(row.expires_at, "%Y-%m-%d %H:%M")} · cap #{money(row.cap)}#{" · bound to #{row.identity}" if row.identity}")
       @stdout.puts(invitation.link)
       @stdout.puts("(shown once: chi keeps only its digest; chi share revoke #{id[0, 8]} #{row.id} ends it)")
       if invitation.warning
@@ -201,12 +220,14 @@ module Samagotchi
       @stdout.puts(Web::QR.lines(invitation.link)) if @tty
     end
 
-    COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "CAP", "STATE"].freeze
+    COLUMNS = ["SESSION", "PARTICIPANT", "NAME", "IDENTITY", "KIND", "ROLE", "CREATED", "EXPIRES", "LAST USED", "CAP",
+               "STATE"].freeze
 
     def print_table(rows)
       cells = rows.map do |row|
-        [row.session_id[0, 8], row.id, row.name, row.kind, row.role, local(row.created_at), local(row.expires_at),
-         row.last_used_at ? local(row.last_used_at) : "-", money(row.cap), row.state]
+        [row.session_id[0, 8], row.id, row.name, row.identity ? "#{row.identity} · bound" : "-", row.kind, row.role,
+         local(row.created_at), local(row.expires_at), row.last_used_at ? local(row.last_used_at) : "-", money(row.cap),
+         row.state]
       end
       widths = COLUMNS.each_index.map { |i| ([COLUMNS[i]] + cells.map { |c| c[i] }).map(&:length).max }
       [COLUMNS, *cells].each do |line|

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../client_id"
+require_relative "../bridge_secret"
 require_relative "../composer_route"
 require_relative "event_renderer"
 require_relative "formatting"
@@ -450,6 +451,8 @@ module Samagotchi
       # The stream ended for good: why, and what brings the session back.
       def closed_line(reason)
         id = @client.session_id
+        # The worker asked for a secret this terminal's chi doesn't send.
+        return "Lost the session's worker: #{BridgeSecret::REFUSED}" if reason == BridgeSecret::ERROR
         return remote_closed_line(reason, id) if via.remote?
 
         # Here a stopped session has always read as unreachable.

data/lib/samagotchi/terminal_ui/local_link.rb

@@ -55,12 +55,27 @@ module Samagotchi
         id = @client.session_id
         return [:gone, "stopped"] if Session.stopped_marker?(id, state_dir: @state_dir)
 
-        [BridgeClient.discover(id, session_dir: session_dir, host: @client.host), nil]
+        # Kept: the stream moves to this very client (EventStream), and
+        # #switched takes it, port and secret, rather than reading again.
+        @found = BridgeClient.discover(id, session_dir: session_dir, host: @client.host)
+        [@found, nil]
       end
 
-      # A new worker's Bridge, on the port its event names.
+      # A new worker's Bridge: the client #live_worker found for the stream
+      # (the event names its port), with that worker's secret. One the event
+      # doesn't name (another worker since) is read from the sidecar for that
+      # port, none when the sidecar names another one by now: that worker is
+      # gone too, and the stream finds the next.
       def switched(event)
-        @client = BridgeClient.new(session_id: @client.session_id, port: AttachLink.event_port(event), host: @client.host)
+        port = AttachLink.event_port(event)
+        found = @found
+        @client = if found&.port == port
+                    found
+                  else
+                    sidecar = WorkerSidecar.read(session_dir)
+                    sidecar = WorkerSidecar.new(port: port) unless sidecar&.port == port
+                    BridgeClient.for_sidecar(@client.session_id, sidecar, host: @client.host)
+                  end
       end
 
       # No sidecar to read: true, its Bridge answers (a P0-P2 worker refuses

data/lib/samagotchi/terminal_ui/question_slot.rb

@@ -15,6 +15,12 @@ module Samagotchi
       # A numbered option shows as "1) Apple", a word as "yes: continue".
       Option = Struct.new(:key, :label) do
         def text = key.match?(/\A\d+\z/) ? "#{key}) #{label}" : "#{key}: #{label}"
+
+        # The model's pick (a label ending in "(Recommended)"): painted bold,
+        # its label kept as is so a typed label still matches.
+        def recommended? = label.to_s.rstrip.end_with?("(Recommended)")
+
+        def code = recommended? ? "1;92" : 92
       end
 
       CONTINUE_QUESTION = "The turn ran out of iterations. Continue it?"
@@ -83,7 +89,7 @@ module Samagotchi
         question_rows = question_rows.first(1) unless details
         rows.concat(question_rows.map { |row| @paint.call(row, @question_code) })
         rows.concat(@details.map { |row| @paint.call(row, @question_code) }) if details
-        rows.concat(folded ? folded_options(width) : @options.map { |o| @paint.call("  #{o.text}", 92) })
+        rows.concat(folded ? folded_options(width) : @options.map { |o| @paint.call("  #{o.text}", o.code) })
         rows << @paint.call("  [#{@hint}]", 90) if hint && @hint
         rows
       end
@@ -91,19 +97,24 @@ module Samagotchi
       # The options packed into rows of +width+: "  1) Allow once · 2) Deny".
       def folded_options(width)
         rows = []
-        line = +""
+        line = []
         @options.each do |option|
-          item = option.text
-          candidate = line.empty? ? "  #{item}" : "#{line} · #{item}"
-          if !line.empty? && display_width(candidate) > width
+          if !line.empty? && display_width("  #{(line + [option]).map(&:text).join(" · ")}") > width
             rows << line
-            line = "  #{item}"
+            line = [option]
           else
-            line = +candidate
+            line << option
           end
         end
         rows << line unless line.empty?
-        rows.map { |row| @paint.call(row, 92) }
+        rows.map { |row| paint_folded(row) }
+      end
+
+      # One folded row; a recommended option in it is painted on its own.
+      def paint_folded(options)
+        return @paint.call("  #{options.map(&:text).join(" · ")}", 92) if options.none?(&:recommended?)
+
+        @paint.call("  ", 92) + options.map { |o| @paint.call(o.text, o.code) }.join(@paint.call(" · ", 92))
       end
 
       # Word wrap at +width+ columns, the first row after +first+, the others

data/lib/samagotchi/tool_declarations.rb

@@ -412,7 +412,7 @@ module Samagotchi
       },
       {
         name: "ask_user_question",
-        description: "Ask the user a structured qualification question. Supports single/multi selection plus optional freeform/Other input. Prefer this over plain numbered lists when you need a clear choice. The harness renders it natively and returns {selected, freeform}.",
+        description: "Ask the user a structured qualification question. Supports single/multi selection plus optional freeform/Other input. Prefer this over plain numbered lists when you need a clear choice. The harness renders it natively and returns {selected, freeform}. If you recommend one option, put it first and end its label with ' (Recommended)'.",
         parameters: {
           type: "object",
           properties: {

data/lib/samagotchi/tool_runner.rb

@@ -77,7 +77,16 @@ module Samagotchi
       # hook, no approval card for a call that can't run (KernelLoop#dispatch
       # answers it with the not-loaded error).
       original = call.dup
-      verdict = left_out?(call) ? Guardrails::Verdict.new(call: call) : evaluate(call, iteration, params)
+      refusal = unreached_group_refusal(call)
+      verdict = if refusal
+                  Guardrails::Verdict.new(call: call).deny!(refusal.message,
+                                                            rule: Tools::ToolIndex::ToolkitGroupRefusal::RULE,
+                                                            source: "core", decided_by: "core")
+                elsif left_out?(call)
+                  Guardrails::Verdict.new(call: call)
+                else
+                  evaluate(call, iteration, params)
+                end
       call = verdict.call
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       label = plugin_label(call[:name])
@@ -378,6 +387,27 @@ module Samagotchi
       !registry.left_out(call[:name], layers: layers).nil?
     end
 
+    def unreached_group_refusal(call)
+      return if participant_turn?
+
+      registry = tools
+      index = registry&.index if registry.respond_to?(:index)
+      return unless index.respond_to?(:unreached_tool)
+
+      name = if call[:name] == index.call_name
+               args = call[:args].is_a?(Hash) ? call[:args] : {}
+               args["tool"] || args[:tool]
+             else
+               call[:name]
+             end
+      tool = index.unreached_tool(name)
+      tool && Tools::ToolIndex::ToolkitGroupRefusal.for(tool, registry)
+    end
+
+    def participant_turn?
+      @kernel.respond_to?(:participant_turn?) && @kernel.participant_turn?
+    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
 
@@ -431,6 +461,12 @@ module Samagotchi
     # A legacy veto keeps its old text; a verdict's deny tells the model
     # who decided and not to route around it.
     def denied(call, verdict)
+      if verdict.rule == Tools::ToolIndex::ToolkitGroupRefusal::RULE
+        output = "[#{call[:name]}] #{verdict.reason}"
+        activity = ToolActivity.tool_activity_event(call[:name], call, output, registry: tools)
+        return { output: output, activity: activity.merge(status: "blocked", guardrail: verdict.to_activity) }
+      end
+
       output = if verdict.legacy?
                  reason = verdict.reason.to_s.strip
                  "[#{call[:name]}] Error: blocked by guardrail: #{reason.empty? ? "blocked by hook" : reason}"