samagotchi 0.78.0 → 0.80.0

data/lib/samagotchi/bootstrap_command.rb

@@ -14,9 +14,10 @@ require_relative "redacted_inspect"
 
 module Samagotchi
   # `chi bootstrap [TARGET]`: the first setup. It names a model server, works
-  # out what it is (llama.cpp's native API or an OpenAI-compatible one),
-  # picks the model, sends one test request and writes config.yml: a fresh
-  # file, or a hosts: entry added to an existing one. Then it installs the
+  # out what it is (llama.cpp's native API, an OpenAI-compatible one or
+  # Anthropic's Messages API, Bootstrap::Probe), picks the model, sends one
+  # test request and writes config.yml: a fresh file, or a hosts: entry
+  # added to an existing one. Then it installs the
   # system bundle and the core profile, and on a terminal asks about dev.
   # Prompts only on a terminal; a script gets the list and exit 2 instead.
   class BootstrapCommand
@@ -24,11 +25,14 @@ module Samagotchi
     include RedactedInspect
 
     USAGE = <<~TEXT
-      Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--no-test] [--dry-run]
+      Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--api API] [--dialect NAME]
+                           [--no-test] [--dry-run]
         Finds the model server at TARGET and writes config.yml for it.
           chi bootstrap 192.168.1.29:8081          llama.cpp on the LAN
           chi bootstrap localhost:11434            Ollama
           chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+          chi bootstrap https://api.anthropic.com --key-env ANTHROPIC_API_KEY
+          chi bootstrap https://api.fireworks.ai/inference/v1 --key-env FIREWORKS_API_KEY --api anthropic
           chi bootstrap                            look on this machine's usual ports
         TARGET        host[:port] (port 8080 when none), or a URL; a URL's
                       path is the OpenAI API base
@@ -37,6 +41,12 @@ module Samagotchi
         --model ID    the model, when the server has several
         --key-env VAR the environment variable holding the API key (the
                       key itself is never written)
+        --api API     openai or anthropic (Anthropic's Messages API) instead
+                      of detecting it; detection takes anthropic only when
+                      the OpenAI model list is refused
+        --dialect NAME the Messages API's dialect: standard or fireworks
+                      (implies --api anthropic; default: fireworks when the
+                      host or the model ids say so)
         --no-test     skip the test request
         --dry-run     show what would be written; write nothing
         With no config.yml it writes one; an existing one gets a hosts:
@@ -50,10 +60,13 @@ module Samagotchi
       f.value "--name"
       f.value "--model"
       f.value "--key-env"
+      f.value "--api"
+      f.value "--dialect"
       f.switch "--no-test"
       f.switch "--dry-run"
     end
 
+    APIS = %i[openai anthropic].freeze
     PICK_SHOWN = 20
     # A test request slower than this says it is waiting (a model loading).
     LOADING_AFTER = 3
@@ -92,6 +105,8 @@ module Samagotchi
         return @exit
       end
 
+      @api = options[:api]
+      @dialect = options[:dialect]
       result = find(options, key_env) or return @exit
       unlocked = with_key(result, key_env) or return @exit
       result, key_env = unlocked
@@ -124,7 +139,25 @@ module Samagotchi
         return usage_error("--key-env takes the variable's name (e.g. OPENROUTER_API_KEY), not the key")
       end
 
-      options
+      parse_api(options)
+    end
+
+    # --api as a Symbol, --dialect downcased (implying --api anthropic).
+    def parse_api(options)
+      if options[:api]
+        api = options[:api].strip.downcase.to_sym
+        return usage_error("--api must be #{APIS.join(" or ")} (got #{options[:api]})") unless APIS.include?(api)
+
+        options[:api] = api
+      end
+      return options unless options[:dialect]
+
+      dialect = options[:dialect].strip.downcase
+      names = LLM::Dialect::BY_NAME.keys
+      return usage_error("--dialect must be #{names.join(" or ")} (got #{options[:dialect]})") unless names.include?(dialect)
+      return usage_error("--dialect is for --api anthropic, not --api openai") if options[:api] == :openai
+
+      options.merge(dialect: dialect, api: :anthropic)
     end
 
     # The server's Probe::Result, or nil with @exit set.
@@ -137,17 +170,26 @@ module Samagotchi
         @exit = usage_error(e.message)
         return nil
       end
-      result = @probe.classify_target(candidates, key_env: key_env)
+      result = @probe.classify_target(candidates, key_env: key_env, api: @api, dialect: @dialect)
       case result.kind
       when :unreachable
         fail!("can't reach #{result.candidate.label} (#{result.reason})")
       when :unknown
         detail = result.status ? "HTTP #{result.status}" : result.reason
-        fail!("reached #{result.candidate.label} but it answers neither llama.cpp /props nor /v1/models (#{detail})")
+        fail!("reached #{result.candidate.label} but it answers #{unknown_asked} (#{detail})")
       else result
       end
     end
 
+    # What an :unknown server didn't answer, by what --api let the probe ask.
+    def unknown_asked
+      case @api
+      when :anthropic then "no Anthropic /v1/models"
+      when :openai then "neither llama.cpp /props nor /v1/models"
+      else "neither llama.cpp /props, /v1/models nor the Anthropic /v1/models"
+      end
+    end
+
     def scan
       found = @probe.scan_local
       ports = Bootstrap::Probe::LOCAL_PORTS.keys.join(", ")
@@ -190,7 +232,7 @@ module Samagotchi
       return fail!("#{key_env} isn't a variable name") unless key_env.match?(ConfigFile::ENV_NAME_RE)
       return fail!("#{key_env} is not set; #{export_hint(key_env, "and run chi bootstrap again")}") if unset?(key_env)
 
-      result = @probe.classify(result.candidate, key_env: key_env)
+      result = @probe.classify(result.candidate, key_env: key_env, api: @api, dialect: @dialect)
       return fail!("#{host} refused the key in #{key_env} (HTTP #{result.status})") if result.kind == :needs_key
       return fail!("can't reach #{host} (#{result.reason || "HTTP #{result.status}"})") unless result.reached?
 
@@ -201,8 +243,15 @@ module Samagotchi
       if result.native?
         build = result.props["build_info"].to_s
         @stdout.puts("found: llama.cpp at #{result.candidate.root}#{" (build #{build})" unless build.empty?}")
+      elsif result.anthropic?
+        dialect = " (dialect: #{result.dialect})" if result.dialect
+        @stdout.puts("found: an Anthropic Messages API at #{Bootstrap::Probe.api_root(result.candidate)}#{dialect}")
       else
         @stdout.puts("found: an OpenAI-compatible API at #{result.candidate.base}")
+        # By the host only: a proxy listing accounts/fireworks/ ids may not serve /v1/messages.
+        if @api.nil? && Bootstrap::Probe.fireworks_host?(result.candidate.host)
+          @stdout.puts("Fireworks also serves the Anthropic Messages API: --api anthropic")
+        end
       end
     end
 
@@ -248,17 +297,28 @@ module Samagotchi
                     @stdout.puts("test: waiting for an answer (loading the model?)…") if done.pop(timeout: LOADING_AFTER).nil?
                   end
                 end
-      seconds = @probe.test_turn(result.candidate, model, key_env: key_env)
+      seconds = @probe.test_turn(result.candidate, model, key_env: key_env, api: result.anthropic? ? :anthropic : :openai,
+                                                          dialect: result.dialect, auth: result.auth)
       @stdout.puts(format("test: answered in %.1f s", seconds))
       true
     rescue StandardError => e
-      @stdout.puts("test: failed: #{e.message}")
+      @stdout.puts("test: failed: #{e.message}#{messages_hint(result, e)}")
       false
     ensure
       done&.push(true)
       waiting&.join
     end
 
+    # A detected OpenAI server whose model list worked but whose
+    # /chat/completions is 404: maybe a Messages-only url (a gateway's
+    # Anthropic route that also lists the OpenAI way).
+    def messages_hint(result, error)
+      return "" unless @api.nil? && result.kind == :openai && error.is_a?(Bootstrap::Probe::TestFailed)
+      return "" unless error.status == 404 && error.path.to_s.end_with?("/chat/completions")
+
+      " (an Anthropic Messages API? try --api anthropic)"
+    end
+
     # The "loading the model?" hint fits a local server (a llama.cpp loading
     # weights); a remote provider's slow answer is the network, not a load.
     def loading_hint?(result)
@@ -268,7 +328,7 @@ module Samagotchi
     # 0 written, 1 written but not as planned, nil with @exit on a refusal.
     def write(result, model, key_env, options)
       writer = Bootstrap::ConfigWriter.new(path: @config_path, env: @env)
-      fields = host_fields(result.candidate, result.native?, key_env)
+      fields = host_fields(result, key_env)
       ids = result.models.map(&:id)
       base = Bootstrap::ConfigWriter.derived_name(result.candidate.host)
       name, reason = begin
@@ -350,18 +410,35 @@ module Samagotchi
     end
 
     # The hosts entry: host/port for a plain http server (api: openai when it
-    # isn't llama.cpp), url for https or a URL with its own path.
-    def host_fields(candidate, native, key_env)
+    # isn't llama.cpp), url for https or a URL with its own path (an
+    # Anthropic one without /v1: the API root, as the hand-written claude
+    # host has it). Then api, dialect, auth (Bearer only when the dialect's
+    # own header isn't), api_key_env.
+    def host_fields(result, key_env)
+      candidate = result.candidate
       fields = if candidate.url || candidate.scheme == "https"
-                 { "url" => native ? candidate.root : candidate.base }
+                 { "url" => url_field(result) }
                else
                  { "host" => candidate.host, "port" => candidate.port }
                end
-      fields["api"] = "openai" unless native
+      if result.anthropic?
+        fields["api"] = "anthropic"
+        fields["dialect"] = result.dialect if result.dialect
+        fields["auth"] = result.auth.to_s if result.auth && result.auth != LLM::Dialect.for(result.dialect).auth
+      elsif !result.native?
+        fields["api"] = "openai"
+      end
       fields["api_key_env"] = key_env if key_env
       fields
     end
 
+    def url_field(result)
+      return result.candidate.root if result.native?
+      return Bootstrap::Probe.api_root(result.candidate) if result.anthropic?
+
+      result.candidate.base
+    end
+
     def report(outcome, model)
       path = outcome.path
       case outcome.kind

data/lib/samagotchi/bridge.rb

@@ -658,7 +658,7 @@ module Samagotchi
 
       begin
         result = @engine.answer_question(id: qid, selected: selected, freeform: freeform, client_id: client_id)
-        [{}, 200, { status: "answered", session_id: session_id, answer: result }]
+        [{}, 200, { status: "answered", session_id: session_id, answer: result.to_h }]
       rescue Engine::QuestionNotPending => e
         # Another client answered first, or the question was cancelled.
         [{}, 409, { error: "question_not_pending", detail: e.message }]

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.78.0
+version: 0.80.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:b5b3166c91f6f2af2563dd9db5f9959cda66747d907017acd0776fcd2fe29049
+  self_map.md: sha256:4ff5708e51f55089de47b107643ae0b74aee04cb96111226823a8d44fb4bc33d
   config_modification_protocol.md: sha256:66792f788cdbb8ee0252f2c387c96bd75266817bb75f721aaa181b602db97137
   memory_guide.md: sha256:c48eea744db69e4f3e9bb415e9a03a8c78bbcaa1205ad3b1fb157a079f92d22e
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

data/lib/samagotchi/bundles/system/self_map.md

@@ -48,7 +48,7 @@
   approvals (I see only how each was answered); see `docs/sessions.md` "Delegating".
 - Bundles extend me: memories, `hooks/*.rb`, `guardrails/*.yml`, and a `plugin.rb` that adds slash
   commands (`anytime:` ones run mid-turn), model tools (they can return images I see), hooks,
-  cards, side answers (`ask_model`),
+  cards, side answers (`ask_model`), HTTP calls (`ctx.http`),
   child sessions and services (e.g. MCP server processes). Shipped: `btw` (`/btw` side question),
   `mcp` (MCP server tools, searched with find_tools and called with call_tool; a screenshot comes as a picture; a toolkit's undeclared built-ins too, as chi/<tool>), `guardrails` (rules), `known-names` (typo guard), `source-links`
   (turns source refs like JIRA-123 in an answer into links in the web, and a one-line note), `loop-guard`

data/lib/samagotchi/continue_offer.rb

@@ -211,13 +211,13 @@ module Samagotchi
     def answered(answer, client_id:)
       # The /continue line takes the text on one line; the steer keeps its
       # line breaks.
-      text = answer[:freeform].to_s.gsub(/\s+/, " ").strip
+      text = answer.freeform.to_s.gsub(/\s+/, " ").strip
       @continue_steer = nil
-      if Array(answer[:selected]).include?(CONTINUE) && !text.empty?
-        @continue_steer = { text: answer[:freeform].to_s.strip,
-                            source: answer[:by] == "parent_agent" ? "parent_agent" : "user" }
+      if answer.selected.include?(CONTINUE) && !text.empty?
+        @continue_steer = { text: answer.freeform.to_s.strip,
+                            source: answer.parent_agent? ? "parent_agent" : "user" }
       end
-      line = if Array(answer[:selected]).include?(CONTINUE) then "/continue yes"
+      line = if answer.selected.include?(CONTINUE) then "/continue yes"
              elsif text.empty? then "/continue no"
              else "/continue no, #{text}"
              end

data/lib/samagotchi/engine.rb

@@ -27,6 +27,7 @@ require_relative "tools/tool_index"
 require_relative "peer_sources"
 require_relative "session_commands"
 require_relative "plugin/loader"
+require_relative "plugin/card"
 require_relative "extension_load"
 require_relative "log"
 require_relative "log_subscriber"
@@ -784,9 +785,6 @@ module Samagotchi
 
     # ── Cards ───────────────────────────────────────────────────────────────
 
-    CARD_LEVELS = %i[info warn].freeze
-    MAX_CARD_ACTIONS = 6
-
     # Show a card in every UI (docs/plugins.md, Cards): {type: :card, id:,
     # source:, title:, body:, level:, actions: [{label:, command:}], in_turn:}.
     # Where it goes (held while the plugins load, an anytime command's, an
@@ -799,7 +797,7 @@ module Samagotchi
     # @return [String] the card's id
     # @raise [ArgumentError] a card without a title, or a bad action
     def show_card(source:, title:, body: "", actions: [], level: :info, id: nil)
-      card = build_card(source: source, title: title, body: body, actions: actions, level: level, id: id)
+      card = Plugin::Card.build(source: source, title: title, body: body, actions: actions, level: level, id: id)
       @event_routes.route(card, **EventRoutes::CARD_MARKS)
       card[:id]
     end
@@ -963,32 +961,6 @@ module Samagotchi
     end
     private :announce_or_hold
 
-    def build_card(source:, title:, body:, actions:, level:, id:)
-      title = title.to_s.strip
-      raise ArgumentError, "a card needs a title" if title.empty?
-
-      level = level.to_s.to_sym
-      raise ArgumentError, "card level must be one of #{CARD_LEVELS.join(", ")}" unless CARD_LEVELS.include?(level)
-
-      actions = Array(actions)
-      raise ArgumentError, "a card has at most #{MAX_CARD_ACTIONS} actions" if actions.size > MAX_CARD_ACTIONS
-
-      actions = actions.map do |action|
-        raise ArgumentError, "a card action is a Hash {label:, command:}" unless action.is_a?(Hash)
-
-        action = action.transform_keys(&:to_sym)
-        command = action[:command].to_s.strip
-        raise ArgumentError, "a card action needs a command" if command.empty? || command.include?("\n")
-
-        label = action[:label].to_s.strip
-        { label: label.empty? ? command : label, command: command }
-      end
-      id = id.to_s.strip
-      { type: :card, id: id.empty? ? SecureRandom.hex(4) : id, source: source.to_s, title: title, body: body.to_s,
-        level: level, actions: actions }
-    end
-    private :build_card
-
     # ── Model switching ────────────────────────────────────────────────────────
 
     # @param typed [String, nil] the name the model was typed as when
@@ -1452,6 +1424,7 @@ module Samagotchi
         emit_event(turn.on_event, turn.tag(event))
       end
       turn.ended = true
+      @turn_state.ended!
       save_quietly(turn.session) if save
       @metrics.persist(state_dir: session_state_dir)
     end
@@ -1582,7 +1555,8 @@ module Samagotchi
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
     #   (as a Hash or as keywords)
     # @param watch [#call, nil] closes the question with the reason it returns
-    # @return [Hash, String] the answer, or {error:, …}
+    # @return [QuestionAnswer, Hash, String] the answer, or {error:, …}, or a
+    #   sync handler's text
     def open_question(fields = nil, watch: nil, **more)
       @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
     end
@@ -1601,7 +1575,7 @@ module Samagotchi
     end
 
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
-    # @return [Hash] normalized answer
+    # @return [QuestionAnswer]
     def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
       @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id,
                             parent_agent: parent_agent)
@@ -2569,8 +2543,10 @@ module Samagotchi
         toolkit: -> { @toolkit_binding.name },
         declared_tools: -> { toolkit_explained.declared.map(&:name) },
         use_toolkit: ->(name) { use_toolkit(name) },
-        ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
-          ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller)
+        cancel_controller: ->(handler: false) { plugin_cancel_controller(handler: handler) },
+        ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil|
+          ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
+                                  model: model)
         },
         model_name: -> { effective_model_ref },
         model_key: -> { @model_key },
@@ -2585,6 +2561,15 @@ module Samagotchi
       )
     end
 
+    # The controller a plugin's ctx.http call without cancel: stops with
+    # (docs/plugins.md): an init task's own, else the running turn's for the
+    # turn's own work until the turn has ended (TurnState#own_controller); nil
+    # for an anytime command, a service or a thread of the plugin's.
+    def plugin_cancel_controller(handler:)
+      (task = current_init_task) ? task.cancel : @turn_state.own_controller(handler: handler)
+    end
+    private :plugin_cancel_controller
+
     # A plugin's ctx.messages: the conversation without the system prompt
     # (the REPL's starts with it, a worker's new session doesn't), and,
     # while a turn runs, the turn so far from the Bridge (plan O1). Read
@@ -2601,14 +2586,15 @@ module Samagotchi
     private :plugin_messages
 
     # ctx.ask_model's request: the session's current model on its host, as
-    # a turn resolves them (a /model switch counts), through its own
+    # a turn resolves them (a /model switch counts), or a configured +model+
+    # (a host:id ref, an alias, a bare id one of a host's models), through its own
     # IdleClient, so it shares nothing with the turn's backend. The client
     # is kept while the target and timeout stay (what it learned, e.g. a
     # refused thinking-off, holds for the next request); the session's id
     # goes with the request.
     # @return [String] the answer
-    def ask_side_model(request, timeout:, max_tokens:, cancel_controller:)
-      target = session_model_recap_target
+    def ask_side_model(request, timeout:, max_tokens:, cancel_controller:, model: nil)
+      target = model.nil? ? session_model_recap_target : configured_side_target(model)
       client = side_model_client(target, timeout)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller, session_id: @session&.id)
@@ -2618,6 +2604,23 @@ module Samagotchi
     end
     private :ask_side_model
 
+    # The target of ctx.ask_model(model:): +model+ as a turn resolves it,
+    # once it is known to name something configured. IdleTarget.of_model
+    # never raises (an unknown host falls to the default host, an unknown id
+    # to the default entry), so a typo would silently ask another model.
+    # @raise [ArgumentError] +model+ names no configured host and is no
+    #   host's model (cached, declared or saved lists; nothing is asked)
+    def configured_side_target(model)
+      ref = @host_registry.model_ref(model)
+      unless ref.host_name || ref.alias_name || @host_registry.hosts_with_model(ref.id).any?
+        raise ArgumentError, "ask_model: unknown model #{model.to_s.inspect} (use a configured host:id, an alias, " \
+                             "or a model id one of your hosts lists)"
+      end
+
+      IdleTarget.of_model(@host_registry, model)
+    end
+    private :configured_side_target
+
     # The IdleClient for +target+ at +timeout+: the last one when both are
     # the same, else a new one.
     def side_model_client(target, timeout)

data/lib/samagotchi/guardrails/approval.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../question_answer"
+
 module Samagotchi
   module Guardrails
     # An ask as a question for the user (Engine#open_question), and the
@@ -67,22 +69,22 @@ module Samagotchi
       end
 
       # Settle +verdict+ from open_question's result.
-      # @param answer [Hash, String] {selected_indices:, freeform:} or {error:}
+      # @param answer [QuestionAnswer, Hash, String] the answer, or {error:} (anything else is a cancel)
       # @param scopes [Array<String>] the offered scopes, in option order
       # @return [Verdict]
       def settle(verdict, answer, scopes)
-        unless answer.is_a?(Hash) && !answer[:error]
+        unless answer.is_a?(QuestionAnswer)
           return verdict.settle!(:deny, decided_by: "user", note: "The approval was cancelled.")
         end
 
-        index = Array(answer[:selected_indices]).first
+        index = answer.selected_indices.first
         if index && index < scopes.size
           verdict.settle!(:allow, decided_by: "user")
           verdict.scope = scopes[index]
           return verdict
         end
 
-        freeform = answer[:freeform].to_s.strip
+        freeform = answer.freeform.to_s.strip
         note = freeform.empty? ? "The user declined this call." : "The user declined this call: #{freeform.inspect}."
         verdict.settle!(:deny, decided_by: "user", note: note)
       end

data/lib/samagotchi/guardrails/gate.rb

@@ -49,10 +49,14 @@ module Samagotchi
       # @param call [Hash] the parsed tool call
       # @param iteration [Integer]
       # @param params [String] the call's one-line preview
+      # @param verdict [Verdict, nil] the one the voters vote on (the test
+      #   kit's recording one, maybe with a vote already in); default a new
+      #   one for +call+
       # @return [Verdict]
-      def evaluate(call, iteration:, params:)
+      def evaluate(call, iteration:, params:, verdict: nil)
         context = @context_lookup.call
-        verdict = Verdict.new(call: call)
+        verdict ||= Verdict.new(call: call)
+        verdict.call = call
         if @cancelled_lookup.call
           verdict.deny!("the turn was stopped", decided_by: "core")
           verdict.context = context
@@ -60,7 +64,7 @@ module Samagotchi
           return verdict
         end
         before = { type: :before_tool_call, iteration: iteration, call: call.dup, params: params,
-                   blocked: false, block_reason: nil, guardrail: verdict,
+                   blocked: verdict.deny?, block_reason: (verdict.reason if verdict.deny?), guardrail: verdict,
                    context: context.to_h, targets: targets_for(call, context).to_h }
         fire_each(:before_tool_call, before) do |event|
           verdict.legacy_deny!(event[:block_reason]) if event[:blocked]

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -70,10 +70,7 @@ module Samagotchi
             # A hook with no declared event cannot be auto-registered.
             next if hook.event.empty?
 
-            event_sym = hook.event.to_sym
-            on_error = hook.on_error
-            priority = hook.priority
-            fail_closed = on_error == "fail_closed" && event_sym == :before_tool_call
+            fail_closed = hook.on_error == "fail_closed" && hook.event == "before_tool_call"
             what = "hook #{basename} (bundle #{bundle_name})"
             file = hooks_dir && File.join(hooks_dir, basename)
             unless file && File.exist?(file)
@@ -87,15 +84,7 @@ module Samagotchi
             end
 
             begin
-              plugin = instantiate(bundle_name, basename, file, settings: settings)
-              policy = if fail_closed then :deny
-                       elsif on_error == "log" then :log
-                       else :skip
-                       end
-              label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-              handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                                   fields: { bundle: bundle_name }) { |event| plugin.call(event) }
-              registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: priority, &handler)
+              load_hook_file(bundle_name, basename, file, hook, registry, settings: settings)
               loaded += 1
             rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
               raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
@@ -107,6 +96,31 @@ module Samagotchi
           loaded
         end
 
+        # Build one hook file and register it in +registry+ under its
+        # event, priority and error policy (a fail_closed before_tool_call
+        # one denies when it raises). No missing-file, sha or requires_chi
+        # check: #load makes them; the test kit loads a bundle's source
+        # this way.
+        # @param hook [MemoryBundle::BundleHook] its manifest entry
+        # @param namespace [Module, nil] the module the file is evaluated
+        #   in (default: the bundle's, #namespace_for)
+        # @raise [Exception] what loading or building the file raised;
+        #   nothing is registered then
+        def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil)
+          event_sym = hook.event.to_sym
+          fail_closed = hook.on_error == "fail_closed" && event_sym == :before_tool_call
+          plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
+          policy = if fail_closed then :deny
+                   elsif hook.on_error == "log" then :log
+                   else :skip
+                   end
+          label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
+          handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                               fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+          registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          nil
+        end
+
         # Why the file doesn't match the sha256 recorded at install, or nil.
         # With none recorded, only a required hook counts as a mismatch.
         def sha_mismatch(file, recorded, required:)
@@ -119,12 +133,13 @@ module Samagotchi
           "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
         end
 
-        # Evaluate a plugin file inside the bundle's namespace module and
+        # Evaluate a plugin file inside the bundle's namespace module (or
+        # +namespace+) and
         # return an instance that responds to #call. A class whose
         # initialize takes an argument gets the settings (one Hash, string
         # keys); one that takes none is built bare.
-        def instantiate(bundle_name, basename, file, settings: {})
-          ns = namespace_for(bundle_name)
+        def instantiate(bundle_name, basename, file, settings: {}, namespace: nil)
+          ns = namespace || namespace_for(bundle_name)
           content = File.read(file)
           ns.module_eval(content, file, 1)
           klass = Hooks.class_for(basename, ns)