samagotchi 0.68.0 → 0.69.0

data/docs/testing.md

@@ -15,6 +15,11 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
+Goldens (`*_golden_spec.rb`, the prompt snapshots) hold no machine state, so they pass on any runner: no absolute
+paths (replace them with placeholders), no PATH tools (the suite pins `rg` as found, `spec_helper.rb`; an example
+that sets PATH to test the lookup is tagged `:real_rg`), no Ruby-version-dependent `inspect` (a Hash's or an
+exception's text changes between Ruby versions: write the string yourself).
+
 The web specs run in plain node. One that loads lit-html, itself or through a module it imports (`turn_view.js`,
 `turn_html.js`, `card.js`, `copy.js`, `images.js`, `scope.js`, `command_view.js`, `diff_view.js`, `read_view.js`,
 `question_cards.js`, `stream_handlers.js`, `stage_view.js`, `bubbles.js`, `cards_place.js`, the chips, `info_bar.js`, `info_bar_model.js`, `lists_view.js`, `context_chips.js`, `families_view.js`,
@@ -49,7 +54,8 @@ script/affected-specs A..B            # another range (A...B: from their merge-b
 
 A builder runs these while working, not the full suite: the specs the change touched, the specs named after the
 files it changed (`lib/samagotchi/foo/bar.rb` → `spec/foo/bar_spec.rb`, `bar_*_spec.rb`…), the specs that read
-docs or source as text (its `RULES`: add one when a full run catches what the names missed), then the other name
+docs or source as text (its `RULES`: add one when a full run catches what the names missed) and the golden of a changed
+file's layer (any `terminal_ui/*.rb` → `spec/terminal_ui_golden_spec.rb`), then the other name
 matches (a spec named after several changed files first, e.g. `engine_toolkit_spec.rb` for `engine.rb` and
 `toolkit.rb`; then one beside the file, so `plugin/context.rb` picks `spec/samagotchi/plugin/*context*` before
 `spec/guardrails/context_spec.rb`), then the specs that name a changed file's class. The default range is the merge-base with main (or origin/main) plus uncommitted and untracked files.

data/lib/samagotchi/bootstrap/probe.rb

@@ -239,9 +239,7 @@ module Samagotchi
                  .fetch(uri, request, retries: false, check_status: false, log_fields: { purpose: "probe" })
       end
 
-      def network_errors
-        [*LLM::HTTP::NETWORK_ERRORS, OpenSSL::SSL::SSLError, Errno::EADDRNOTAVAIL, Errno::ENETDOWN, Errno::EPIPE]
-      end
+      def network_errors = LLM::HTTP::NETWORK_ERRORS
 
       def reason(error)
         case error

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.68.0
+version: 0.69.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:9528cc4c7d512a3fdfb103bf966a0359acad11c218666512d628a8d00378aaab
+  self_map.md: sha256:b5b3166c91f6f2af2563dd9db5f9959cda66747d907017acd0776fcd2fe29049
   config_modification_protocol.md: sha256:c7decf27af999066195f83e71222a6ae294f13174ced9664a21cd1dabf8b854a
   memory_guide.md: sha256:c48eea744db69e4f3e9bb415e9a03a8c78bbcaa1205ad3b1fb157a079f92d22e
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -50,7 +50,7 @@
   commands (`anytime:` ones run mid-turn), model tools (they can return images I see), hooks,
   cards, side answers (`ask_model`),
   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), `guardrails` (rules), `known-names` (typo guard), `source-links`
+  `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`
   (denies a repeated tool call with the same result, stops the turn after a few, and cuts thinking that
   repeats itself, asking me again), `check-in` (after N tool

data/lib/samagotchi/config.rb

@@ -1058,25 +1058,6 @@ module Samagotchi
       hosts.keys.map { |k| k.to_s.downcase }.include?(prefix) ? nil : prefix
     end
 
-    # hosts_config as a SAMAGOTCHI_HOSTS_JSON override (workers no longer
-    # get one: they read config.yml).
-    def hosts_json_for_env(env: ENV, path: global_path(env: env))
-      hosts = hosts_config(env: env, path: path)
-      # Only serialize if non-default or explicitly configured hosts:
-      # include when hosts file exists with hosts: section or when workers need propagation
-      return nil if hosts.nil? || hosts.empty?
-
-      # Every field travels (HostConfig#to_env_h); the worker parses it back.
-      simple = hosts.transform_values(&:to_env_h)
-      # Disabled hosts travel as just that, so a worker refuses "box:x"
-      # the way its parent does instead of sending it to the default host.
-      disabled_host_names(env: env, path: path).grep(HOST_NAME_RE).each { |name| simple[name] ||= { "enabled" => false } }
-      JSON.generate(simple)
-    rescue StandardError => e
-      Log.error(:config, "hosts_json_failed", error: e.class.name, message: e.message)
-      nil
-    end
-
     # A top-level section of config.yml as written (nil when absent or the
     # file doesn't parse); a reader checks its shape.
     def section(name, env: ENV, path: global_path(env: env))

data/lib/samagotchi/engine.rb

@@ -212,6 +212,10 @@ module Samagotchi
       @lifecycle_mutex = Mutex.new
       @shut_down = false
       load_plugins if plugins
+      # Registered from what the sources published while they loaded, and
+      # with no plugins too: a toolkit's left-out built-ins are reachable
+      # either way (declared per toolkit, Tools::Registry).
+      @tool_index.declare(@tools, failures: @plugin_failures)
       guardrail_rules
       # The Engine owns the reminder store; its kernel (built here, or a
       # spec's) gets it, so tool calls via KernelLoop and reminder injection
@@ -2497,8 +2501,6 @@ module Samagotchi
       # start) waits for the first turn, beside the load warnings: no UI
       # is there yet, and the Engine isn't built.
       @extension_load.load_plugins(registries, failures: @plugin_failures)
-      # Declared once, from what the sources published while they loaded.
-      @tool_index.declare(@tools, failures: @plugin_failures)
     end
 
     # Keep a plugin's new tool set (chi.replace_tools, from any thread)
@@ -2547,6 +2549,7 @@ module Samagotchi
         state_dir: -> { session_state_dir },
         can_stage: -> { !turn_running? && !history? },
         reset_prompt: -> { @prompt_builder&.reset! },
+        refresh_index: -> { @tool_index.refresh! },
         emit: ->(sink, event) { emit_event(sink, event) },
         notify: ->(text, level, source, extra:) { hook_notify(text, level, source, extra: extra) }
       )

data/lib/samagotchi/guardrails/targets.rb

@@ -3,6 +3,7 @@
 require_relative "../tools/tool_path"
 require_relative "../tools/memory"
 require_relative "../tool_declarations"
+require_relative "../tools/tool_index"
 require_relative "../log"
 require_relative "model_size"
 require_relative "outside"
@@ -147,14 +148,20 @@ module Samagotchi
 
       # +name+ as the acts_as of +entry+'s calls: nil for none, and for a
       # core tool or a tool another bundle registered (logged); the tool's
-      # own name is no alias either.
+      # own name is no alias either. chi's tool index (call_tool, source
+      # ToolIndex::SOURCE) skips the other-bundle check: its call_targets
+      # only name a tool one of its sources published (or a source-prefixed
+      # name, ToolIndex#claimed), so the registry is the wrong owner test,
+      # and a bundle tool sharing an MCP tool's name would otherwise take
+      # call_tool calls of that tool out of its mcp_* rules.
       def self.acts_as_of(name, entry, registry)
         name = name.to_s.strip
         return nil if name.empty? || name == entry.name
 
         other = registry[name]
         whose = if CORE_TOOLS.include?(name) || other&.core? then "a core tool"
-                elsif other && other.source != entry.source then "bundle #{other.source}'s tool"
+                elsif other && other.source != entry.source && entry.source != Tools::ToolIndex::SOURCE
+                  "bundle #{other.source}'s tool"
                 end
         return name unless whose
 

data/lib/samagotchi/host_config.rb

@@ -10,9 +10,7 @@ require_relative "reasoning_history"
 module Samagotchi
   # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
   # holds them by lowercased name; HostRegistry builds its HostEntry from
-  # one). #to_env_h writes every field in the shape of the
-  # SAMAGOTCHI_HOSTS_JSON override (ConfigFile.hosts_json_for_env), and
-  # .parse reads it back to an equal HostConfig.
+  # one).
   #
   # name: the lowercased entry name; host, port, scheme: where it is (from
   # url: when given); url: the configured url, nil when host/port; transport,
@@ -179,31 +177,5 @@ module Samagotchi
       nil
     end
     private_class_method :invalid
-
-    # The entry as a SAMAGOTCHI_HOSTS_JSON override carries it (string keys,
-    # unset fields left out); .parse(name, to_env_h) gives it back. A url
-    # entry travels as its url (host/port come from it); the API key stays
-    # in the environment.
-    # @return [Hash{String => Object}]
-    def to_env_h
-      location = url ? { "url" => url } : { "host" => host, "port" => port }
-      location.merge("transport" => transport&.to_s, "api" => api&.to_s, "api_key_env" => api_key_env,
-                     "auth" => (AUTH_SCHEMES.key(auth) if auth), "dialect" => dialect,
-                     "profile" => profile, "first_token_timeout" => first_token_timeout,
-                     "vision" => vision, "sampling" => sampling, "thinking" => thinking&.to_s,
-                     "reasoning_history" => reasoning_history&.to_s, "remote" => remote, "window_tokens" => window_tokens,
-                     "steer_cut_after" => steer_cut_after,
-                     "llm_context_strategy" => llm_context_strategy&.map(&:to_s),
-                     "llm_context_apply" => llm_context_apply&.to_s,
-                     "llm_context_budget_tokens" => llm_context_budget_tokens,
-                     "models" => models_config).compact
-    end
-
-    private
-
-    # hosts.<name>.models as written back (HostModel#to_config), nil when none.
-    def models_config
-      models.values.to_h { |m| [m.id, m.to_config] } unless models.nil? || models.empty?
-    end
   end
 end

data/lib/samagotchi/host_model.rb

@@ -103,13 +103,6 @@ module Samagotchi
                          .map { |info| HostModel::Row.new(id: info.id.to_s, configured: false, info: info) }
       end
     end
-
-    # The entry as written back to config (HostConfig#to_env_h): nil for a
-    # bare id.
-    def to_config
-      config = { "price" => price&.to_config, "served" => served }.compact
-      config unless config.empty?
-    end
   end
 
   # A listing row (HostModel.rows): id as the host lists it, else as

data/lib/samagotchi/kernel_loop.rb

@@ -21,6 +21,7 @@ require_relative "steer"
 require_relative "reasoning_history"
 require_relative "thought_stream_splitter"
 require_relative "tools/builtins"
+require_relative "tools/builtin_calls"
 require_relative "muted_memories"
 require_relative "tool_activity"
 require_relative "tool_runner"
@@ -1070,12 +1071,22 @@ module Samagotchi
     #
     # A tool the session's toolkit leaves out is a real one, so its error
     # does name it (deliberately, against the rule above): the model learns
-    # it exists and that only the user can load it.
-    def unknown_tool_error(name, layers)
+    # it exists, and how to reach it (call_tool, when the toolkit reaches
+    # it that way) or that only the user can load it. A call reached
+    # through call_tool (+via+) of a tool the toolkit declares is told to
+    # call it directly: the model's call_tool(tool: "chi/read") with read
+    # declared, or a hook's rewrite (a direct call can't carry via:).
+    def unknown_tool_error(name, layers, via: nil)
       names = @tools.names(layers: layers)
-      if @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
-        toolkit = @tools.toolkit&.name
-        "Error: #{name} isn't loaded in this session#{" (toolkit #{toolkit})" if toolkit} and can't be loaded from " \
+      toolkit = @tools.toolkit&.name
+      in_toolkit = " in this session#{" (toolkit #{toolkit})" if toolkit}"
+      if via && @tools.offered(name, layers: layers)
+        "Error: #{name} is declared#{in_toolkit}; call it directly. Available: #{names.join(", ")}"
+      elsif !via && @tools.respond_to?(:indexed) && @tools.indexed(name, layers: layers)
+        "Error: #{name} isn't declared#{in_toolkit}; call it with #{Tools::BuiltinCalls::VIA}(tool: \"chi/#{name}\", args: {…}) " \
+          "(find_tools gives its inputSchema). Available: #{names.join(", ")}"
+      elsif @tools.respond_to?(:left_out) && @tools.left_out(name, layers: layers)
+        "Error: #{name} isn't loaded#{in_toolkit} and can't be loaded from " \
           "here; only the user can (/toolkit add #{name}). Available: #{names.join(", ")}"
       elsif SHELL_LIKE_TOOL_NAMES.include?(name.to_s.downcase) && names.include?("execute")
         "Error: no such tool. Shell commands run with `execute` (same arguments)."
@@ -1085,9 +1096,15 @@ module Samagotchi
     end
 
     def dispatch(call)
-      entry = @tools.offered(call[:name], layers: llm_context_layers)
+      # A built-in reached through call_tool runs only while the toolkit
+      # reaches it that way (Registry#indexed); any other call by its name.
+      entry = if call[:via]
+                @tools.respond_to?(:indexed) ? @tools.indexed(call[:name], layers: llm_context_layers) : nil
+              else
+                @tools.offered(call[:name], layers: llm_context_layers)
+              end
       unless entry
-        result = unknown_tool_error(call[:name], llm_context_layers)
+        result = unknown_tool_error(call[:name], llm_context_layers, via: call[:via])
         return {
           output: result,
           activity: ToolActivity.tool_activity_event(call[:name], call, result, registry: @tools)

data/lib/samagotchi/llm/errors.rb

@@ -20,7 +20,8 @@ module Samagotchi
     # asking again could help.
     #
     #   ConnectionError  no answer (refused, reset, timeout); RetryExhausted,
-    #                    ConnectionRefused
+    #                    ConnectionRefused, TLSError (a handshake that can't
+    #                    work: certificate, host name, http vs https)
     #   RateLimited      429, with retry_after when the server says
     #   CreditsHeld      402 "… in-flight requests": credit reserved by other
     #                    requests; a RateLimited, retried after 20 s
@@ -271,6 +272,51 @@ module Samagotchi
       def summary = "can't reach host #{host}#{" at #{address}" if address} (connection refused) — is the server running?"
     end
 
+    # A TLS handshake that can't work however often it is tried: a
+    # certificate chi doesn't trust, a certificate for another name, or a
+    # server that doesn't speak TLS there (an https:// base_url on a plain
+    # HTTP port). Not retried. Any other OpenSSL::SSL::SSLError (an
+    # unexpected eof or a reset mid-handshake) is a network blip, retried.
+    class TLSError < ConnectionError
+      # problem => [pattern of the OpenSSL message, what to check]. The
+      # first match wins, so the host name comes before the general
+      # certificate check ("certificate verify failed (hostname mismatch)").
+      PROBLEMS = {
+        hostname: [/hostname mismatch|does not match the server certificate/i,
+                   "the certificate is for another name: check the host's base_url"],
+        certificate: [/certificate verify failed/i,
+                      "is its CA trusted? set SSL_CERT_FILE to a CA bundle that has it"],
+        scheme: [/wrong version number|packet length too long/i,
+                 "the server doesn't answer TLS there: should the host's base_url start with http://?"]
+      }.freeze
+
+      attr_reader :address, :problem, :reason
+
+      # The permanent problem an OpenSSL::SSL::SSLError's +message+ names
+      # (:hostname, :certificate, :scheme), or nil for a transient one.
+      def self.problem_for(message)
+        PROBLEMS.find { |_problem, (pattern, _hint)| pattern.match?(message.to_s) }&.first
+      end
+
+      # The OpenSSL reason without Ruby's "SSL_connect returned=1 errno=0
+      # peeraddr=… state=…: " prefix.
+      def self.reason_for(message)
+        message.to_s[/\bstate=[^:]*:\s*(.+)\z/m, 1] || message.to_s
+      end
+
+      def initialize(host:, problem:, reason:, address: nil, attempts: 1)
+        @address = address
+        @problem = problem
+        @reason = reason
+        super("#{host}: TLS failed#{" at #{address}" if address}: #{reason}", host: host, retryable: false,
+                                                                            attempts: attempts)
+      end
+
+      def summary
+        "can't reach host #{host}#{" at #{address}" if address} over TLS (#{reason}) — #{PROBLEMS.fetch(problem).last}"
+      end
+    end
+
     # A stream that showed nothing (no text, reasoning or tool call) within
     # the host's first-token limit. A queued request can stay open for many
     # minutes on keep-alive comments alone, which reset the read timeout.

data/lib/samagotchi/llm/http.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "openssl"
 require "uri"
 require_relative "../config"
 require_relative "../version"
@@ -31,9 +32,13 @@ module Samagotchi
       # the user, who can try again later.
       MAX_RETRY_AFTER = 60.0
 
+      # Errors that mean the request didn't get through (the probe treats
+      # them as "unreachable"). #retrying retries them, except a refused
+      # connection and a TLS error that can't work (.tls_problem).
       NETWORK_ERRORS = [
-        Timeout::Error, EOFError, SocketError, IO::TimeoutError,
-        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ETIMEDOUT
+        Timeout::Error, EOFError, SocketError, IO::TimeoutError, OpenSSL::SSL::SSLError,
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::ENETDOWN,
+        Errno::ETIMEDOUT, Errno::EPIPE, Errno::EADDRNOTAVAIL
       ].freeze
 
       # Requests of these purposes are the ones a turn waits on (or, for the
@@ -77,6 +82,13 @@ module Samagotchi
         NETWORK_ERRORS.any? { |klass| error.is_a?(klass) }
       end
 
+      # The permanent TLS problem +error+ is (TLSError::PROBLEMS: :certificate,
+      # :hostname, :scheme), or nil: not a TLS error, or a transient one
+      # (an unexpected eof or a reset mid-handshake) worth retrying.
+      def self.tls_problem(error)
+        error.is_a?(OpenSSL::SSL::SSLError) ? TLSError.problem_for(error.message) : nil
+      end
+
       # The ProviderError an SSE line carries (llama.cpp's `error:` event, a
       # `data:` line with an `error` object), or nil.
       def self.sse_error(line, host:)
@@ -278,6 +290,12 @@ module Samagotchi
             if e.is_a?(Errno::ECONNREFUSED)
               raise ConnectionRefused.new(host: @label, address: current[:address], attempts: attempts)
             end
+            # Nor is a handshake that can't work (an untrusted certificate,
+            # another name's, a plain HTTP server): it fails the same way.
+            if (problem = self.class.tls_problem(e))
+              raise TLSError.new(host: @label, address: current[:address], problem: problem,
+                                 reason: TLSError.reason_for(e.message), attempts: attempts)
+            end
 
             delay = current[:streamed] ? nil : @retry_policy.delay_for(attempts)
             raise RetryExhausted.new(attempts: attempts, last_error: e, label: @label) if delay.nil?

data/lib/samagotchi/llm_context_stale.rb

@@ -191,11 +191,17 @@ module Samagotchi
         id = entry[:tool_call_id].to_s
         matches = id.empty? ? [] : batch.select { |call_id, _| call_id.to_s == id }
         call = matches.one? ? matches.first.last : nil
+        call &&= Tools::BuiltinCalls.unwrap_saved(call, entry[:content])
         texts = call && refs.size == 1 ? ToolResponse.runs_named(entry[:content], [call[:name]]) : nil
         return texts ? [[refs.first, call, texts.first.text]] : []
       end
 
+      # A call_tool of a built-in ran as it: its run's lead names the
+      # built-in (BuiltinCalls.unwrap_saved).
       calls = batch.map(&:last)
+      calls = calls.zip(ToolResponse.runs(entry[:content], calls.size)).map do |call, run|
+        Tools::BuiltinCalls.unwrap_saved(call, run&.text)
+      end
       texts = ToolResponse.runs_named(entry[:content], calls.map { |call| call[:name] })
       return [] unless texts && texts.size == refs.size
 

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -24,6 +24,9 @@ module Samagotchi
     #     file: plugin.rb
     #     sha256: sha256:0a1b...
     #   requires_chi: ">= 0.1.28"   # optional — a Gem::Requirement for chi's VERSION
+    #   requires_chi_next: true     # optional, shipped bundles — ignored here:
+    #                          #   `rake release:bump` raises requires_chi to
+    #                          #   the released chi (docs/releasing.md)
     #   needs:                 # optional — outside commands the memories rely on
     #     - command: gh        #   (checked on PATH, never installed; docs/memory.md)
     #       why: reads PRs     #   optional

data/lib/samagotchi/model_price.rb

@@ -15,8 +15,8 @@ module Samagotchi
 
       values = raw.is_a?(Hash) ? raw.transform_keys(&:to_s).slice(*ModelPrice::KEYS) : nil
       valid = values && values.key?("input") && values.key?("output") &&
-              # YAML's .inf and .nan are Floats too: JSON can't carry them
-              # (hosts_json_for_env would drop every host) and NaN poisons the sums.
+              # YAML's .inf and .nan are Floats too: an infinite price
+              # isn't one, and NaN poisons the sums.
               values.values.all? { |v| v.is_a?(Numeric) && v.finite? && !v.negative? }
       unless valid
         warn_once "Warning: #{where}.price needs input and output, each a number >= 0 (USD per 1M tokens); ignored"
@@ -45,8 +45,6 @@ module Samagotchi
       ((uncached * input) + (cached_tokens * cache_read) + (cache_write_tokens * cache_write) +
        (completion_tokens * output)) / 1e6
     end
-
-    def to_config = to_h.transform_keys(&:to_s)
   end
 
   # The keys a price may hold (config validation checks them too).

data/lib/samagotchi/session_metrics.rb

@@ -852,6 +852,9 @@ module Samagotchi
 
         called_as = event.dig(:activity, :called_as)
         active[:called_as] = called_as.to_s if called_as
+        # Reached through call_tool: the reloaded row says so (not an alias).
+        via = event.dig(:activity, :via)
+        active[:via] = via.to_s if via
         # A grep that found nothing (ok): the reloaded web row says "no match".
         active[:no_match] = true if event.dig(:activity, :no_match)
         finish_tool_record(active, status.empty? ? "ok" : status, waited_ms: event[:waited_ms].to_i)
@@ -861,7 +864,7 @@ module Samagotchi
     # Caller holds the mutex.
     def finish_tool_record(active, status, waited_ms: 0)
       record = active.slice(
-        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :no_match, :started_at
+        :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :started_at
       ).merge(
         status: status,
         completed_at: now.iso8601(3),

data/lib/samagotchi/system_prompt.rb

@@ -331,7 +331,9 @@ module Samagotchi
     # The tools the session's toolkit leaves out, named once right after the
     # base prompt: sessions on another toolkit already differ at the tools,
     # and nothing later (a memory write) moves it. nil when none are (full):
-    # the prompt is what it was before toolkits.
+    # the prompt is what it was before toolkits. The ones call_tool reaches
+    # and the ones the toolkit removes (only the user brings those back)
+    # get a sentence each; with call_tool not declared, one list.
     def not_loaded_line(layers)
       registry = @tools_lookup.call
       return nil unless registry.respond_to?(:left_out_names)
@@ -339,8 +341,22 @@ module Samagotchi
       names = registry.left_out_names(layers: layers)
       return nil if names.empty?
 
-      "Not loaded in this session (toolkit #{registry.toolkit&.name}): #{names.join(", ")}. " \
-        "Only the user can load one (/toolkit add <name>)."
+      toolkit = "(toolkit #{registry.toolkit&.name})"
+      reachable = registry.reachable_names(layers: layers)
+      if reachable.empty?
+        return "Not loaded in this session #{toolkit}: #{names.join(", ")}. Only the user can load one (/toolkit add <name>)."
+      end
+
+      removed = names - reachable
+      # find_tools removed (call_tool still works): the route without it.
+      how = if removed.include?("find_tools") then "Call one with call_tool(tool: \"chi/<name>\", args: {…})."
+            else "Search them with find_tools; call one with call_tool."
+            end
+      line = "Not declared in this session #{toolkit}: #{reachable.join(", ")}. #{how}"
+      return line if removed.empty?
+
+      "#{line} Removed #{toolkit}: #{removed.join(", ")}. Only the user can load #{removed.size == 1 ? "it" : "one"} " \
+        "(/toolkit add <name>)."
     end
 
     def with_tail_declarations(prompt, chat:, layers:)

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -34,7 +34,8 @@ module Samagotchi
       # What a tool line says the call did: the model's description of a
       # command (": List the specs") in place of its cut params, else the
       # params, dim; then, dim, the name the model called it by when that was
-      # an alias's (" (called as bash)").
+      # an alias's (" (called as bash)"), or the tool it was reached through
+      # (" (via call_tool)").
       def tool_params_suffix(activity)
         description = activity[:description].to_s.strip
         params = activity[:params].to_s.strip
@@ -43,7 +44,9 @@ module Samagotchi
                  else ""
                  end
         called_as = activity[:called_as].to_s
-        called_as.empty? ? suffix : "#{suffix}#{paint(" (called as #{called_as})", 90)}"
+        suffix = "#{suffix}#{paint(" (called as #{called_as})", 90)}" unless called_as.empty?
+        via = activity[:via].to_s
+        via.empty? ? suffix : "#{suffix}#{paint(" (via #{via})", 90)}"
       end
 
       # Green ok, yellow stopped (a wait the user's Stop ended), red the rest.

data/lib/samagotchi/tool_activity.rb

@@ -56,6 +56,9 @@ module Samagotchi
       # The name the model used when an alias ran a built-in (called_as: "bash"
       # for an execute), for a UI that shows it.
       event[:called_as] = call[:called_as] if call.is_a?(Hash) && call[:called_as]
+      # The tool it was reached through (via: "call_tool", a built-in the
+      # toolkit doesn't declare): not an alias, the model named it.
+      event[:via] = call[:via] if call.is_a?(Hash) && call[:via]
       # The model's own words for a command, which the TUI's tool line
       # shows in place of the cut params.
       description = command_description(tool_name, call)

data/lib/samagotchi/tool_row_fields.rb

@@ -23,7 +23,7 @@ module Samagotchi
   # params and label stay where they are: their sources differ per path
   # (the registry's preview, a plugin's label, the saved shown params).
   module ToolRowFields
-    ACTIVITY_KEYS = %i[title called_as].freeze
+    ACTIVITY_KEYS = %i[title called_as via].freeze
     EVENT_KEYS = %i[view ref refs].freeze
     KEYS = (ACTIVITY_KEYS + EVENT_KEYS).freeze
 
@@ -33,13 +33,15 @@ module Samagotchi
     #   relative to it when inside it)
     # @return [Hash] title (a few words: a project-relative path, a command
     #   without its "cd … &&"), called_as (the name the model called it by
-    #   when that was an alias's: bash), view (ToolView: the full command)
+    #   when that was an alias's: bash), via (the tool it was reached
+    #   through: call_tool), view (ToolView: the full command)
     #   and ref (FileRef: the file a file tool touched), each only when
     #   there is one
     def for(tool_name, call, cwd:)
       {
         title: ToolActivity.tool_title(tool_name, call, cwd: cwd),
         called_as: call[:called_as],
+        via: call[:via],
         view: ToolView.for(tool_name, call)&.to_h,
         ref: FileRef.for(tool_name, call, cwd: cwd)&.to_h
       }.compact

data/lib/samagotchi/tool_runner.rb

@@ -47,6 +47,10 @@ module Samagotchi
     #   file (EditPreview.change; also on tool_call_completed, never in the
     #   model's output)
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
+      # A call_tool of one of chi's own tools runs as that tool, from here
+      # on (the gate, the row, the result): rules, approvals and hooks see
+      # the real call, with via: (Tools::ToolIndex#unwrap).
+      call = unwrapped(call)
       params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
       # The gate runs first, so tool_call_started shows the call that runs.
       # A tool the session's toolkit leaves out skips it: no before_tool_call
@@ -60,7 +64,7 @@ module Samagotchi
       started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
                   tool: call[:name], call: call.dup, params: params }
       started[:label] = label if label
-      # Its row fields (ToolRowFields: title, called_as, view, ref, and a
+      # Its row fields (ToolRowFields: title, called_as, via, view, ref, and a
       # plugin tool's refs); the worker runs in its session's working
       # directory.
       fields = ToolRowFields.for(call[:name], call, cwd: Dir.pwd)
@@ -268,12 +272,29 @@ module Samagotchi
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 
-    # A real tool the session's toolkit leaves out of this turn.
+    def layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
+
+    # The call its tool's entry unwraps it to (call_tool on a built-in),
+    # else the call as it is. One that fails runs as it is: call_tool then
+    # refuses a built-in (fail closed).
+    def unwrapped(call)
+      registry = tools
+      return call unless registry.respond_to?(:offered) && !call[:name].nil?
+
+      registry.offered(call[:name], layers: layers)&.unwrap&.call(call, layers) || call
+    rescue StandardError => e
+      Log.warn(:turn, "tool_unwrap_failed", tool: call[:name].to_s, error: "#{e.class}: #{e.message}")
+      call
+    end
+
+    # A call that can't run in this turn as it is, by its name: a real tool
+    # the session's toolkit leaves out, or one reached through call_tool
+    # (via:) that the toolkit doesn't reach that way (a hook's rewrite).
     def left_out?(call)
       registry = tools
       return false unless registry.respond_to?(:left_out) && !call[:name].nil?
+      return registry.indexed(call[:name], layers: layers).nil? if call[:via]
 
-      layers = @kernel.respond_to?(:llm_context_layers) ? @kernel.llm_context_layers : []
       !registry.left_out(call[:name], layers: layers).nil?
     end