samagotchi 0.68.0 → 0.70.0

data/lib/samagotchi/tool_output_cut.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require_relative "tool_output_files"
+
+module Samagotchi
+  # How ToolRunner cuts a tool's output that is longer than
+  # max_tool_output_chars, by the tool's policy (POLICIES, by its built-in
+  # name; any other tool gets :head).
+  #
+  # :head keeps the first chars and ends with head_line ("[cut: N of M
+  # chars; read it in parts]"): read (which has line ranges) and every tool
+  # with no policy of its own.
+  #
+  # :head_tail_file (execute) keeps a short head and a long tail, whole
+  # lines, with one gap line between them, and saves the whole output
+  # (ToolOutputFiles, through the caller's +save+): a test run's verdict and
+  # an error are at the end. The gap line names the saved file and the lines
+  # left out of it, so the model reads or rg's it instead of running the
+  # command again. execute's stdout and stderr are cut each on its own
+  # (stdout gets about two thirds of the room), its exit line always kept.
+  # The cut text still fits the cap, and comes from the content alone (no
+  # clock): the same output gives the same text.
+  #
+  # :head_tail_ref (task_wait, delegate, delegate_result) cuts the same
+  # way, as one block, and saves nothing: the whole is already in a file (a
+  # task's log, the child's reply in its output/ folder), which the tool
+  # gave with its text (Tools::RefText) and the gap line names.
+  module ToolOutputCut
+    POLICIES = { "execute" => :head_tail_file, "task_wait" => :head_tail_ref, "delegate" => :head_tail_ref,
+                 "delegate_result" => :head_tail_ref }.freeze
+
+    # What a :head_tail_ref tool's file holds, for its gap line.
+    REF_WHAT = { "task_wait" => "the task's whole output", "delegate" => "the child's whole reply",
+                 "delegate_result" => "the child's whole reply" }.freeze
+
+    # A head cut's last line (head_line), as LLMContextStale recognizes a
+    # partial read by it. Kept in sync with head_line by its spec.
+    HEAD_CUT = /\[cut: \d+ of \d+ chars; read it in parts\]\z/
+
+    # The head's chars at most (execute.cut_head_chars): never more than a
+    # quarter of the room; the tail gets the rest.
+    HEAD_CHARS = 1000
+    # A tail shorter than this isn't worth it: the cap is too small, and
+    # the output gets the head cut.
+    MIN_TAIL = 200
+
+    # An execute that didn't finish: stopped, killed at the limit or
+    # handed over (its result starts with an "Error:" or a "Still running"
+    # line after the lead), or with no exit line last.
+    UNFINISHED = /\A(?:ran as: [^\n]*\n)?\[execute\]\n(?:Error: |Still running at the )/
+
+    # The marks of a text that is already a head-and-tail preview (execute's
+    # own above execute.truncate_at_bytes): its saved copy isn't the whole
+    # output.
+    PREVIEW_MARK = "[TRUNCATED_PREVIEW_HEAD]"
+    # execute's blocks (Tools::Execute#call): stdout, stderr, then the exit
+    # line last (a hint in brackets may follow it). A killed or handed-over
+    # command has none: its output isn't all there is.
+    STDOUT_LABEL = "\nstdout:\n"
+    STDERR_LABEL = "\nstderr:\n"
+    EXIT_LINE = /\nexit: -?\d+[^\n]*(?:\n\([^\n]*\))?\z/
+
+    # The share of the room stdout gets when both blocks are cut.
+    STDOUT_SHARE = Rational(2, 3)
+
+    # A cut part: [from, length] of the output.
+    Block = Data.define(:from, :length) do
+      def to = from + length
+    end
+
+    module_function
+
+    # @param tool [String, nil] the call's tool name
+    # @return [Symbol] its policy
+    def policy(tool) = POLICIES.fetch(tool.to_s, :head)
+
+    # +output+ cut to +cap+ chars by +tool+'s policy.
+    # @param save [#call, nil] (text, dry:) → ToolOutputFiles::Saved, or a
+    #   String saying why it wasn't saved ("no session", "Errno::ENOSPC");
+    #   dry: true only says where it would go. It writes only once the
+    #   head-and-tail cut is known to fit the cap with that file's gap
+    #   line: a cut that falls back to the head cut saves nothing.
+    # @param head_chars [Integer] execute.cut_head_chars
+    # @return [Array(String, Object)] the text the model gets, and what
+    #   +save+ returned (nil when it wasn't called)
+    # @param ref [String, nil] :head_tail_ref: the file the whole text is in
+    # @param ref_stderr [String, nil] :head_tail_ref: its stderr's file, if apart
+    def apply(output, cap:, tool:, save: nil, ref: nil, ref_stderr: nil, head_chars: HEAD_CHARS)
+      kind = policy(tool)
+      return [head(output, cap), nil] if kind == :head || cap < MIN_TAIL * 3
+
+      if kind == :head_tail_ref
+        text = head_tail(output, cap: cap, blocks: [Block.new(from: 0, length: output.length)], head_chars: head_chars,
+                                 gap: RefGap.new(output, ref, REF_WHAT.fetch(tool.to_s, "the whole output"),
+                                                 stderr: ref_stderr))
+        return [text || head(output, cap), nil]
+      end
+
+      blocks = execute_blocks(output)
+      planned = save ? save.call(output, dry: true) : "no session"
+      text = head_tail(output, cap: cap, blocks: blocks, head_chars: head_chars, gap: FileGap.new(output, planned))
+      return [head(output, cap), nil] unless text
+      return [text, planned] unless planned.is_a?(ToolOutputFiles::Saved)
+
+      saved = save.call(output)
+      return [text, saved] if saved.is_a?(ToolOutputFiles::Saved)
+
+      # The write failed: the line says so instead, if that still fits.
+      text = head_tail(output, cap: cap, blocks: blocks, head_chars: head_chars, gap: FileGap.new(output, saved))
+      [text || head(output, cap), text ? saved : nil]
+    end
+
+    def unfinished?(output) = output.match?(UNFINISHED) || !output.match?(EXIT_LINE)
+
+    # +output+ as a web row keeps it, at most +cap+ chars (a reload's
+    # MessageParts, the Bridge's snapshot): a read's head (its view numbers
+    # the lines from the first), any other tool's head and tail with a gap
+    # line, as the model's cut keeps a test run's verdict and exit line.
+    def preview(output, cap:, tool:)
+      return output if output.length <= cap
+      return output[0, cap] if tool.to_s == "read"
+
+      head_tail(output, cap: cap, blocks: [Block.new(from: 0, length: output.length)], head_chars: HEAD_CHARS,
+                                  gap: RefGap.new(output, nil, nil)) || output[0, cap]
+    end
+
+    # +output+ cut to +cap+ chars, the cut line included: the model knows
+    # what it didn't get. A cap smaller than the line keeps +cap+ chars and
+    # the line goes past it.
+    def head(output, cap)
+      keep = cap - head_line(cap, output.length).length
+      keep = cap unless keep.positive?
+      "#{output[0, keep]}#{head_line(keep, output.length)}"
+    end
+
+    def head_line(kept, total)
+      "\n[cut: #{kept} of #{total} chars; read it in parts]"
+    end
+
+    # +output+ with each of +blocks+ that doesn't fit its share of the room
+    # cut to its head and tail, a gap line between them (the first cut's
+    # line +gap+.line, the next ones' +gap+.short). nil when the cap leaves
+    # too little room.
+    def head_tail(output, cap:, blocks:, head_chars:, gap:)
+      fixed = output.length - blocks.sum(&:length)
+      # Room for the gap lines (their longest numbers) and a newline each.
+      room = cap - fixed - (gap.line_max.length + 2) - (blocks.size > 1 ? gap.short_max.length + 2 : 0)
+      shares = shares(blocks.map(&:length), room)
+      return nil unless shares
+
+      text = +""
+      at = 0
+      first = true
+      blocks.zip(shares).each do |block, share|
+        text << output[at...block.from]
+        at = block.to
+        body = output[block.from, block.length]
+        if body.length <= share
+          text << body
+          next
+        end
+
+        shown = cut_block(body, share, head_chars)
+        return nil unless shown
+
+        head_part, tail_part = shown
+        left_out = Block.new(from: block.from + head_part.length, length: body.length - head_part.length - tail_part.length)
+        text << head_part
+        text << "\n" unless head_part.end_with?("\n") || head_part.empty?
+        text << (first ? gap.line(left_out) : gap.short(left_out)) << "\n" << tail_part
+        first = false
+      end
+      text << output[at..]
+      text.length <= cap ? text : nil
+    end
+
+    # The room each block gets: stdout STDOUT_SHARE when both need cutting,
+    # a block that needs less gives the rest to the other. nil when there
+    # isn't room for a useful tail.
+    def shares(lengths, room)
+      return nil if room < MIN_TAIL
+      return [room] if lengths.size == 1
+
+      first = (room * STDOUT_SHARE).floor
+      second = room - first
+      if lengths[1] < second
+        [room - lengths[1], lengths[1]]
+      elsif lengths[0] < first
+        [lengths[0], room - lengths[0]]
+      else
+        [first, second]
+      end
+    end
+
+    # +body+'s head and tail within +share+ chars, each snapped to whole
+    # lines when that keeps at least half of it. nil when the tail would
+    # be shorter than MIN_TAIL.
+    def cut_block(body, share, head_chars)
+      head_size = [head_chars, share / 4].min
+      tail_size = share - head_size
+      return nil if tail_size < MIN_TAIL
+
+      head_part = body[0, head_size]
+      newline = head_part.rindex("\n")
+      head_part = head_part[0, newline + 1] if newline && newline + 1 >= head_size / 2
+      tail_part = body[-tail_size..]
+      newline = tail_part.index("\n")
+      tail_part = tail_part[(newline + 1)..] if newline && tail_part.length - newline - 1 >= tail_size / 2
+      [head_part, tail_part]
+    end
+
+    # execute's stdout and stderr bodies, each cut on its own; any other
+    # text (no "stdout:"/"stderr:" block: an error, a hand-over) is one.
+    def execute_blocks(output)
+      ends = output.match(EXIT_LINE)&.begin(0) || output.length
+      stdout_at = output.index(STDOUT_LABEL)
+      stderr_at = output.rindex(STDERR_LABEL, ends - STDERR_LABEL.length)
+      stderr_at = nil if stderr_at && stdout_at && stderr_at < stdout_at
+      blocks = []
+      if stdout_at
+        from = stdout_at + STDOUT_LABEL.length
+        blocks << Block.new(from: from, length: [(stderr_at || ends) - from, 0].max)
+      end
+      blocks << Block.new(from: stderr_at + STDERR_LABEL.length, length: ends - stderr_at - STDERR_LABEL.length) if stderr_at
+      blocks.empty? ? [Block.new(from: 0, length: output.length)] : blocks
+    end
+
+    # The gap line of a :head_tail_ref cut: the file the whole text is in.
+    class RefGap
+      def initialize(output, ref, what, stderr: nil)
+        @output = output
+        @ref = ref.to_s
+        @what = what
+        @stderr = stderr.to_s
+      end
+
+      def line(left_out)
+        also = @stderr.empty? ? "" : " (its stderr in #{@stderr})"
+        where = @ref.empty? ? "" : "; #{@what} is in #{@ref}#{also}: read it with start_line/end_line or rg it"
+        "[cut: #{left_out.length} of #{@output.length} chars not shown#{where}]"
+      end
+
+      def short(left_out) = "[cut: #{left_out.length} chars not shown]"
+      def line_max = line(Block.new(from: 0, length: @output.length))
+      def short_max = short(Block.new(from: 0, length: @output.length))
+    end
+
+    # The gap lines of a :head_tail_file cut: where the whole output is
+    # saved, and which of its lines the cut left out.
+    class FileGap
+      # @param saved [ToolOutputFiles::Saved, String] the saved file, or
+      #   why there is none
+      def initialize(output, saved)
+        @output = output
+        @saved = saved.is_a?(String) ? nil : saved
+        @reason = saved.is_a?(String) ? saved : nil
+      end
+
+      # The first cut's line.
+      def line(left_out)
+        return "[cut: #{left_out.length} of #{@output.length} chars not shown; #{unsaved_note}]" unless @saved
+
+        "[cut: #{lines_text(left_out)} of the saved file not shown (#{left_out.length} of #{@output.length} chars); " \
+          "#{saved_note}]"
+      end
+
+      # A further cut's line, the file named by the first.
+      def short(left_out)
+        return "[cut: #{left_out.length} chars not shown]" unless @saved
+
+        "[cut: #{lines_text(left_out)} of the saved file not shown (#{left_out.length} chars)]"
+      end
+
+      # The longest line and short line it can write (budgeting).
+      def line_max = line(widest)
+      def short_max = short(widest)
+
+      private
+
+      def widest = Block.new(from: 0, length: @output.length)
+
+      def lines_text(left_out)
+        return "lines #{lines_total}-#{lines_total}" if left_out.from.zero? && left_out.length == @output.length
+
+        first = @output[0, left_out.from].count("\n") + 1
+        last = @output[0, left_out.to].count("\n")
+        last += 1 unless left_out.to.zero? || @output[left_out.to - 1] == "\n"
+        "lines #{first}-#{[last, first].max}"
+      end
+
+      def lines_total = @saved.lines
+
+      def where = "#{@saved.path} (#{@saved.bytes} bytes, #{@saved.lines} lines)"
+
+      def saved_note
+        if @output.include?(PREVIEW_MARK)
+          "this preview is saved in #{where}; the full output wasn't kept: read the preview with " \
+            "start_line/end_line or rg it"
+        elsif ToolOutputCut.unfinished?(@output)
+          "the output it printed is saved in #{where}: read it with start_line/end_line or rg it"
+        else
+          "the whole output is saved in #{where}: read it with start_line/end_line or rg it; don't rerun the command"
+        end
+      end
+
+      def unsaved_note
+        "the whole output wasn't saved (#{@reason}); to look past this, rerun with the output sent to a file " \
+          "(cmd > /tmp/out.txt 2>&1) and read that"
+      end
+    end
+  end
+end

data/lib/samagotchi/tool_output_files.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require_relative "atomic_file"
+
+module Samagotchi
+  # The whole output of a tool call ToolRunner cut (ToolOutputCut's
+  # :head_tail_file), saved in the session's folder, tool_output/
+  # (sessions/<id>/tool_output/; not output/, the session's reply outbox),
+  # so the model reads or rg's it instead of running the command again.
+  #
+  # The name comes from the content (<tool>-<sha256[0,12]>.txt): the same
+  # output gives the same path, so the cut text is the same each time
+  # (loop-guard's repeat check, the prompt cache). The files go with the
+  # session folder; a session keeps its newest MAX_FILES.
+  module ToolOutputFiles
+    DIR = "tool_output"
+    MAX_FILES = 50
+
+    # Where a saved output is, and its size.
+    Saved = Data.define(:path, :bytes, :lines)
+
+    module_function
+
+    # @param session_dir [String] the session's folder (Session.session_dir)
+    # @param text [String] the output, saved byte for byte
+    # @param tool [String] the tool's name, the file name's start
+    # @return [Saved]
+    # @raise [SystemCallError] when it can't be written
+    def save(session_dir, text, tool:)
+      path = planned(session_dir, text, tool: tool).path
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir)
+      # Already there (the same output again): newest now, not rewritten.
+      # An empty one (cut short) is written again.
+      if File.size?(path)
+        FileUtils.touch(path)
+      else
+        AtomicFile.write(path, text)
+      end
+      prune(dir)
+      planned(session_dir, text, tool: tool)
+    end
+
+    # Where #save would put +text+, and its size, with nothing written: the
+    # cut checks its gap line fits before anything is saved.
+    # @return [Saved]
+    def planned(session_dir, text, tool:)
+      path = File.join(session_dir, DIR, "#{file_tool(tool)}-#{Digest::SHA256.hexdigest(text)[0, 12]}.txt")
+      Saved.new(path: path, bytes: text.bytesize, lines: line_count(text))
+    end
+
+    # The lines a text has, a last line with no newline counted.
+    def line_count(text)
+      text.count("\n") + (text.empty? || text.end_with?("\n") ? 0 : 1)
+    end
+
+    # A tool name safe in a file name (a plugin's or an MCP tool's).
+    def file_tool(tool)
+      name = tool.to_s.downcase.gsub(/[^a-z0-9_-]/, "_")
+      name.empty? ? "tool" : name
+    end
+
+    # Keeps the newest MAX_FILES files of +dir+, by mtime.
+    def prune(dir)
+      files = Dir.glob(File.join(dir, "*.txt"))
+      return if files.size <= MAX_FILES
+
+      files.sort_by { |f| [-File.mtime(f).to_f, f] }.drop(MAX_FILES).each { |f| FileUtils.rm_f(f) }
+    end
+  end
+end

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

@@ -7,6 +7,9 @@ require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
 require_relative "edit_preview"
+require_relative "tool_output_cut"
+require_relative "tool_output_files"
+require_relative "tools/output_guardrails"
 require_relative "tools/tool_path"
 require_relative "memory_bundle/index_sync"
 require_relative "memory_bundle/index_size"
@@ -16,8 +19,8 @@ module Samagotchi
   # tool_call_completed events, the guardrail gate (before_tool_call hooks
   # and their veto), dispatch through KernelLoop, the after_tool_call hook
   # and the output cap. Both loops feed the model `capped_output:` (cut to
-  # the cap with a "[cut: N of M chars …]" line), the text the event and
-  # the hook get too.
+  # the cap by the tool's ToolOutputCut policy, with a "[cut: …]" line),
+  # the text the event and the hook get too.
   class ToolRunner
     # More images in one result are left out, each with a line (a tool
     # that returns many screenshots can't flood the context).
@@ -38,6 +41,7 @@ module Samagotchi
 
     # @param call_index [Integer] 1-based position of the call in its batch
     # @return [Hash] output:, capped_output:, truncated:, activity:,
+    #   output_file: (the saved whole output of a cut execute result),
     #   images: (refs) when the tool returned images the model gets to see, and
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
@@ -47,6 +51,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 +68,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)
@@ -105,7 +113,8 @@ module Samagotchi
         output = "#{changed}\n#{output}"
       end
       truncated = !max_tool_output_chars.nil? && output.length > max_tool_output_chars
-      capped = truncated ? cut(output, max_tool_output_chars) : output
+      capped, saved = truncated ? cut(call, output, max_tool_output_chars, result) : output
+      output_file = saved.path if saved.is_a?(ToolOutputFiles::Saved)
 
       # The call's outcome as its activity line has it (worked out from the
       # full output: ok, error, blocked, stopped); a dispatcher that raised
@@ -116,6 +125,7 @@ module Samagotchi
       completed[:images] = images if images&.any?
       completed[:diff] = diff if diff
       completed[:waited_ms] = waited_ms if waited_ms
+      completed[:output_file] = output_file if output_file
       # Also here: a UI that missed the start (a replay gap) builds its row
       # from this event (its title is in the activity).
       completed.merge!(fields.slice(*ToolRowFields::EVENT_KEYS))
@@ -131,22 +141,50 @@ module Samagotchi
       run[:shown_label] = label if label
       run[:refs] = refs unless refs.empty?
       run[:diff] = diff if diff
+      run[:output_file] = output_file if output_file
       run
     end
 
     private
 
-    # +output+ cut to +cap+ chars, the cut line included: the model knows
-    # what it didn't get. A cap smaller than the line keeps +cap+ chars and
-    # the line goes past it.
-    def cut(output, cap)
-      keep = cap - cut_line(cap, output.length).length
-      keep = cap unless keep.positive?
-      "#{output[0, keep]}#{cut_line(keep, output.length)}"
+    # +output+ cut to +cap+ by its tool's policy (ToolOutputCut); an
+    # execute result keeps its tail too, its whole output saved in the
+    # session's folder.
+    # @param result [Hash] the dispatch's: its ref_path is the file the
+    #   whole text is in (a task's log, a child's reply: Tools::RefText),
+    #   for task_wait and delegate; ref_stderr_path, a task's stderr log
+    # @return [Array(String, Object)] the text, and the saved file (or why
+    #   there is none) when it was cut that way
+    def cut(call, output, cap, result)
+      ToolOutputCut.apply(output, cap: cap, tool: call[:name], save: ->(text, dry: false) { save_output(call, text, dry: dry) },
+                                  ref: result[:ref_path], ref_stderr: result[:ref_stderr_path],
+                                  head_chars: Tools::OutputGuardrails.config_positive_int("execute.cut_head_chars",
+                                                                                          ToolOutputCut::HEAD_CHARS))
     end
 
-    def cut_line(kept, total)
-      "\n[cut: #{kept} of #{total} chars; read it in parts]"
+    # The whole output in the session's tool_output folder
+    # (ToolOutputFiles), or why it isn't saved: no session (a bare kernel)
+    # or the error's class. Never fails the call. +dry+: where it would go,
+    # nothing written (ToolOutputFiles.planned).
+    # @return [ToolOutputFiles::Saved, String]
+    def save_output(call, text, dry: false)
+      dir = session_dir
+      return "no session" if dir.to_s.empty?
+      return ToolOutputFiles.planned(dir, text, tool: call[:name]) if dry
+
+      ToolOutputFiles.save(dir, text, tool: call[:name])
+    rescue SystemCallError => e
+      Log.warn(:turn, "tool_output_save_failed", tool: call[:name], error: e.class.name)
+      e.class.name
+    end
+
+    # The session's folder (KernelLoop#session_dir), nil for a bare kernel
+    # or a lookup that failed.
+    def session_dir
+      @kernel.respond_to?(:session_dir) ? @kernel.session_dir&.call : nil
+    rescue StandardError => e
+      Log.warn(:turn, "tool_output_save_failed", error: e.class.name)
+      nil
     end
 
     # edit/write only: the file just before the call runs. The row diffs it
@@ -268,12 +306,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
 

data/lib/samagotchi/toolkit.rb

@@ -25,17 +25,19 @@ module Samagotchi
     # The plain form the snapshot and the web carry.
     def to_h = { name: name, add: add, remove: remove }
 
-    # This toolkit with +tool+ declared (/toolkit add): a tool it removed
-    # comes out of +remove+ (back to its kit's), any other goes into +add+.
+    # This toolkit with +tool+ declared (/toolkit add): out of +remove+
+    # and into +add+, whatever its kit says (an add after a remove
+    # declares it).
     def adding(tool)
       tool = tool.to_s
-      remove.include?(tool) ? with(remove: remove - [tool]) : with(add: (add + [tool]).uniq)
+      with(remove: remove - [tool], add: (add + [tool]).uniq)
     end
 
-    # This toolkit with +tool+ left out (/toolkit remove), the other way.
+    # This toolkit with +tool+ removed (/toolkit remove), the other way: a
+    # remove is hard (call_tool can't reach it either), also after an add.
     def removing(tool)
       tool = tool.to_s
-      add.include?(tool) ? with(add: add - [tool]) : with(remove: (remove + [tool]).uniq)
+      with(add: add - [tool], remove: (remove + [tool]).uniq)
     end
 
     # How the UIs name it: "lean", "lean +web_fetch -memory_write".
@@ -66,21 +68,31 @@ module Samagotchi
 
     # A toolkit as a session's next turn would declare it (Engine
     # #toolkit_explained): +toolkit+ as saved, +resolved+, the Registry
-    # +declared+ entries and the names it leaves out (+left_out+), and
-    # whether that isn't what the Registry declares now (+pending+: it
+    # +declared+ entries and the names it leaves out (+left_out+): the ones
+    # call_tool reaches (+reachable+) and the ones it removes (+removed+);
+    # and whether that isn't what the Registry declares now (+pending+: it
     # applies at the next turn's start).
-    Explained = Data.define(:toolkit, :resolved, :declared, :left_out, :pending) do
-      # What the prompt carries of it: the declared names and, when it
-      # leaves tools out, the kit name the not-loaded line gives. Two equal
+    Explained = Data.define(:toolkit, :resolved, :declared, :left_out, :reachable, :removed, :pending) do
+      def initialize(toolkit:, resolved:, declared:, left_out:, pending:, reachable: [], removed: [])
+        super
+      end
+
+      # What the prompt carries of it: the declared names, the reachable
+      # and removed ones (the not-loaded line, find_tools' chi line) and,
+      # when either list has any, the kit name the line gives. Two equal
       # keys build the same prompt (/toolkit's "no change", its cost).
-      def prompt_key = [declared.map(&:name), left_out.empty? ? nil : resolved.name]
+      def prompt_key
+        [declared.map(&:name), reachable, removed, reachable.empty? && removed.empty? ? nil : resolved.name]
+      end
 
       # What the UIs show (the snapshot, command_ran): nil when it declares
       # every tool on full (full, full +delegate), which has no chip.
+      # +left_out+ is +reachable+ and +removed+ together.
       def summary
         return nil if toolkit.name == Toolkit::FULL && left_out.empty? && resolved.fallback.nil?
 
-        { name: toolkit.name, label: toolkit.label, left_out: left_out, fallback: resolved.fallback }
+        { name: toolkit.name, label: toolkit.label, left_out: left_out, reachable: reachable, removed: removed,
+          fallback: resolved.fallback }
       end
     end
 
@@ -111,8 +123,9 @@ module Samagotchi
       Kit.new(name: FULL, tools: :all),
       Kit.new(name: LEAN, tools: LEAN_TOOLS),
       # A delegate child: it reports to its parent (send_note; the
-      # delegated-by line names it) and leaves memory writes to it.
-      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write])
+      # delegated-by line names it) and leaves memory writes to it, and
+      # starts no children of its own (removed: not even through call_tool).
+      Kit.new(name: CHILD, base: LEAN, add: %w[send_note], remove: %w[memory_write delegate delegate_result])
     ].to_h { |kit| [kit.name, kit] }.freeze
 
     # What a toolkit declares, the Registry's filter: every built-in