samagotchi 0.154.1 → 0.155.0

data/lib/samagotchi/llm/backend.rb

@@ -19,9 +19,11 @@ module Samagotchi
     # in +messages+ (Engine#run_turn resume_from:); the replies from there on
     # keep the model's reasoning (thought blocks), as within one run. nil:
     # the run starts here, as every other turn's does.
+    # +context+: the run's turn (TurnContext, Engine#generate's), handed down
+    # the tool path explicitly; nil: the backend's own (a bare kernel's).
     class ModelBackend
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
         raise NotImplementedError, "#{self.class}#complete must be implemented"
       end
     end

data/lib/samagotchi/llm/chat_loop.rb

@@ -24,7 +24,7 @@ require_relative "../tool_runner"
 require_relative "../tool_response"
 require_relative "../tool_ids"
 require_relative "../tool_declarations"
-require_relative "../tools/deferred_tools"
+require_relative "../tools/tool_surface"
 require_relative "../tool_loads"
 require_relative "../vision_context"
 require_relative "../log"
@@ -79,8 +79,11 @@ module Samagotchi
       #   prompt's part every session shares (SystemPrompt#stable_length), or nil
       # @param sleeper [#call, nil] waits the given seconds before a dropped
       #   stream's step is asked again (specs pass one that doesn't sleep)
-      def initialize(kernel:, adapter: nil, stable_length: nil, sleeper: nil)
+      # @param context [TurnContext, nil] the turn its helpers read before any
+      #   #complete (a bench building wire messages); a run's replaces it
+      def initialize(kernel:, adapter: nil, stable_length: nil, sleeper: nil, context: nil)
         @kernel = kernel
+        @turn_context = context
         @adapter = adapter
         @stable_length = stable_length
         @sleeper = sleeper || ->(seconds) { sleep(seconds) }
@@ -93,10 +96,14 @@ module Samagotchi
 
       # +reasoning_since+ (ModelBackend#complete): the resumed run's start,
       # the Run's own start then (Run#initialize, #reasoning_boundary).
+      # +context+: the run's turn (TurnContext, Engine#generate's): its
+      # settings are what the requests send, its tool calls run in it; a
+      # bare loop's (#turn_context) when none is given.
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
         raise ArgumentError, "ChatLoop has no adapter" unless @adapter
 
+        @turn_context = context if context
         conversation = Array(messages).map(&:dup)
         Run.new(self, conversation, on_stream_event, cancel_controller, model_name, pending_input, start: reasoning_since)
            .call(max_iterations: max_iterations || 1, cap: KernelLoop.resolve_output_char_cap(max_tool_output_chars))
@@ -108,14 +115,14 @@ module Samagotchi
       end
 
       # Tool definitions for the request: the schemas the native prompts are
-      # rendered from (the kernel's registry, the tools the turn's LLM
-      # context layers offer), with the chat-only enums and closed
-      # parameters. On an adapter that loads tools for +model+
-      # (#loads_tools?), every tool the session reaches but doesn't declare
-      # follows, deferred (Tools::DeferredTools: +conversation+, the
+      # rendered from (the turn's ToolSurface: what it declares), with the
+      # chat-only enums and closed parameters. On an adapter that loads
+      # tools for +model+ (#loads_tools?, asked per request: a refusal turns
+      # it off mid-turn), every tool the session reaches but doesn't declare
+      # follows, deferred (ToolSurface#deferred_for: +conversation+, the
       # request's, names the ones it loaded); never without a declared one.
       def tool_definitions(conversation = nil, model: nil)
-        declared = ToolDeclarations.chat_schemas(tools.schemas(layers: llm_context_layers)).map do |schema|
+        declared = ToolDeclarations.chat_schemas(surface.schemas).map do |schema|
           { type: "function", function: schema.slice(:name, :description, :parameters) }
         end
         return declared if declared.empty? || !loads_tools?(model)
@@ -127,10 +134,13 @@ module Samagotchi
       end
 
       # The tools a request on a host that loads tools declares deferred
-      # (Tools::DeferredTools).
-      def deferred_tools(conversation)
-        Tools::DeferredTools.list(tools, conversation, layers: llm_context_layers)
-      end
+      # (ToolSurface#deferred_for).
+      def deferred_tools(conversation) = surface.deferred_for(conversation)
+
+      # The turn's ToolSurface (#turn_context's), else one computed now from
+      # the kernel's tools (a bare loop).
+      # @return [Tools::ToolSurface]
+      def surface = Tools::ToolSurface.of(turn_context, tools)
 
       # Whether the adapter takes tools it doesn't declare up front for
       # +model+ (AnthropicMessages#loads_tools?); OpenAIChat doesn't.
@@ -147,22 +157,33 @@ module Samagotchi
       # The kernel's tools.
       def tools = @kernel.tools
 
-      # The turn's LLM context layers (KernelLoop#llm_context_layers).
-      def llm_context_layers = @kernel.llm_context_layers
+      # The TurnContext of the run in progress, else of the last run
+      # (#complete's context:); before any, the one it was built with, else a
+      # context of the kernel's own settings (a bare loop). Read on the turn's thread only.
+      # @return [TurnContext]
+      def turn_context = @turn_context || TurnContext.none(settings: @kernel.turn_settings)
+
+      # The turn's LLM::TurnSettings (#turn_context's).
+      def settings = turn_context.settings
+
+      # The turn's LLM context layers (TurnContext#llm_context_layers).
+      def llm_context_layers = turn_context.llm_context_layers
 
       # The turn's LLM context strategy (LLMContextStrategy::Resolved), nil
       # when none was resolved.
-      def llm_context = @kernel.turn_settings&.llm_context
+      def llm_context = settings&.llm_context
 
       # KernelLoop#reprefilled_tokens, the kernel's request history.
       def reprefilled_tokens(model, **) = @kernel.reprefilled_tokens(model, **)
 
-      # The kernel's LLMContextView, the turn's strategy.
-      def llm_context_view = @kernel.llm_context_view
+      # The kernel's LLMContextView under the turn's strategy.
+      def llm_context_view = @kernel.llm_context_view(llm_context)
 
       # The strategy's own edits before a request and at turn end
-      # (KernelLoop#apply_llm_context!).
-      def apply_llm_context!(conversation, **) = @kernel.apply_llm_context!(conversation, **)
+      # (KernelLoop#apply_llm_context!), under the turn's strategy.
+      def apply_llm_context!(conversation, **)
+        @kernel.apply_llm_context!(conversation, llm_context, model: settings&.model_name, **)
+      end
 
       # The running turn, for forget_outputs (KernelLoop#llm_context_turn).
       def llm_context_turn=(turn)
@@ -267,7 +288,7 @@ module Samagotchi
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
       # Whether this turn's requests carry tool changes (the turn's model).
-      def tool_change_wire? = tool_changes?(@kernel.turn_settings&.model_name)
+      def tool_change_wire? = tool_changes?(settings&.model_name)
 
       # The first index whose model entries carry their reasoning (nil:
       # none do) under +level+. Under turn: +since+ when given, where a
@@ -298,14 +319,14 @@ module Samagotchi
         conversation.drop(boundary).sum { |entry| entry[:role].to_s == "model" && thought?(entry) ? entry[:thinking].length : 0 }
       end
 
-      # The turn's ReasoningHistory level (the kernel's turn_settings); drop
+      # The turn's ReasoningHistory level (the turn's settings); drop
       # without settings, and for a +model+ whose host refused it
       # (#reasoning_history_refused!). An adapter that sends its blocks back
       # (#replays_content?) is floored at turn: the running run's thinking
       # blocks always go back (a tool loop with thinking needs the last
       # assistant turn's), whatever the level says.
       def reasoning_history(model = nil)
-        level = model && @refusals.refused?(:reasoning_history, model) ? :drop : @kernel.turn_settings&.reasoning_history
+        level = model && @refusals.refused?(:reasoning_history, model) ? :drop : settings&.reasoning_history
         level ||= :drop
         level == :drop && replays_content? ? :turn : level
       end
@@ -320,18 +341,17 @@ module Samagotchi
         @refusals.remember(:reasoning_history, model)
       end
 
-      # The turn's VisionContext (the Engine sets the kernel's
-      # turn_settings), or nil.
-      def vision = @kernel.turn_settings.vision
+      # The turn's VisionContext (its settings'), or nil.
+      def vision = settings.vision
 
-      # The turn's configured price (the kernel's turn_settings), or nil.
-      def price = (@kernel.turn_settings&.price if @kernel.respond_to?(:turn_settings))
+      # The turn's configured price (its settings'), or nil.
+      def price = settings&.price
 
-      # The turn's request parameters (the kernel's turn_settings).
-      def sampling = @kernel.turn_settings.sampling || {}
+      # The turn's request parameters (its settings').
+      def sampling = settings.sampling || {}
 
-      # The turn's thinking level (the kernel's turn_settings).
-      def thinking = @kernel.turn_settings.thinking || Thinking::DEFAULT
+      # The turn's thinking level (its settings').
+      def thinking = settings.thinking || Thinking::DEFAULT
 
       # The request fields the thinking level adds, as the adapter's wire
       # takes them (OpenAIChat#thinking_fields: Thinking.chat_fields); none
@@ -375,24 +395,24 @@ module Samagotchi
       def strip_model_thought(text) = @kernel.strip_model_thought(text)
 
       def tool_runner
-        @tool_runner ||= ToolRunner.new(@kernel, window: -> { context_window(@kernel.turn_settings&.model_name) })
+        @tool_runner ||= ToolRunner.new(@kernel, window: ->(run_settings) { context_window(run_settings&.model_name, run_settings) })
       end
 
       # The window for +model+: the kernel's client probes the server it
       # points at (Engine keeps it on the effective model's host; a local
       # llama.cpp answers /props), then the host's model list, the model's
       # or host's window_tokens, config, env and the default. A remote
-      # provider has no /props to probe.
-      def context_window(model)
+      # provider has no /props to probe. +run_settings+: the LLM::TurnSettings
+      # whose window_setting counts (the turn's by default).
+      def context_window(model, run_settings = settings)
         client = @adapter.remote? ? nil : @kernel.client
-        ContextWindow.resolve(client: client, model: model, adapter: @adapter,
-                              setting: (@kernel.turn_settings&.window_setting if @kernel.respond_to?(:turn_settings)))
+        ContextWindow.resolve(client: client, model: model, adapter: @adapter, setting: run_settings&.window_setting)
       rescue StandardError
         nil
       end
 
-      # The kernel's generation guard (KernelLoop#guard_generation).
-      def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation : nil
+      # The kernel's generation guard for the turn (KernelLoop#guard_generation).
+      def guard_generation = @kernel.respond_to?(:guard_generation) ? @kernel.guard_generation(turn_context) : nil
 
       # A hook failing must not break the turn (as in ToolRunner).
       def fire_hook(name, event)
@@ -609,8 +629,10 @@ module Samagotchi
           @deferred = []
           @context = ContextStatus.new(conversation: conversation, llm_context: loop.llm_context,
                                        counted_chars_per_token: loop.counted_chars_per_token)
+          # The run's turn: its tool calls run in it.
+          @turn_context = loop.turn_context
           loop.llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: @context,
-                                                             emit: method(:emit))
+                                                             emit: method(:emit), turn_id: @turn_context.id)
         end
 
         def call(max_iterations:, cap:)
@@ -1094,7 +1116,7 @@ module Samagotchi
         def dispatch(tool_calls, iteration, cap)
           log_direct_deferred(tool_calls)
           calls = tool_calls.map { |tool_call| NativeToolNormalizer.normalize(tool_call) }
-          runs = ToolResponse.run_batch(@loop.tool_runner, calls, iteration: iteration, emit: method(:emit),
+          runs = ToolResponse.run_batch(@loop.tool_runner, calls, context: @turn_context, iteration: iteration, emit: method(:emit),
                                                                   on_stream_event: @on_stream_event, cap: cap) do |run, index|
             @conversation << ToolResponse.single(run, tool_call_id: tool_calls[index].id,
                                                       ids: ToolIds.next_ids(@conversation, 1))

data/lib/samagotchi/llm/native_backend.rb

@@ -17,7 +17,7 @@ module Samagotchi
       def provider = :native
 
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
-                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
+                   model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil, context: nil)
         @kernel.run(
           messages,
           max_iterations: max_iterations,
@@ -26,7 +26,8 @@ module Samagotchi
           model_name: model_name,
           max_tool_output_chars: max_tool_output_chars,
           pending_input: pending_input,
-          reasoning_since: reasoning_since
+          reasoning_since: reasoning_since,
+          context: context || @kernel.context
         )
       end
     end

data/lib/samagotchi/llm_context_forget.rb

@@ -52,9 +52,11 @@ module Samagotchi
     # The turn a forget_outputs call runs in: its conversation (the
     # entries the edits are saved on), its ContextStatus (nil: none) and
     # its stream (+emit+, nil: none), which gets an applied batch's ✂ row
-    # (LLMContextNotice).
-    Turn = Data.define(:conversation, :context, :emit) do
-      def initialize(emit: nil, **fields) = super
+    # (LLMContextNotice); +turn_id+: the Engine turn the run is for
+    # (TurnContext#id; nil: none), so a reader tells the running turn's
+    # conversation from the last one's (Engine#live_conversation).
+    Turn = Data.define(:conversation, :context, :emit, :turn_id) do
+      def initialize(emit: nil, turn_id: nil, **fields) = super
     end
 
     # One output a call may name: its entry, its ToolIds ref, its tool,

data/lib/samagotchi/model_binding.rb

@@ -8,7 +8,7 @@ module Samagotchi
   # An Engine's model choice (ModelChoice: the model as given and as typed)
   # and the prompt profile resolved for it, under one mutex; the counterpart
   # of ToolkitBinding. The memory overlay keys follow the choice
-  # (#sync_model_key!).
+  # (#sync_model_key!), which each turn's TurnContext takes.
   #
   # The choice changes in one assignment under the mutex (#switch!), so a
   # reader on another thread sees the old pair or the new one. A resolution
@@ -126,13 +126,13 @@ module Samagotchi
     # The memory overlay key follows the model sent (ModelOverlay.key_for
     # its id). A model typed as an alias used to key overlays by the alias
     # (before aliases were applied there): that key is read when the
-    # target's overlay is missing (KernelLoop#sync_model_key!).
+    # target's overlay is missing. A turn takes both in its TurnContext
+    # (Engine#generate): memory_read and the gate read them there.
     def sync_model_key!
       choice = @choice
       @model_key = ModelOverlay.key_for(@bare_name.call(choice.name))
       typed_key = ModelOverlay.key_for(@registry.parse_qualified_model(choice.typed).last)
       @fallback_model_key = typed_key == @model_key ? nil : typed_key
-      @kernel.call.sync_model_key!(@model_key, fallback: @fallback_model_key)
     end
   end
 end

data/lib/samagotchi/plugin/prompt_sections.rb

@@ -63,6 +63,13 @@ module Samagotchi
         @mutex.synchronize { @sections.any? { |section| section.bundle == bundle.to_s && section.name == name.to_s } }
       end
 
+      # The names +bundle+ registered, in prompt order (what it registered, for
+      # Testing::Install and chi bundle check).
+      # @return [Array<String>]
+      def names(bundle)
+        @mutex.synchronize { @sections.select { |section| section.bundle == bundle.to_s }.map(&:name) }
+      end
+
       # Run every block for +session_id+ and keep what they gave.
       # @param session_id [String, nil] whose last good text a failure keeps
       # @return [Array<Built>] in prompt order, the sections with text

data/lib/samagotchi/question_desk.rb

@@ -118,7 +118,7 @@ module Samagotchi
     end
 
     # Ask the model's question (ask_user_question): the kernel's
-    # question_handler, called on the turn thread with the payload
+    # Services#question_handler, called on the turn thread with the payload
     # Tools::AskUserQuestion.validate made. Opens it (#open_question) and
     # returns the answer as JSON for the tool result.
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:},

data/lib/samagotchi/revise_anchor.rb

@@ -5,7 +5,7 @@ require_relative "verify_anchor"
 module Samagotchi
   # The earlier turn a Revise turn rewrites the answer of, carried only by
   # a Revise turn (TurnAnchors). Its stamp on the turn's opening message
-  # is display metadata, never in the prompt (Engine#revision_target).
+  # is display metadata, never in the prompt (TurnStages::VerifyAnchors#revision_target).
   ReviseAnchor = Data.define(:turn_id) do
     def self.from(value)
       return value if value.is_a?(self)

data/lib/samagotchi/system_prompt.rb

@@ -8,6 +8,7 @@ require_relative "memory_paths"
 require_relative "paths"
 require_relative "tool_declarations"
 require_relative "tools/memory"
+require_relative "tools/tool_surface"
 require_relative "muted_memories"
 require_relative "model_notes"
 require_relative "bundle_needs"
@@ -46,7 +47,8 @@ module Samagotchi
     attr_reader :requested_memories
 
     # @param profile  [#call] → ModelProfile
-    # @param tools    [#call] → Tools::Registry
+    # @param tools    [#call] → Tools::Registry, nil (no tools): each build
+    #   reads it as a Tools::ToolSurface under the build's layers
     # @param session  [#call] → Session, nil
     # @param thinking [#call] → Symbol, the effective model's level (Thinking)
     # @param model    [#call] → ModelIdentity, nil (the section is left out)
@@ -91,8 +93,10 @@ module Samagotchi
 
     # A prompt #build made, with what it read while it did: the memory
     # index sizes (#memory_index), the model notes, the files and the
-    # plugins' sections it holds, and its stable part's length (chat).
-    Built = Data.define(:prompt, :memory_index, :notes, :files, :sections, :stable_length)
+    # plugins' sections it holds, its stable part's length (chat) and the
+    # Tools::ToolSurface it declares (the tools, the not-loaded line, the
+    # kit's prompt text).
+    Built = Data.define(:prompt, :memory_index, :notes, :files, :sections, :stable_length, :surface)
 
     # The full prompt: #base wrapped with the index and the rest. Built once
     # per loop and level (until #reset!) so the prompt prefix, and the
@@ -110,7 +114,7 @@ module Samagotchi
     # @param chat [Boolean] for the chat loop
     # @param thinking [Symbol, nil] the level (Thinking); nil: the effective model's
     # @param layers [Array<Symbol>] the turn's LLM context layers: the
-    #   native prompt declares the tools they add (Tools::Registry#entries)
+    #   native prompt declares the tools they add (Tools::ToolSurface#declared)
     def build(chat: false, thinking: nil, layers: [])
       key = [chat, thinking, layers]
       cache = @cache
@@ -172,7 +176,8 @@ module Samagotchi
     # The base prompt (specs, plugins' declarations), with Gemma's tool
     # declarations at its end as #build has them.
     def base(chat: false, layers: [])
-      with_tail_declarations(assist_system_prompt(chat: chat, layers: layers), chat: chat, layers: layers)
+      surface = tool_surface(layers)
+      with_tail_declarations(assist_system_prompt(chat: chat, surface: surface), chat: chat, surface: surface)
     end
 
     # Names activated via preloaded --memory entries during prompt
@@ -192,12 +197,20 @@ module Samagotchi
       @section_files = []
       @section_plugins = []
       @measured_stable_length = nil
-      prompt = system_prompt_with_index(assist_system_prompt(chat: chat, layers: layers),
-                                        chat: chat, thinking: thinking, layers: layers)
+      surface = tool_surface(layers)
+      prompt = system_prompt_with_index(assist_system_prompt(chat: chat, surface: surface),
+                                        chat: chat, thinking: thinking, surface: surface)
       Built.new(prompt: prompt, memory_index: @measured_index, notes: @section_notes || [],
-                files: @section_files.freeze, sections: @section_plugins.freeze, stable_length: @measured_stable_length)
+                files: @section_files.freeze, sections: @section_plugins.freeze, stable_length: @measured_stable_length,
+                surface: surface)
     end
 
+    # The session's tools as a build under +layers+ declares them, read
+    # from the Registry now (one per build: the declarations, the
+    # not-loaded line and the kit's text agree).
+    # @return [Tools::ToolSurface]
+    def tool_surface(layers) = Tools::ToolSurface.for(@tools_lookup.call, layers: layers)
+
     def profile = @profile_lookup.call
 
     def turn_thinking = @thinking_lookup.call
@@ -208,8 +221,8 @@ module Samagotchi
 
     # ── Tool declarations ──────────────────────────────────────────────────────
 
-    def tool_declarations(layers)
-      schemas = ToolDeclarations.native_schemas(@tools_lookup.call, layers: layers)
+    def tool_declarations(surface)
+      schemas = ToolDeclarations.native_schemas(surface)
       case profile.name
       when "qwen36"
         ToolDeclarations.qwen_declarations(schemas)
@@ -232,7 +245,7 @@ module Samagotchi
 
     # @param chat [Boolean] for the chat loop: no tool declarations or call
     #   syntax (its tools go as schemas with each request)
-    def assist_system_prompt(chat: false, layers: [])
+    def assist_system_prompt(surface:, chat: false)
       return chat_system_prompt if chat
 
       hint = tool_call_hint
@@ -241,7 +254,7 @@ module Samagotchi
       tools = if gemma_tail_declarations?
                 "Your tools are declared at the end of this system prompt."
               else
-                "You have access to the following tools:\n\n#{tool_declarations(layers)}\n"
+                "You have access to the following tools:\n\n#{tool_declarations(surface)}\n"
               end
 
       <<~SYS
@@ -332,7 +345,7 @@ module Samagotchi
     # memory write changes them) after all of them; the model, the location
     # and the session close the prompt (Gemma's tool declarations still
     # follow them).
-    def system_prompt_with_index(base, chat: false, thinking: nil, layers: [])
+    def system_prompt_with_index(base, chat: false, thinking: nil, surface: tool_surface([]))
       thinking_token = chat ? "" : Thinking.native(thinking || turn_thinking, profile).system_token
       indexes = { project: read_memory_index("project"), system: read_memory_index("system") }
       @measured_index = measure_indexes(indexes)
@@ -340,15 +353,15 @@ module Samagotchi
         "Project memories:\n#{indexes[:project]}",
         "System memories:\n#{indexes[:system]}"
       ].join("\n\n")
-      stable = [thinking_token + base, not_loaded_line(layers), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
-                project_specific_description, appended_section, kit_prompt_section, plugin_prompt_section, memory_sections]
+      stable = [thinking_token + base, not_loaded_line(surface), rg_guidance, system_identity_section, model_notes_section, explicit_memory_section,
+                project_specific_description, appended_section, kit_prompt_section(surface), plugin_prompt_section, memory_sections]
       stable_text = stable.compact.join("\n")
       volatile = [participants_section, current_model, project_location, current_session].compact
-      return with_tail_declarations(stable_text, chat: chat, layers: layers) if volatile.empty?
+      return with_tail_declarations(stable_text, chat: chat, surface: surface) if volatile.empty?
 
       prompt = "#{stable_text}\n#{volatile.join("\n")}"
       @measured_stable_length = stable_text.length + 1 if chat
-      with_tail_declarations(prompt, chat: chat, layers: layers)
+      with_tail_declarations(prompt, chat: chat, surface: surface)
     end
 
     # The tools the session's toolkit leaves out, named once right after the
@@ -357,15 +370,12 @@ module Samagotchi
     # 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)
-
-      names = registry.left_out_names(layers: layers)
+    def not_loaded_line(surface)
+      names = surface.left_out.keys
       return nil if names.empty?
 
-      toolkit = "(toolkit #{registry.toolkit&.name})"
-      reachable = registry.reachable_names(layers: layers)
+      toolkit = "(toolkit #{surface.toolkit&.name})"
+      reachable = surface.index_only.map(&:name)
       if reachable.empty?
         return "Not loaded in this session #{toolkit}: #{names.join(", ")}. Only the user can load one (/toolkit add <name>)."
       end
@@ -387,10 +397,7 @@ module Samagotchi
     # sessions on that kit share it, and a memory write doesn't move it.
     # nil on a kit without one and on full: the prompt is what it was
     # before kit prompts.
-    def kit_prompt_section
-      registry = @tools_lookup.call
-      registry.respond_to?(:toolkit) ? registry.toolkit&.prompt : nil
-    end
+    def kit_prompt_section(surface) = surface.toolkit&.prompt
 
     # The plugins' prompt sections (chi.prompt_section), right after the
     # kit prompt and before the memory indexes: a plugin's text depends on
@@ -406,8 +413,8 @@ module Samagotchi
       end
     end
 
-    def with_tail_declarations(prompt, chat:, layers:)
-      chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(layers)
+    def with_tail_declarations(prompt, chat:, surface:)
+      chat || !gemma_tail_declarations? ? prompt : prompt.rstrip + tool_declarations(surface)
     end
 
     def gemma_tail_declarations? = profile.name == "gemma4"

data/lib/samagotchi/testing/boundary.rb

@@ -94,6 +94,13 @@ module Samagotchi
           "Samagotchi::AnswerRefs.new" => "spec: after_turn's refs: helper, as chi's fire site builds it",
           "Samagotchi::Log" => "spec: stubs Log to check what ctx.log recorded: a kit log recorder could replace it"
         },
+        "inline-widgets" => {
+          'require "samagotchi/inline_widgets"' => "spec: for InlineWidgets",
+          "Samagotchi::InlineWidgets.parse" => "spec: each example the sections teach parses strictly, as chi web " \
+                                               "parses a block (the drawing is core's, so is the parse)",
+          "Samagotchi::Plugin::PromptSections::MAX" => "spec: the prompt-section limit a section over is dropped at: " \
+                                                       "could be a stable constant"
+        },
         "loop-guard" => {
           'require "samagotchi/llm/native_tool_normalizer"' => "spec: for NativeToolNormalizer",
           "Samagotchi::LLM::NativeToolNormalizer.normalize" => "spec: replays recorded calls in the shape chi's parser gives",

data/lib/samagotchi/testing/bundle.rb

@@ -11,6 +11,7 @@ require_relative "../tools/tool_index"
 require_relative "../peer_sources"
 require_relative "../toolkit"
 require_relative "../guardrails/gate"
+require_relative "../turn_context"
 require_relative "../memory_bundle/manifest"
 require_relative "../memory_bundle/source"
 require_relative "../session_setup"
@@ -239,8 +240,9 @@ module Samagotchi
         dispatched = nil
         capture = Hooks::Registry.new
         capture.register(:before_tool_call) { |event| dispatched = event.dup }
-        gate = Guardrails::Gate.new(-> { capture }, context_lookup: -> { context }, tools_lookup: -> { tools })
-        gate.evaluate(call, iteration: iteration, params: params, verdict: verdict || Verdict.new(call: call))
+        gate = Guardrails::Gate.new(hooks: capture, tools: tools, context_for: ->(_turn) { context })
+        gate.evaluate(call, context: TurnContext.none, iteration: iteration, params: params,
+                            verdict: verdict || Verdict.new(call: call))
         raise ArgumentError, "guardrails did not dispatch a before_tool_call event for #{call[:name].inspect}" unless dispatched
 
         dispatched.slice(:type, :iteration, :call, :params, :blocked, :block_reason, :guardrail, :context, :targets)
@@ -256,11 +258,11 @@ module Samagotchi
       def tool_call(call, params: nil, cwd: nil, context: nil, verdict: nil, iteration: 1)
         context ||= Guardrails::Context.new(cwd: cwd || @recorder[:cwd], session_id: @recorder[:session_id],
                                             interface: @recorder[:frontend])
-        gate = Guardrails::Gate.new(-> { hooks }, context_lookup: -> { context }, tools_lookup: -> { tools },
-                                                  checks_lookup: -> { [] })
+        gate = Guardrails::Gate.new(hooks: hooks, tools: tools, context_for: ->(_turn) { context },
+                                    checks_for: ->(_turn) { [] })
         verdict ||= Verdict.new(call: call)
         params ||= "#{call[:name]} #{call[:content] || call[:path]}".strip
-        failing { gate.evaluate(call, iteration: iteration, params: params, verdict: verdict) }
+        failing { gate.evaluate(call, context: TurnContext.none, iteration: iteration, params: params, verdict: verdict) }
       end
 
       # Run a command line ("/name args") as chi does: the first matching

data/lib/samagotchi/testing/install.rb

@@ -31,7 +31,7 @@ module Samagotchi
       # What a bundle registered (#registered): commands, tools (names),
       # hooks per event, inits (labels), toolkits, tool sources and peer
       # sources (names).
-      Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources)
+      Registered = Data.define(:commands, :tools, :hooks, :inits, :toolkits, :tool_sources, :peer_sources, :prompt_sections)
       # A command: its mid_turn policy and its selection-bar labels (chi.annotation).
       Command = Data.define(:name, :mid_turn, :labels)
       # A hook on an event: the bundle, the hook (its file, or the plugin's) and its priority.
@@ -98,7 +98,8 @@ module Samagotchi
           inits: inits.map { |init| init[:label] },
           toolkits: Array(registries.toolkits).map(&:name),
           tool_sources: registries.tool_index.sources.map(&:label),
-          peer_sources: registries.peer_sources.names
+          peer_sources: registries.peer_sources.names,
+          prompt_sections: registries.prompt_sections.names(name)
         )
       end
 

data/lib/samagotchi/tool_activity.rb

@@ -58,11 +58,11 @@ module Samagotchi
     # @param registry [Tools::Registry, nil] the session's tools
     # @param cwd [String, nil] what a file tool's title is relative to (the
     #   worker runs in its session's working directory)
-    def tool_activity_event(tool_name, call, result, registry: nil, cwd: Dir.pwd)
+    def tool_activity_event(tool_name, call, result, registry: nil, cwd: Dir.pwd, surface: nil)
       event = {
         action: tool_activity_action(tool_name, registry: registry, call: call),
         tool: tool_name,
-        params: tool_activity_params(tool_name, call, registry: registry),
+        params: tool_activity_params(tool_name, call, registry: registry, surface: surface),
         status: tool_activity_status(result, tool_name, command: call.is_a?(Hash) ? call[:content] : nil)
       }
       # A grep that found nothing: ok, and the web row says "no match".
@@ -359,7 +359,9 @@ module Samagotchi
       name == "git" && args.first == "diff" && args.intersect?(%w[--quiet --exit-code])
     end
 
-    def tool_activity_params(tool_name, call, registry: nil)
+    # +surface+: the turn's Tools::ToolSurface, for a preview that reads it
+    # (call_tool's); nil outside a turn.
+    def tool_activity_params(tool_name, call, registry: nil, surface: nil)
       case tool_name
       when Tools::Execute::NAME
         "command=#{preview_tool_param(call[:content])}"
@@ -453,7 +455,7 @@ module Samagotchi
         parts << "options=#{preview_tool_param(Array(opts).join(","))}" if opts && !Array(opts).empty?
         parts.join(" ")
       else
-        registry_params(registry_entry(registry, tool_name), call)
+        registry_params(registry_entry(registry, tool_name), call, surface)
       end
     end
 
@@ -472,13 +474,13 @@ module Samagotchi
     # the web's reload also has); nil for a tool the registry doesn't know
     # that has no args:, and for a built-in without its own words above
     # (the reminder tools).
-    def registry_params(entry, call)
+    def registry_params(entry, call, surface = nil)
       return nil if entry&.core?
       return nil if entry.nil? && !call[:args].is_a?(Hash)
 
       if entry&.preview
         begin
-          return entry.preview.call(call)
+          return entry.preview_of(call, surface)
         rescue StandardError => e
           Log.warn(:plugins, "plugin_preview_failed", tool: entry.name, error: e.class.name,
                                                       msg: "#{entry.name} preview failed: #{e.message}")

data/lib/samagotchi/tool_declarations.rb

@@ -635,10 +635,10 @@ module Samagotchi
 
     # The schemas the native (Gemma, Qwen) prompts declare: the built-ins
     # as they are, and each plugin tool's flattened (.flat_schema).
-    # @param registry [Tools::Registry]
-    # @param layers [Array<Symbol>] the turn's LLM context layers (Registry#entries)
-    def native_schemas(registry, layers: [])
-      registry.entries(layers: layers).map { |entry| entry.core? ? entry.schema : flat_schema(entry.schema) }
+    # @param surface [Tools::ToolSurface] the tools a turn (or a build
+    #   under its layers) declares (ToolSurface#declared)
+    def native_schemas(surface)
+      surface.declared.map { |entry| entry.core? ? entry.schema : flat_schema(entry.schema) }
     end
 
     # A plugin tool's schema in the shape the built-ins have, which is all