pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/agent.rb

@@ -3,151 +3,174 @@
 require 'ruby_llm'
 
 module Pikuri
-  # Thin wrapper around +RubyLLM::Chat+: pikuri owns the *extension
-  # surface* (the event-stream listeners that consume normalized
-  # chat events, plus the controls that signal back into the loop)
-  # while ruby_llm owns the loop itself. The Thought / Tool-call /
-  # Observation iteration lives in +Chat#complete+; pikuri's job
-  # is wiring ruby_llm's three callbacks at construction time,
-  # emitting {Event} variants from each, and forwarding control
-  # signals (step-budget tick, cancellation check, mid-loop input
-  # drain) to the appropriate {Control}.
+  # Thin wrapper around +RubyLLM::Chat+: ruby_llm owns the Thought /
+  # Tool-call / Observation loop (+Chat#complete+); pikuri owns the
+  # *extension surface* — it wires ruby_llm's three callbacks at
+  # construction, emits {Event} variants from each, and forwards control
+  # signals to the {Control}s.
   #
-  # == Roles in this file
+  # Two seams meet here:
   #
-  # Two seams are visible:
-  #
-  # 1. **Listeners** ({ListenerList} + {Listener::Base} subclasses)
-  #    — pure consumers of the event stream; they never write back.
-  #    The +Agent+ emits every loop-narration {Event} variant;
-  #    extensions emit their own domain events through the
-  #    {ExtensionContext} capability facade handed to
-  #    {Extension#bind}. There is no public path from an +Agent+
-  #    reference to emission — no +listeners+ reader, no +chat+
-  #    reader, no emit method — so holding an agent grants read
-  #    access to its configuration and nothing more. New rendering
-  #    or capture targets (a web sink, a structured log) are added
-  #    as listeners without touching {Agent}.
+  # 1. **Listeners** ({ListenerList} + {Listener::Base}) — pure consumers
+  #    of the event stream, never writing back. The +Agent+ emits every
+  #    loop-narration {Event}; extensions emit domain events through the
+  #    {ExtensionContext} handed to {Extension#bind}. No public path leads
+  #    from an +Agent+ reference to emission (no +listeners+/+chat+ reader,
+  #    no emit method), so holding an agent grants read access and nothing
+  #    more. New sinks are added as listeners without touching {Agent}.
   # 2. **Controls** ({Control::StepLimit}, {Control::Cancellable},
-  #    {Control::Interloper}) — host-facing signal holders. The
-  #    +Agent+ reads from them at well-defined boundaries:
-  #    {Control::StepLimit#tick!} on every +before_tool_call+ (and
-  #    {Control::StepLimit#reset!} at turn start),
-  #    {Control::Cancellable#check!} on every +before_tool_call+
-  #    (and {Control::Cancellable#reset!} at turn start),
-  #    {Control::Interloper#drain!} on every +after_tool_result+.
+  #    {Control::Interloper}) — host-facing signal holders the +Agent+
+  #    reads at fixed boundaries: +tick!+/+check!+ on every
+  #    +before_tool_call+, +reset!+ at turn start, +drain!+ once each tool
+  #    batch is answered.
   #
-  # The two roles are named separately so "what fires when" is a
-  # single grep for +@listeners.emit+ in this file (loop narration)
+  # "What fires when" is one grep for +@listeners.emit+ (loop narration)
   # plus the capability calls in {ExtensionContext} (domain events).
   #
   # == Step-exhaustion policy
   #
-  # If the +step_limit:+ {Control::StepLimit} trips during
-  # completion, {#run_loop} catches the +Exceeded+ exception and
-  # applies the budget's {Control::StepLimit#on_exhausted} policy
-  # (see that class header for how hosts pick):
+  # When +step_limit:+ trips during completion, {#run_loop} applies its
+  # {Control::StepLimit#on_exhausted} policy:
   #
-  # - +:raise+ (the default) — re-raise to the host, same shape as
-  #   the cancellation rescue below. The chat history survives and
-  #   {Control::StepLimit#reset!} fires at the next turn boundary,
-  #   so a REPL user can simply say "continue".
+  # - +:raise+ (default) — re-raise to the host. History survives and
+  #   {Control::StepLimit#reset!} fires next turn, so "continue" works.
   # - +:synthesize+ — emit an {Event::FallbackNotice} and run the
-  #   {Synthesizer} prompt on a nested tools-free +Agent+ (the
-  #   same construction shape the +agent+ tool from
-  #   +pikuri-subagents+ uses for sub-agents): parent's listener
-  #   stream derived via {ListenerList#for_sub_agent} (Terminal
-  #   padded, TokenLog zeroed, recorder shared by reference),
-  #   parent's +cancellable+ shared so a user cancel during
-  #   synthesis still works, a defensive +step_limit+ at +max: 1+
-  #   (the synth has no tools and shouldn't tick it). The synth's
-  #   answer becomes the value reported by
-  #   {#last_assistant_content}, so callers (notably the +agent+
-  #   tool from +pikuri-subagents+) still get a usable reply.
+  #   {Synthesizer} prompt on a nested tools-free +Agent+ (listener stream
+  #   via {ListenerList#for_sub_agent}, +cancellable+ shared so a user
+  #   cancel still works, a defensive +step_limit+ at +max: 1+). Its answer
+  #   becomes {#last_assistant_content}, so callers still get a reply.
   #
   # == Cancellation rescue
   #
-  # If the +cancellable:+ {Control::Cancellable} trips during
-  # +Chat#ask+, {#run_loop} catches the +Cancelled+ exception,
-  # emits an {Event::Cancelled} to the listener stream, and
-  # re-raises. No synthesizer fallback runs: cancellation means
-  # the user asked the agent to drop everything, so salvaging a
-  # partial answer would be the wrong move. The caller (typically
-  # a REPL) rescues the re-raised exception and returns control
-  # to the user; because {#run_loop} calls
-  # {Control::Cancellable#reset!} at the start of every turn, the
-  # same agent instance can take a fresh turn immediately
-  # afterwards.
+  # When +cancellable:+ trips during +Chat#ask+, {#run_loop} emits an
+  # {Event::Cancelled} and re-raises — no synthesizer fallback (cancel
+  # means drop everything). {Control::Cancellable#reset!} at each turn
+  # start lets the same instance take a fresh turn afterwards.
+  #
+  # == Threading
+  #
+  # **Thread-unsafe** — and that is the whole guarantee, deliberately no
+  # stronger. +@chat+, the message-identity map and the +on_close+ list are
+  # plain unguarded state, and {#run_loop} is not re-entrant, so a second
+  # thread calling in mid-turn corrupts the conversation rather than raising.
+  # Preventing concurrent access is the caller's job, by any means: one thread
+  # per agent, a mutex around every call, an actor mailbox. Nothing here is
+  # *confined* to a particular thread — an +Agent+ may be driven from a
+  # different thread on each turn, so never key anything about it off
+  # +Thread.current+.
+  #
+  # Several agents in one VM is then the easy case, one thread each:
+  #
+  #   agents.map { |a| Thread.new { a.run_loop(user_message: task_for(a)) } }.each(&:join)
+  #
+  # Two {Control}s are the sanctioned doors *in* from another thread, which is
+  # why they carry locks and the agent does not: {Control::Cancellable} (stop
+  # the turn) and {Control::Interloper} (queue a mid-turn message, delivered at
+  # the next tool-batch boundary). Every other method needs the caller's own
+  # serialization.
+  #
+  # Tools inherit nothing from this: an instance handed to two agents is
+  # reachable from both, so each declares its own posture (see
+  # {Pikuri::Tool}'s +== Sharing+).
   class Agent
     LOGGER = Pikuri.logger_for('Agent')
     private_constant :LOGGER
 
-    # @param transport [ChatTransport] the model-resolution bundle
-    #   (+model+ / +provider+ / +assume_model_exists+ and, for a model
-    #   on a non-global server, +api_base+ / +api_key+) the chat is
-    #   built from. Bundled into one value object so every construction
-    #   site — this constructor, the synthesizer rescue below, a
-    #   mid-conversation switch — can forward it with one assignment
-    #   instead of loose kwargs (where dropping one would silently
-    #   route the chat elsewhere or raise
-    #   +RubyLLM::ModelNotFoundError+). If +transport.model+ is
-    #   +nil+, it's filled in from +RubyLLM.config.default_model+.
-    # @param system_prompt [String] system message prepended to
-    #   the chat. Extensions append their advertisement blocks
-    #   (e.g. +<available_skills>+, +<available_mcps>+) onto this
-    #   base via {Configurator#append_system_prompt} during the
-    #   block.
-    # @param step_limit [Control::StepLimit, nil] step budget
-    #   control. When set, {Control::StepLimit#tick!} fires on
-    #   every +before_tool_call+ and {Control::StepLimit#reset!}
-    #   at the start of each turn; the budget's
-    #   {Control::StepLimit#on_exhausted} policy decides what
-    #   {#run_loop} does when it trips (see "Step-exhaustion
-    #   policy" in the class header). +nil+ means "no step budget"
-    #   (the agent can loop indefinitely).
-    # @param cancellable [Control::Cancellable, nil] cancellation
-    #   control. When set, {Control::Cancellable#check!} fires on
-    #   every +before_tool_call+ and
-    #   {Control::Cancellable#reset!} at the start of each turn.
-    #   +nil+ means "not cancellable" (the host has no way to
-    #   stop a running turn except by killing the process).
-    # @param interloper [Control::Interloper, nil] mid-loop
-    #   user-input queue. When set, the queue is drained at
-    #   every +after_tool_result+ and each item becomes a
-    #   {Event::UserTurn} with +mid_loop: true+. +nil+ means
-    #   "no mid-loop injection" (the bundled CLIs default).
-    # @param id [String] unique identifier for this agent. Empty
-    #   for the main agent; sub-agents get persona-rooted ids
-    #   like +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+, ...
-    #   generated by the +agent+ tool from +pikuri-subagents+ from
-    #   the persona name + a per-persona counter. Forwarded to
-    #   listeners through {ListenerList#for_sub_agent} so id-aware
-    #   ones (notably {Listener::TokenLog}) can tag their output.
-    #   The word "id" is deliberate — "name" is reserved throughout
-    #   the codebase for the persona-name load (the value the LLM
-    #   picks in the +agent+ tool's +name:+ argument).
-    # @param streaming [Boolean] opt into chunk-level streaming.
-    #   When +true+, {#run_loop} passes a per-chunk block to
-    #   +Chat#complete+, and ruby_llm requests
-    #   SSE responses from the provider — chunks are normalized
-    #   into {Event::ThinkingDelta} / {Event::AssistantDelta} on
-    #   the listener stream as they arrive. When +false+ (the
-    #   default), +Chat#ask+ runs in single-shot mode and only
-    #   the message-level {Event::Thinking} / {Event::Assistant}
-    #   bookends fire from +after_message+. Read by the +agent+
-    #   tool from +pikuri-subagents+ so spawned sub-agents inherit
-    #   the same mode without an extra kwarg.
-    # @yield [Configurator] yields a {Configurator} that collects
-    #   tools (via {Configurator#add_tool} / {Configurator#add_tools}),
-    #   listeners (via {Configurator#add_listener} /
-    #   {Configurator#add_listeners}), system-prompt snippets (via
-    #   {Configurator#append_system_prompt}), extension instances
-    #   (via {Configurator#add_extension} — which fires +configure+
-    #   immediately), and close handlers (via
-    #   {Configurator#on_close}). The Configurator is the *only*
-    #   path for adding any of these — there are no parallel ctor
-    #   kwargs. The block is optional; an agent constructed without
-    #   one has no tools, no listeners, no extensions.
+    # Envelope wrapped around every injected reference block by
+    # {#append_reference_block}. +system-reminder+ is Claude Code's and
+    # grok-build's tag, deliberately — an in-distribution envelope the model has
+    # seen in training beats a pikuri-flavoured one it has to infer.
+    REFERENCE_TAG = 'system-reminder'
+    private_constant :REFERENCE_TAG
+
+    # Provider slugs (matched against +@chat.model.provider+) whose wire format
+    # carries system content in a top-level request field rather than as an
+    # element of +messages+ — Anthropic's +system+ param, Bedrock's +system+
+    # blocks. ruby_llm's provider splits it out at payload-render time
+    # (+messages.partition { |m| m.role == :system }+), so a conversation
+    # holding nothing but the system prompt renders +messages: []+ and the API
+    # 400s — see {EmptyTurnError}. Everywhere else +:system+ is an ordinary
+    # array element (OpenAI, Gemini) and that same conversation is a legal
+    # one-message request.
+    #
+    # Only +:system+ moves — a placement difference in the payload, not a
+    # rewrite of what pikuri appended, so the +:user+ blocks of
+    # {#append_reference_block} ride through untouched on every provider here.
+    SEPARATE_SYSTEM_FIELD_PROVIDERS = %w[anthropic bedrock].freeze
+    private_constant :SEPARATE_SYSTEM_FIELD_PROVIDERS
+
+    # A blank turn was requested against a conversation holding nothing but the
+    # assembled system prompt, on a provider that would render that as
+    # +messages: []+ (see {SEPARATE_SYSTEM_FIELD_PROVIDERS}):
+    #
+    #   agent.run_loop(user_message: nil)   # fresh chat, backend Anthropic
+    #   # => EmptyTurnError; the host catches it and prompts for a real message
+    #
+    # Narrow by construction: every *injected* block lands as +role: :user+
+    # ({#append_reference_block}), so a skill-only or memory-only bare load has
+    # a message to complete against and never reaches here. What remains is a
+    # genuinely empty conversation.
+    #
+    # Content-neutral: {#provider} is all it carries — the host owns any
+    # user-facing wording.
+    class EmptyTurnError < StandardError
+      # @return [String] the resolved provider slug that can't complete the turn
+      attr_reader :provider
+
+      # @param provider [String] the resolved provider slug (e.g. +"anthropic"+)
+      def initialize(provider)
+        @provider = provider
+        super("#{provider} cannot complete a turn whose conversation holds only " \
+              ':system content (no user or assistant message): it would send an ' \
+              'empty messages array. Add a user message.')
+      end
+    end
+
+    # What {#run_loop} answers a tool call with when its batch unwound — see
+    # +== Repairing an unwound tool batch+. Public so a renderer can tell one
+    # from a real observation, as {History::INTERRUPTED_RESULT} is for the
+    # on-disk shape.
+    #
+    # Paired per cause: the first unanswered call is the one that raised or was
+    # about to, the rest never started, and telling a skipped call "you failed"
+    # invites a pointless retry. A tool failure has no constant — it reports
+    # +"Error: <class>: <message>"+, the shape {Tool#run} already returns for a
+    # validation failure.
+    CANCELLED_RESULT = '[Cancelled by the user]'
+    # @see CANCELLED_RESULT
+    CANCELLED_SKIPPED_RESULT = '[Not executed — the user cancelled this turn]'
+    # @see CANCELLED_RESULT
+    STEP_BUDGET_RESULT = '[Not executed — step budget exhausted]'
+    # @see CANCELLED_RESULT
+    FAILED_SKIPPED_RESULT = '[Not executed — a previous tool call in this batch failed]'
+
+    # @param transport [ChatTransport] model-resolution bundle (+model+ /
+    #   +provider+ / +assume_model_exists+ and, off the global server,
+    #   +api_base+ / +api_key+). A +nil+ +transport.model+ is filled from
+    #   +RubyLLM.config.default_model+.
+    # @param system_prompt [String] base system message; the chat sees
+    #   this plus every extension's {Extension#system_prompt_snippets},
+    #   assembled by {#assemble_system_prompt} at construction and on each
+    #   {#clear_conversation}.
+    # @param step_limit [Control::StepLimit, nil] step budget, or +nil+ for
+    #   no budget (unbounded looping). Its {Control::StepLimit#on_exhausted}
+    #   policy drives {#run_loop} on trip (see the class header).
+    # @param cancellable [Control::Cancellable, nil] cancellation control,
+    #   or +nil+ for none (no way to stop a running turn but killing the
+    #   process).
+    # @param interloper [Control::Interloper, nil] mid-loop user-input queue
+    #   drained once each tool batch is answered (each item becomes an
+    #   {Event::UserTurn} with +mid_loop: true+), or +nil+ for none.
+    # @param id [String] unique id; empty for the main agent, persona-rooted
+    #   for sub-agents (+"researcher 0"+, ...). Distinct from a persona's
+    #   +name+ (the value the LLM picks in the +agent+ tool's +name:+ arg).
+    # @param streaming [Boolean] opt into chunk-level streaming — {#run_loop}
+    #   passes a per-chunk block to +Chat#complete+ and normalizes chunks
+    #   into {Event::ThinkingDelta}/{Event::AssistantDelta}. Default +false+
+    #   (only the +after_message+ bookends fire).
+    # @yield [Configurator] the sole path for adding tools, listeners,
+    #   extensions, and +on_close+ handlers — there are no parallel ctor
+    #   kwargs. Optional; without it the agent has none of those.
     # @return [Agent]
     def initialize(transport:, system_prompt:,
                    step_limit: nil, cancellable: nil, interloper: nil,
@@ -158,6 +181,11 @@ module Pikuri
       @cancellable = cancellable
       @closed = false
 
+      # Kept separate from the assembled +@system_prompt+ so
+      # {#assemble_system_prompt} can recompute (base + extensions'
+      # snippets) from scratch at construction and on each
+      # {#clear_conversation}, refreshing dynamic sections.
+      @system_prompt_base = system_prompt
       @system_prompt = system_prompt
       @step_limit = step_limit
       @interloper = interloper
@@ -165,127 +193,86 @@ module Pikuri
       @streaming = streaming
       @synth_answer = nil
       @on_close_handlers = []
-      # Stashed for {#run_configure}, which runs the failure-prone
-      # build phase below out of a separate method.
+      # Stashed for {#run_configure}, the failure-prone build phase.
       @block = block
 
-      # Register *before* the build phase so a mid-construction raise
-      # is still recoverable: extensions arm their cleanup via
-      # +c.on_close+ (which writes straight to +@on_close_handlers+,
-      # see {Configurator}), and the rescue below fires whatever was
-      # armed before the failure. On the happy path this registration
-      # is the at-exit backstop if the host forgets {#close}; an
-      # explicit {#close} unregisters, so the agent isn't pinned alive
-      # until process exit.
+      # Register *before* the build phase so a mid-construction raise is
+      # recoverable: extensions arm cleanup via +c.on_close+ (straight into
+      # +@on_close_handlers+), and the rescue below fires whatever was armed
+      # before the failure. On the happy path this is the at-exit backstop
+      # if the host forgets {#close}; an explicit {#close} unregisters.
       Pikuri::Finalizers.register(self)
 
       begin
         run_configure
       rescue StandardError
-        # Half-built agent (e.g. an extension's +configure+ raised
-        # Cancelled mid-spawn). Fire the handlers armed so far, drop
-        # out of the registry, and re-raise — no partial state leaks.
+        # Half-built agent: fire the armed handlers, drop out of the
+        # registry, re-raise — no partial state leaks.
         close
         raise
       end
     end
 
-    # @return [ChatTransport] the resolved transport bundle this
-    #   agent was constructed with — same model id / provider /
-    #   assume-model-exists flag passed to every +RubyLLM.chat+
-    #   call originating from this agent (the main chat, the
-    #   synthesizer rescue, the +agent+ tool from
-    #   +pikuri-subagents+). Read by extensions that need to spawn
-    #   their own ruby_llm calls (e.g. MCP description synthesis,
-    #   sub-agent delegation).
+    # @return [ChatTransport] the resolved transport this agent was built
+    #   with — the model/provider/connection every +RubyLLM.chat+ from this
+    #   agent uses (main chat, synthesizer, sub-agents).
     attr_reader :transport
 
-    # @return [Array<Tool>] this agent's tool list in declaration
-    #   order. Read by extensions that filter against it (notably
-    #   the +agent+ tool from +pikuri-subagents+, which picks the
-    #   sub-agent's toolset from the parent's instances so any
-    #   already-bound workspace/confirmer wiring travels along).
-    #   Tools listed here are also the ones registered with
-    #   ruby_llm — the parent LLM can call any of them. Compare
-    #   with {#sub_agent_tools}.
+    # @return [Array<Tool>] tool list in declaration order. These are the
+    #   tools registered with ruby_llm — the parent LLM can call any. Cf.
+    #   {#sub_agent_tools}.
     attr_reader :tools
 
-    # @return [Array<Tool>] tools registered via
-    #   {Configurator#add_sub_agent_tool}, in declaration order.
-    #   Invisible to the parent LLM (never sent to ruby_llm);
-    #   available only to sub-agents whose persona +tool_names+
-    #   match. See {Configurator}'s "Two tool pools" header for
-    #   the trifecta-defense rationale.
+    # @return [Array<Tool>] tools added via
+    #   {Configurator#add_sub_agent_tool}, in declaration order. Never sent
+    #   to ruby_llm (invisible to the parent LLM); available only to
+    #   sub-agents whose persona +tool_names+ match — the trifecta defense,
+    #   see {Configurator}.
     attr_reader :sub_agent_tools
 
     # @return [String] resolved model id from {#transport}.
-    #   Convenience delegator for callers that don't need the
-    #   full transport bundle.
     def model
       @transport.model
     end
 
-    # @return [String] system prompt actually sent to the chat —
-    #   equal to the constructor's +system_prompt:+ argument plus
-    #   any snippets appended via {Configurator#append_system_prompt}
-    #   (extensions' +<available_skills>+ / +<available_mcps>+ /
-    #   +<available_agents>+, ...). Not inherited by sub-agents —
-    #   each persona owns its own system prompt verbatim.
+    # @return [String] system prompt actually sent — the base
+    #   +system_prompt:+ plus every extension's
+    #   {Extension#system_prompt_snippets}, re-assembled on
+    #   {#clear_conversation} (so a dynamic section may differ from its
+    #   construction value). Not inherited by sub-agents.
     attr_reader :system_prompt
 
-    # @return [Control::StepLimit, nil] the step-budget control
-    #   this agent was constructed with, or +nil+ when none.
+    # @return [Control::StepLimit, nil] the step budget, or +nil+.
     attr_reader :step_limit
 
-    # @return [Control::Cancellable, nil] the cancellation
-    #   control this agent was constructed with, or +nil+ when
-    #   none. Read by extensions that propagate cancellation to
-    #   their own LLM calls (e.g. the +agent+ tool from
-    #   +pikuri-subagents+ shares it with spawned sub-agents so
-    #   one Ctrl+C stops the tree).
+    # @return [Control::Cancellable, nil] the cancellation control, or
+    #   +nil+. Extensions read it to propagate cancellation to their own
+    #   LLM calls (the +agent+ tool shares it so one Ctrl+C stops the tree).
     attr_reader :cancellable
 
-    # @return [Control::Interloper, nil] the mid-loop user-input
-    #   control this agent was constructed with, or +nil+ when
-    #   none.
+    # @return [Control::Interloper, nil] the mid-loop user-input control, or
+    #   +nil+.
     attr_reader :interloper
 
-    # @return [String] this agent's unique identifier — empty for
-    #   the main agent; for sub-agents, the persona-rooted id
-    #   assigned by the +agent+ tool from +pikuri-subagents+ (e.g.
-    #   +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+).
-    #   Propagated to listeners via {ListenerList#for_sub_agent(id:)}
-    #   so id-aware ones can tag output. Distinct from the persona's
-    #   +name+ (the value the LLM picks in the +agent+ tool's
-    #   +name:+ argument).
+    # @return [String] this agent's id — empty for the main agent,
+    #   persona-rooted for sub-agents (+"researcher 0"+). Distinct from the
+    #   persona +name+; propagated to listeners via
+    #   {ListenerList#for_sub_agent} so id-aware ones tag their output.
     attr_reader :id
 
-    # @return [Boolean] +true+ when this agent opted into
-    #   chunk-level streaming (see the +streaming:+ kwarg on
-    #   {#initialize}); +false+ otherwise. Read by extensions that
-    #   spawn their own ruby_llm calls (notably the +agent+ tool
-    #   from +pikuri-subagents+, so spawned sub-agents inherit the
-    #   same mode).
+    # @return [Boolean] whether this agent opted into chunk-level streaming
+    #   (see {#initialize}'s +streaming:+).
     attr_reader :streaming
 
-    # @return [Array<Extension>] extension instances bound to this
-    #   agent — added via {Configurator#add_extension} inside the
-    #   +Agent.new+ block. Each instance's +configure+ runs during
-    #   the block and its +bind+ runs at the end of
-    #   {#initialize}, once per registration (so once per parent
-    #   agent in the typical setup; sub-agents do not inherit
-    #   extensions).
+    # @return [Array<Extension>] extensions bound to this agent. Each one's
+    #   +configure+ ran during the +Agent.new+ block, its +bind+ at the end
+    #   of {#initialize}. Not inherited by sub-agents.
     attr_reader :extensions
 
     # @return [Integer, nil] resolved context-window cap — the
-    #   {ChatTransport#context_window} if one was given, else what
-    #   {ContextWindowDetector} probed. +nil+ when neither produced
-    #   a value (a non-llama server with no explicit cap). Re-resolved
-    #   on every model switch (see {#run_loop}'s +transport:+). Read by
-    #   extensions that spawn their own ruby_llm calls (notably the
-    #   +agent+ tool from +pikuri-subagents+, which hands a sub-agent
-    #   +parent.transport.with(context_window: this)+ so the resolved
-    #   cap rides along without a re-probe).
+    #   {ChatTransport#context_window} if given, else the
+    #   {ContextWindowDetector} probe; +nil+ when neither yields one.
+    #   Re-resolved on every model switch.
     attr_reader :context_window_cap
 
     # Final assistant message content for the most recent
@@ -302,85 +289,100 @@ module Pikuri
       last&.content
     end
 
-    # Run the agent loop for a single user turn. Emits an
-    # {Event::UserTurn} with +mid_loop: false+, resets the
-    # step-budget and cancellation controls (so a stale state
-    # from a prior turn doesn't poison this one), and forwards
-    # +user_message+ to {#chat} via +ask+. Returns nil; rendering
-    # and any other observable output is the listeners'
-    # responsibility.
-    #
-    # If the +step_limit+ control trips during completion, the
-    # rescue branch applies its {Control::StepLimit#on_exhausted}
-    # policy: +:raise+ re-raises the +Exceeded+ exception to the
-    # host (chat history intact — the next turn's +reset!+
-    # refreshes the budget, so "continue" just works);
-    # +:synthesize+ emits an {Event::FallbackNotice} and runs the
-    # {Synthesizer} prompt on a nested tools-free agent, capturing
-    # its answer for {#last_assistant_content}. See
-    # "Step-exhaustion policy" in the class header.
-    #
-    # If the +cancellable+ control trips during +ask+, the rescue
-    # branch emits an {Event::Cancelled} and re-raises the
-    # +Cancelled+ exception. No synthesizer fallback runs — see
-    # the "Cancellation rescue" section in the class header.
-    #
-    # Subsequent calls keep building on the same chat history, so
-    # the model sees full multi-turn context.
+    # Run the agent loop for one turn. With a +user_message+, emits an
+    # {Event::UserTurn} (+mid_loop: false+) and appends it; with none, runs a
+    # *bare* turn against whatever the conversation + drained injections
+    # already hold — the case a host uses after loading a skill on its own
+    # initiative, so the agent reacts to it. Resets the step/cancellation
+    # controls, drains any pending {Control::Interloper} injections, then
+    # +complete+s the chat. Output is the listeners' job; subsequent calls
+    # build on the same history.
+    #
+    # A blank +user_message+ against a conversation holding nothing but the
+    # system prompt is provider-split: providers that can't complete it raise
+    # {EmptyTurnError}, the rest run the turn against that history. A blank turn
+    # *mid-conversation* always proceeds — real turns remain to answer, and a
+    # drained injection is itself one.
+    #
+    # Step-limit and cancellation trips are handled per the class header's
+    # "Step-exhaustion policy" / "Cancellation rescue".
     #
     # == Switching models mid-conversation
     #
-    # Passing a +transport:+ that differs from the current one
-    # switches the underlying chat to that model — via
-    # +Chat#with_model+, so the history and the registered
-    # callbacks survive — re-resolves the context-window cap, and
-    # emits an {Event::ModelSwitched} followed by a fresh
-    # {Event::ContextCap}. The switch is deliberately confined to
-    # the top of this method (a private +apply_transport!+) rather
-    # than exposed as a standalone setter: the chat is
-    # single-thread-confined, so doing it here serializes the swap
-    # with the turn on the loop's own thread — a background thread
-    # mutating +with_model+'s connection mid-completion would tear
-    # an in-flight stream. A +nil+ +transport:+ (the default) keeps
-    # the current model. The conversation is *not* re-baselined: a
-    # switch is the same conversation under a new model, so the
-    # message count and running context size carry over (the next
-    # turn's token report self-corrects to the new model's count).
-    #
-    # @param user_message [String] the user's request for this
-    #   turn; must not be +nil+, empty, or whitespace-only
-    # @param transport [ChatTransport, nil] when non-+nil+ and
-    #   structurally different from the current transport, switch to
-    #   it before running the turn (see above); +nil+ keeps the
-    #   current model
-    # @raise [ArgumentError] if +user_message+ is +nil+, empty,
-    #   or contains only whitespace — an empty turn would poison
-    #   the chat history and burn a step budget on nothing
-    # @raise [Control::Cancellable::Cancelled] if the registered
-    #   {Control::Cancellable} was triggered during the turn;
-    #   the listener stream sees an {Event::Cancelled} first
-    # @raise [Control::StepLimit::Exceeded] if the step budget
-    #   tripped and its policy is +:raise+ (the default)
-    # @return [nil]
-    def run_loop(user_message:, transport: nil)
-      raise ArgumentError, "user_message must not be blank, got #{user_message.inspect}" \
-        if user_message.nil? || user_message.to_s.strip.empty?
-
+    # A +transport:+ differing from the current one switches the chat to it
+    # (via {#apply_transport!}), re-resolves the cap, and emits
+    # {Event::ModelSwitched} + a fresh {Event::ContextCap}. The switch is
+    # confined to the top of this method because the chat is
+    # single-thread-confined — a background thread mutating the connection
+    # mid-completion would tear an in-flight stream. The conversation is
+    # *not* re-baselined: same conversation, new model, so message count and
+    # running context size carry over. +nil+ keeps the current model.
+    #
+    # == Repairing an unwound tool batch
+    #
+    # ruby_llm appends the assistant +tool_calls+ message *before* running any
+    # of them, so anything unwinding out of the batch — a tool raising, a
+    # {Control::Cancellable::Cancelled}, a tripped budget, an untrapped
+    # +Interrupt+ — leaves calls no +:tool+ message answers. OpenAI and
+    # Anthropic 400 on that; a local llama.cpp feeds it to the chat template
+    # and the model improvises. So an +ensure+ answers each dangling call
+    # ({#repair_dangling_tool_calls!}) and the exception then propagates: a
+    # host that keeps the conversation gets one it can still send.
+    #
+    # +ensure+ rather than a clause per +rescue+, because it also catches what
+    # nobody enumerated (+Interrupt+ is no +StandardError+) and it runs *after*
+    # the +:synthesize+ rescue body, leaving {Synthesizer.build_prompt} the
+    # unrepaired history its drop-calls-with-no-result pass expects.
+    #
+    # Unlike {History#repair_interrupted_tool_calls} — the load path, where a
+    # killed process leaves no clue and {History::INTERRUPTED_RESULT} has to be
+    # generic — the cause is in hand here and picks the wording.
+    #
+    # @param user_message [String, nil] the turn's request; +nil+/blank runs a
+    #   bare turn (see above)
+    # @param transport [ChatTransport, nil] when non-+nil+ and structurally
+    #   different, switch to it before the turn; +nil+ keeps the model
+    # @raise [Control::Cancellable::Cancelled] if cancelled mid-turn (an
+    #   {Event::Cancelled} is emitted first)
+    # @raise [Control::StepLimit::Exceeded] if the budget tripped under the
+    #   +:raise+ policy
+    # @raise [EmptyTurnError] on a blank turn against a prompt-only
+    #   conversation when the provider carries +:system+ outside +messages+
+    #   (see above)
+    # @return [nil] after a turn runs
+    def run_loop(user_message: nil, transport: nil)
       apply_transport!(transport) if transport
       @synth_answer = nil
       @step_limit&.reset!
       @cancellable&.reset!
-      # Append the user turn, emit it, then run the memory dispatch — so
-      # any <memory-context> the dispatch injects lands as a :system
-      # message *after* the user turn it annotates (append-only at the
-      # tail; see {#dispatch_ext_on_user_message}). `ask` would bundle the
-      # user-message append with completion atomically, leaving no seam to
-      # inject between them, so the two halves run explicitly here:
-      # add_message + complete (the exact pair `ask` is sugar for). A raw
-      # String content matches the interloper drain path.
-      @chat.add_message(role: :user, content: user_message)
-      @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
-      dispatch_ext_on_user_message(user_message)
+
+      # Deliver host-scheduled injections (e.g. a UI-loaded skill) before the
+      # first complete, so a freshly-scheduled block lands this turn rather
+      # than only after the next tool batch — ordered ahead of the user
+      # message appended below.
+      drain_interloper if @interloper
+
+      blank = user_message.nil? || user_message.to_s.strip.empty?
+      # These providers would send `messages: []` here (see EmptyTurnError).
+      # The drain above is what usually saves this case: an injected block is a
+      # :user message, so a skill-only bare load has something to complete
+      # against and falls through.
+      if blank && @chat.messages.all? { |m| m.role == :system } &&
+         SEPARATE_SYSTEM_FIELD_PROVIDERS.include?(@chat.model.provider.to_s)
+        raise EmptyTurnError, @chat.model.provider
+      end
+
+      unless blank
+        # Append the user turn, emit it, then run the memory dispatch — so any
+        # <memory-context> the dispatch injects lands as a :system message
+        # *after* the user turn it annotates. (+ask+ bundles append+complete
+        # atomically, leaving no seam to inject between; the halves run
+        # explicitly instead.)
+        track_message(@chat.add_message(role: :user, content: user_message))
+        @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
+        dispatch_ext_on_user_message(user_message)
+      end
+
       if @streaming
         @chat.complete(&streaming_block)
       else
@@ -393,28 +395,154 @@ module Pikuri
     rescue Control::StepLimit::Exceeded => e
       raise unless @step_limit&.on_exhausted == :synthesize
 
+      # Ruby restores +$!+ once a rescue clause completes normally, so the
+      # +ensure+ below would see no cause for this one unwind. Assigned before
+      # the synth runs, so a synth that raises doesn't displace the real reason.
+      exhausted = e
       @synth_answer = Synthesizer.run_synthesizer(@extension_context, @chat.messages, user_message)
       nil
+    ensure
+      repair_dangling_tool_calls!(exhausted || $!)
     end
 
-    # Release agent-owned resources. Fires every handler registered
-    # via {Configurator#on_close} (during the +Agent.new+ block) and
-    # {ExtensionContext#on_close} (during {Extension#bind} or any
-    # later hook), in LIFO order — matches Ruby +ensure+-block semantics
-    # so handlers registered later (which may depend on handlers
-    # registered earlier) tear down first. Each handler runs inside
-    # its own +rescue+; an exception is logged via
-    # +Pikuri.logger_for+ but doesn't abort the rest. Idempotent —
-    # subsequent calls are no-ops.
+    # Return the agent to a fresh-conversation state without tearing down
+    # its wiring — the host "/clear". Unlike {#close} (which fires the
+    # teardown handlers), everything stays alive; nothing is re-probed or
+    # re-connected. Resets, in order:
+    #
+    # 1. Chat history (+Chat#reset_messages!+, which also drops every injected
+    #    reference block), then re-applies a freshly **re-assembled** prompt —
+    #    {#assemble_system_prompt} re-pulls every extension's snippets, so
+    #    dynamic sections refresh (a resident memory persona, a re-read
+    #    +MACHINE.md+). Callbacks and tool registrations on the reused +@chat+
+    #    are untouched.
+    # 2. Controls — step/cancellation reset, interloper queue drained (stale
+    #    mid-loop input must not leak forward), cached synth answer dropped.
+    # 3. Listeners — a single {Event::Reset} so they reset display state.
+    # 4. Extension state — {Extension#on_conversation_reset} on each.
+    #
+    # Model/transport are left as-is (a clear is not a model switch). Runs on
+    # the agent's own thread; not designed to race an in-flight {#run_loop}.
+    #
+    # @return [void]
+    def clear_conversation
+      @chat.reset_messages!
+      @message_meta.clear
+      @system_prompt = assemble_system_prompt
+      @chat.with_instructions(@system_prompt)
+      @synth_answer = nil
+      @step_limit&.reset!
+      @cancellable&.reset!
+      @interloper&.drain!
+      @listeners.emit(Event::Reset.new)
+      @extensions.each { |ext| ext.on_conversation_reset(@extension_context) }
+      nil
+    end
+
+    # Snapshot the conversation as a {History} — the round-trip partner of
+    # {#load_history!}, and the supported way for a host to persist a
+    # conversation without reaching into the underlying chat.
+    #
+    #   agent.export_history.save(dir)          # a folder per conversation
+    #   File.write(f, agent.export_history.to_json)   # or one self-contained file
+    #
+    # The system prompt is excluded — {#load_history!} re-assembles it, so a
+    # resumed conversation gets today's, not the one that was current when it
+    # was saved.
+    #
+    # Attachment bytes are read here, eagerly, so the snapshot still shows
+    # what the model saw after the file has changed on disk.
+    #
+    # A thinking block withheld from the conversation because another model
+    # produced it is restored here from the message's metadata, so the record
+    # survives any number of load/save cycles under a switched model.
+    #
+    # @return [History]
+    def export_history
+      exported = @chat.messages.reject { |m| m.role == :system }.map do |msg|
+        meta = @message_meta[msg] || { id: History.mint_id, kind: 'user' }
+        exported_msg = History::Message.from_ruby_llm(msg, id: meta[:id], kind: meta[:kind])
+        meta[:thinking] ? exported_msg.with(thinking: meta[:thinking]) : exported_msg
+      end
+      History.new(messages: exported)
+    end
+
+    # Replace the conversation with a saved one, keeping every bit of wiring
+    # — tools, listeners, extensions, model — in place.
+    #
+    #   agent.load_history!(History.load(dir))
+    #
+    # Runs {#clear_conversation} first, so controls reset and extensions see
+    # {Extension#on_conversation_reset} exactly as they would on a host
+    # "/clear"; the system prompt is re-assembled from current state. Then
+    # emits {Event::HistoryLoaded} — {Event::Reset} alone would tell listeners
+    # the conversation is empty, which it no longer is.
+    #
+    # Safe to call repeatedly on a long-lived agent: switching conversations
+    # in a shell is exactly this, once per switch, and nothing survives across
+    # one. Like the rest of {Agent}, it must not race a running {#run_loop}.
+    #
+    # == What is restored, and what is not
+    #
+    # Messages, tool calls and their results, thinking, attachments, per-message
+    # usage. **Not** state living outside the conversation: a workspace's
+    # read-before-edit marks, promoted skills, a task list. A resumed
+    # conversation whose transcript says a file was read will still be asked
+    # to read it again before editing — which is right, since the file may
+    # have changed while the conversation sat on disk.
+    #
+    # Two repairs happen on the way in, both because a stored conversation can
+    # describe something a provider will not accept:
+    #
+    # - A tool call whose result never arrived gets a synthesized one
+    #   ({History#repair_interrupted_tool_calls}).
+    # - A turn produced by a *different* model loses its whole thinking block
+    #   — a foreign one lands in a slot the receiving model reads as its own
+    #   scratchpad. Withheld from the conversation only; {#export_history}
+    #   still writes it. {#apply_transport!} repeats this for a switch that
+    #   happens later. See +DECISIONS.md+ +D_thinking_block_replay+.
+    #
+    # @param history [History] from {#export_history}, {History.parse} or
+    #   {History.load} — already validated by whichever door it came through.
+    # @return [Integer] how many messages were restored.
+    # @raise [ArgumentError] if given anything but a {History}; the parsing
+    #   doors are where untrusted input belongs.
+    def load_history!(history)
+      unless history.is_a?(History)
+        raise ArgumentError, "expected a Pikuri::Agent::History, got #{history.class} — " \
+                             'use History.parse / History.load to build one from stored bytes'
+      end
+
+      clear_conversation
+      current_model = @chat.model&.id
+      repaired = history.repair_interrupted_tool_calls
+      repaired.messages.each do |m|
+        keep = keep_thinking?(m.thinking, m.model_id, current_model)
+        track_message(@chat.add_message(m.to_ruby_llm(keep_thinking: keep)),
+                      kind: m.kind, id: m.id, thinking: (m.thinking unless keep))
+      end
+
+      last = repaired.messages.reverse.find { |m| m.role == 'assistant' && m.tokens }
+      @listeners.emit(Event::HistoryLoaded.new(
+                        messages: repaired.messages.size,
+                        tokens: last && Event::Tokens.new(**last.tokens.to_h, model_id: last.model_id)
+                      ))
+      repaired.messages.size
+    end
+
+    # Release agent-owned resources: fire every handler registered via
+    # {Configurator#on_close} and {ExtensionContext#on_close} in LIFO order,
+    # so a handler that depends on an earlier one tears down first. Each runs
+    # in its own +rescue+ (an exception is logged, not propagated).
+    # Idempotent.
     #
     # @return [void]
     def close
       return if @closed
 
       @closed = true
-      # Drop out of the process-global registry first: a deliberate
-      # close means this agent no longer needs the at-exit fallback,
-      # and removing the reference lets it be garbage-collected.
+      # Drop out of the registry first: a deliberate close no longer needs
+      # the at-exit fallback, and dropping the reference frees it for GC.
       Pikuri::Finalizers.unregister(self)
       @on_close_handlers.reverse_each do |handler|
         handler.call
@@ -435,17 +563,36 @@ module Pikuri
       "Agent(id=#{@id}, model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
     end
 
+    # This agent's lethal-trifecta picture: which legs it holds, which its
+    # sub-agents hold, the verdict at every node.
+    #
+    #   puts agent.trifecta.render        # the map a bin script prints
+    #   agent.trifecta.tree_verdict       # => :soft
+    #
+    # Memoized and pure, so a UI may call it as often as it likes. Nothing
+    # reports this for you: an Agent computes the picture and stops, because a
+    # library writing to a log its embedder never asked for is noise. Surfacing
+    # it is the host's job — the bundled +bin/pikuri-*+ scripts print
+    # {Trifecta::Report#render} at boot.
+    #
+    # Valid only after construction (it reads the wired tool list), and it
+    # reflects the tools present *then*.
+    #
+    # @return [Trifecta::Report] root of the walked tree
+    def trifecta
+      @trifecta ||= Trifecta.walk(Trifecta.build(self))
+    end
+
     private
 
     # The failure-prone build phase, split out of {#initialize} so the
     # constructor can wrap it in a rescue and self-heal. Funnels the
-    # +Agent.new+ block through a single {Configurator} — tools,
-    # listeners, system-prompt snippets, extensions, and +on_close+
-    # handlers — then wires the chat and runs the extension +bind+
-    # sweep. The Configurator's +on_close_sink:+ is +@on_close_handlers+
-    # itself, so a handler an extension arms via +c.on_close+ is live on
-    # the agent the instant it's registered — that's what lets the
-    # constructor's rescue close a half-built agent.
+    # +Agent.new+ block through one {Configurator} (tools, listeners,
+    # snippets, extensions, +on_close+), wires the chat, then runs the
+    # extension +bind+ sweep. The Configurator's +on_close_sink:+ is
+    # +@on_close_handlers+ itself, so a handler armed via +c.on_close+ is
+    # live the instant it's registered — what lets the rescue close a
+    # half-built agent.
     #
     # @return [void]
     def run_configure
@@ -465,25 +612,34 @@ module Pikuri
       @tools = configurator.tools.dup
       @sub_agent_tools = configurator.sub_agent_tools.dup
       @listeners = ListenerList.new(configurator.listeners)
-      configurator.system_prompt_additions.each do |snippet|
-        @system_prompt = "#{@system_prompt}\n\n#{snippet}"
-      end
       @extensions = configurator.extensions.dup
+      # Assemble now that every extension's +configure+ has run (their
+      # snippets read populated state); re-runs on {#clear_conversation}.
+      @system_prompt = assemble_system_prompt
 
       @chat = build_chat(@transport)
       @chat.with_instructions(@system_prompt)
-      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
-
-      # Wire @chat for pikuri's event stream and controls — the
-      # three message-level registered callbacks (+after_message+,
-      # +before_tool_call+, +after_tool_result+). The per-chunk
-      # streaming callback is separate because ruby_llm takes it as
-      # a block to +Chat#complete+ rather than a registered hook —
-      # see {#streaming_block}. Together with the +@listeners.emit+
-      # calls in {#run_loop} / {#dispatch_ext_on_user_message} this
-      # is the complete "which callback emits which event" map.
+      # One context per agent, so an opting-in +execute+ never has to nil-check
+      # what it was handed.
+      context = Tool::ExecuteContext.new(cancellable: @cancellable || Control::Cancellable::NEVER)
+      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool(context: context)) }
+
+      # Wire @chat for the event stream and controls via ruby_llm's three
+      # registered callbacks. (The per-chunk streaming callback is separate
+      # — {#streaming_block} — since ruby_llm takes it as a block to
+      # +Chat#complete+, not a registered hook.) With the +@listeners.emit+
+      # calls in {#run_loop}/{#dispatch_ext_on_user_message}, this is the
+      # complete callback→event map.
+      # Identity-keyed, so nothing can drift out of alignment with
+      # +@chat.messages+ the way a parallel array would: a message pikuri
+      # never saw is simply absent here, and {#export_history} mints it an id
+      # rather than silently pairing it with someone else's.
+      @message_meta = {}.compare_by_identity
+
       @chat.after_message do |msg|
+        track_message(msg)
         emit_after_message(msg)
+        drain_interloper if @interloper && tool_batch_complete?(msg)
       end
       @chat.before_tool_call do |tc|
         @listeners.emit(Event::ToolCall.new(name: tc.name, arguments: tc.arguments))
@@ -492,54 +648,61 @@ module Pikuri
       end
       @chat.after_tool_result do |result|
         @listeners.emit(Event::ToolResult.new(content: result))
-        drain_interloper if @interloper
       end
 
-      # Context-window cap: lets every listener that cares (notably
-      # TokenLog) pick the value off the stream before any Tokens
-      # event arrives. Re-fires on each model switch (see
-      # {#apply_transport!}).
+      # Context-window cap on the stream before any Tokens event; re-fires
+      # on each model switch (see {#apply_transport!}).
       detect_and_emit_context_cap!
 
-      # The runtime capability facade — constructed once, after the
-      # chat and listener list are final, and handed to every
-      # extension's #bind / #on_user_message. The ONLY object that
-      # grants emission / raw-tool-registration / close-handler
-      # capabilities; the Agent itself exposes no public path to
-      # them. See {ExtensionContext}.
+      # The runtime capability facade — the ONLY object granting
+      # emission / raw-tool / close-handler capabilities; the Agent exposes
+      # no public path to them. Handed to every extension's #bind /
+      # #on_user_message. See {ExtensionContext}.
       @extension_context = ExtensionContext.new(
         agent: self, chat: @chat, listeners: @listeners,
         on_close_sink: @on_close_handlers
       )
 
-      # Bind sweep — each extension gets its chance to install
-      # per-agent state (dynamic tools via
-      # {ExtensionContext#add_raw_tool}, per-agent close hooks via
-      # {ExtensionContext#on_close}, domain-event wiring via
-      # {ExtensionContext#emit_event}, etc.) now that the chat is
-      # fully wired. See IDEAS.md §"Extension protocol design" for
-      # what #configure vs #bind are each for.
+      # Bind sweep — each extension installs per-agent state now the chat is
+      # fully wired (dynamic tools, close hooks, domain-event wiring). See
+      # {Extension} for #configure vs #bind.
       @extensions.each { |ext| ext.bind(@extension_context) }
     end
 
-    # Resolve the context-window cap and announce it on the listener
-    # stream as an {Event::ContextCap}. The transport's explicit
-    # +context_window+ wins verbatim; otherwise {ContextWindowDetector}
-    # probes the server (yielding +nil+ for a non-llama one). Because the
-    # cap rides {ChatTransport}, a model switch resolves the *new*
-    # transport's cap — explicit caps don't bleed across models. Shared
-    # by {#run_configure} (construction) and {#apply_transport!} (each
-    # model switch) so "how the cap is resolved and emitted" lives in
-    # one place.
+    # Build the full prompt: base plus every extension's
+    # {Extension#system_prompt_snippets}, in registration order, joined by
+    # blank lines. Blank/nil sections drop (an extension contributing
+    # nothing leaves no stray separator). Pure function of the base + the
+    # extensions' current state, so it serves both construction and
+    # {#clear_conversation} (the latter refreshing dynamic sections).
+    #
+    # Those two call sites are the whole list, and that is a *price* rather
+    # than a missing feature: a stable prefix is free after turn one
+    # (llama.cpp slot prefix-reuse, Anthropic's prompt cache), where amending
+    # one invalidates every cached token after the change point and
+    # re-prefills. Hence there is no amend-the-prompt seam — mid-conversation
+    # blocks go through {#append_reference_block}, which appends and
+    # invalidates nothing. See `DECISIONS.md` `D_reference_text_as_user_turn`.
+    #
+    # @return [String]
+    def assemble_system_prompt
+      sections = @extensions.flat_map(&:system_prompt_snippets)
+      [@system_prompt_base, *sections]
+        .reject { |s| s.nil? || s.to_s.strip.empty? }
+        .join("\n\n")
+    end
+
+    # Resolve the context-window cap and announce it as an
+    # {Event::ContextCap}. The transport's explicit +context_window+ wins;
+    # else {ContextWindowDetector} probes the server (+nil+ for a non-llama
+    # one). The cap rides {ChatTransport}, so a switch resolves the *new*
+    # transport's cap. Shared by {#run_configure} and {#apply_transport!}.
     #
     # @return [void]
     def detect_and_emit_context_cap!
-      # Probe the server this transport actually targets — after a
-      # cross-server switch the chat's connection points at
-      # +@transport.api_base+, but the process-global config the
-      # detector defaults to still names the *old* server, so derive the
-      # base from the transport (falling back to the global base for a
-      # transport that rides it).
+      # Probe the server this transport targets: after a cross-server switch
+      # the chat points at +@transport.api_base+, but the global config still
+      # names the old server — so derive the base from the transport.
       @context_window_cap = @transport.context_window ||
                             ContextWindowDetector.detect(
                               @transport,
@@ -548,34 +711,27 @@ module Pikuri
       @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
     end
 
-    # Switch the underlying chat to +transport+ when it differs from
-    # the current one. Called only from the top of {#run_loop} — see
-    # that method's "Switching models mid-conversation" section for why
-    # the swap is confined to the loop's own thread.
-    #
-    # Mirrors {#initialize}'s +nil+-model fill before the structural
-    # comparison, so a +transport+ that defers its model to the default
-    # doesn't read as "different" and switch spuriously.
-    # +Chat#with_model+ swaps only the model / provider / connection,
-    # leaving +@chat+'s message history and registered callbacks
-    # intact, so the conversation continues seamlessly under the new
-    # model. Emits {Event::ModelSwitched} (the narration: old → new
-    # transport, unformatted, for the chrome to present) then re-resolves
-    # and re-emits the cap via {#detect_and_emit_context_cap!}.
+    # Switch the chat to +transport+ when it differs from the current one.
+    # Called only from the top of {#run_loop} (see its "Switching models"
+    # section for the thread-confinement reason). Mirrors {#initialize}'s
+    # +nil+-model fill before the structural compare, so a transport
+    # deferring to the default model doesn't switch spuriously.
+    # +Chat#with_model+ keeps history and callbacks. Emits
+    # {Event::ModelSwitched}, then re-resolves and re-emits the cap.
+    #
+    # Because the history is kept, every turn in it is now potentially from
+    # another model, so {#strip_foreign_thinking!} runs before the event —
+    # {#load_history!}'s repair only covers a conversation that arrives stale.
     #
     # == Cross-server switches
     #
-    # +with_model+ alone re-resolves against the chat's *existing*
-    # connection, so it can only move between models on one server. When
-    # either the new or the old transport overrides the connection
-    # (+ChatTransport#connection_overrides?+ — a different +api_base+ /
-    # +api_key+), the swap first installs a fresh +RubyLLM::Context+ via
-    # +Chat#with_context+ (which re-points the connection and re-resolves
-    # the model in place, again preserving history + callbacks) before
-    # +with_model+ lands the new model id. The "old overrode" half of
-    # the guard handles switching *back* to a global-config model: the
-    # rebuilt context dups the process-global config, resetting the
-    # connection the previous override installed.
+    # +with_model+ re-resolves against the chat's existing connection, so it
+    # only moves between models on one server. When either transport
+    # overrides the connection (+ChatTransport#connection_overrides?+), a
+    # fresh +RubyLLM::Context+ is installed via +Chat#with_context+ first
+    # (re-pointing the connection, preserving history + callbacks). The "old
+    # overrode" half handles switching *back* to a global-config model: the
+    # rebuilt context dups the global config, resetting the prior override.
     #
     # @param transport [ChatTransport] the model to switch to
     # @return [void]
@@ -587,14 +743,14 @@ module Pikuri
       @chat.with_context(build_context(filled)) if filled.connection_overrides? || old.connection_overrides?
       @chat.with_model(filled.model, provider: filled.provider, assume_exists: filled.assume_model_exists)
       @transport = filled
+      strip_foreign_thinking!
       @listeners.emit(Event::ModelSwitched.new(from: old, to: filled))
       detect_and_emit_context_cap!
     end
 
-    # Build the chat for +transport+: through a dedicated
-    # +RubyLLM::Context+ when it overrides the connection, else through
-    # the process-global +RubyLLM.chat+ (which the construction-time
-    # path has always used).
+    # Build the chat for +transport+: through a dedicated +RubyLLM::Context+
+    # when it overrides the connection, else through the process-global
+    # +RubyLLM.chat+.
     #
     # @param transport [ChatTransport]
     # @return [RubyLLM::Chat]
@@ -606,14 +762,18 @@ module Pikuri
       end
     end
 
-    # A +RubyLLM::Context+ carrying +transport+'s connection overrides
-    # mapped onto the provider's ruby_llm config slots
-    # (+#{provider}_api_base+ / +#{provider}_api_key+). +RubyLLM.context+
-    # dups the process-global config, so an absent override inherits the
-    # global value; a transport with no overrides yields a plain dup
-    # (used by {#apply_transport!} to reset a prior override). The
-    # +ChatTransport+ guarantees a non-+nil+ +provider+ whenever an
-    # override is set, so the slot name is always resolvable.
+    # A +RubyLLM::Context+ carrying +transport+'s connection overrides on the
+    # provider's config slots (+#{provider}_api_base+ / +_api_key+).
+    # +RubyLLM.context+ dups the global config, so an absent override inherits
+    # the global value and a no-override transport yields a plain dup (used by
+    # {#apply_transport!} to reset a prior override). +ChatTransport+
+    # guarantees a non-+nil+ +provider+ whenever an override is set.
+    #
+    # A transport's +faraday_adapter+ (if any) is installed here too: the
+    # adapter rides *this* context's config, not the process-global
+    # +RubyLLM.config+, so it stays per-agent — the seam
+    # {Pikuri::Testing.fake_transport} uses to run the real ruby_llm loop
+    # against a scripted HTTP backend.
     #
     # @param transport [ChatTransport]
     # @return [RubyLLM::Context]
@@ -622,33 +782,24 @@ module Pikuri
       RubyLLM.context do |c|
         c.public_send("#{slug}_api_base=", transport.api_base) unless transport.api_base.nil?
         c.public_send("#{slug}_api_key=", transport.api_key) unless transport.api_key.nil?
+        c.faraday_adapter = transport.faraday_adapter if transport.faraday_adapter
+        # ruby_llm defaults an OpenAI-family `:system` message to the newer
+        # `developer` role. OpenAI treats the two alike, but a local
+        # llama.cpp hands the role straight to the model's chat template,
+        # and a Qwen/Llama template has never seen `developer` — the system
+        # prompt then arrives under a role token the model was not trained
+        # on. pikuri targets local servers first, so ask for `system`.
+        c.openai_use_system_role = true if c.respond_to?(:openai_use_system_role=)
       end
     end
 
-    # Fire the per-turn {Extension#on_user_message} hook on every
-    # extension that defines it, appending any returned
-    # String text block to the chat as a +role: :system+
-    # message right after the user turn it annotates (callers append
-    # the +:user+ message first; this runs last). The system role is
-    # load-bearing — it tags the block as recalled reference (not new
-    # input) and keeps it excludable from a later extraction pass.
-    # See {Extension#on_user_message}.
-    #
-    # Each injected block also emits an {Event::SystemInjected} at
-    # this site, so the listener stream mirrors the log growth (the
-    # Terminal renders it; otherwise an injection would be invisible
-    # except as a downstream echo in the assistant's reasoning).
-    #
-    # Private and the single place the chat log grows by a memory
-    # block — keeps "what mutates the log, when" one grep in this
-    # file. Fired from {#run_loop} (initial turn) and from
-    # {#drain_interloper} (mid-loop interlopers). Called on every
-    # extension unconditionally — same as {Extension#configure} /
-    # {Extension#bind}: the hook is part of the protocol and the
-    # {Extension} module supplies a no-op default, so any extension
-    # that includes the module responds. An extension is "opted out"
-    # by leaving the default in place (it returns +nil+, injecting
-    # nothing), not by omitting the method.
+    # Fire {Extension#on_user_message} on every extension, appending any
+    # returned text via {#append_reference_block} right after the user turn it
+    # annotates (the caller appends the +:user+ message first).
+    #
+    # Called unconditionally — the {Extension} no-op default returns +nil+
+    # (injects nothing), so opting out means leaving the default, not omitting
+    # the method.
     #
     # @param content [String] the incoming user message
     # @return [void]
@@ -657,40 +808,209 @@ module Pikuri
         message = ext.on_user_message(@extension_context, content)
         next unless message.is_a?(String) && !message.strip.empty?
 
-        block = message.strip
-        @chat.add_message(role: :system, content: block)
-        @listeners.emit(Event::SystemInjected.new(content: block))
+        append_reference_block(message.strip)
+      end
+      nil
+    end
+
+    # Append host-originated reference text — a memory block, a loaded skill, a
+    # path-activation promotion, retrieved context — and emit
+    # {Event::SystemInjected}. Lands as a +role: :user+ message wrapped in
+    # +<system-reminder>+:
+    #
+    #   append_reference_block('<memory-context>…</memory-context>')
+    #   # the chat log grows by one :user message:
+    #   #   <system-reminder>
+    #   #   <memory-context>…</memory-context>
+    #   #   </system-reminder>
+    #
+    # The event carries the block *unwrapped* — the envelope is wire plumbing,
+    # and a listener rendering the tag would be showing the reader framing they
+    # did not write.
+    #
+    # == Implementation details
+    #
+    # +:user+ rather than +:system+ because a mid-conversation +:system+ message
+    # is not portable: Qwen3.6's chat template silently drops every one past the
+    # leading header, and providers carrying +:system+ in a separate field
+    # (Anthropic, Bedrock — see {SEPARATE_SYSTEM_FIELD_PROVIDERS}) merge it into
+    # the standing system prompt, so the block is presented as though it had
+    # always been there and stays in force. Neither failure is visible from
+    # anything pikuri can observe: the message is in the payload, the listener
+    # stream renders it, the history holds it. See +DECISIONS.md+
+    # +D_reference_text_as_user_turn+.
+    #
+    # A closing tag inside +content+ is escaped, so injected text (a file, a web
+    # page, an MCP tool's description) cannot close the envelope early and have
+    # what follows read as conversation.
+    #
+    # @param content [String] the block to inject, already stripped; callers
+    #   with their own semantic tag (+<memory-context>+) keep it — the envelope
+    #   nests around it
+    # @return [void]
+    def append_reference_block(content)
+      close = "</#{REFERENCE_TAG}>"
+      # Block form, not a replacement String: gsub reads `\&`, `\1` etc. out of
+      # the latter, so a tag carrying one would be mangled rather than escaped.
+      body = content.gsub(close) { "<\\/#{REFERENCE_TAG}>" }
+      # Tagged +reference+ so a restored conversation can tell pikuri's own
+      # injection from something the human typed — both land as +:user+.
+      track_message(@chat.add_message(role: :user, content: "<#{REFERENCE_TAG}>\n#{body}\n#{close}"),
+                    kind: 'reference')
+      @listeners.emit(Event::SystemInjected.new(content: content))
+      nil
+    end
+
+    # Remember pikuri's own identity for a message just added to the chat, so
+    # {#export_history} can hand out a stable id, say whether a +:user+ message
+    # was typed or injected, and put back a thinking block the conversation is
+    # not replaying. None of it ever reaches a provider.
+    #
+    # Keyed on the message *object*, so a caller that rebuilds one must move
+    # its entry across — see {#strip_foreign_thinking!}.
+    #
+    # @param msg [RubyLLM::Message] as returned by +Chat#add_message+.
+    # @param kind [String] one of {History::KINDS}.
+    # @param id [String, nil] an existing id to preserve (restoring a saved
+    #   conversation); +nil+ mints a fresh one.
+    # @param thinking [History::Thinking, nil] a block withheld from +msg+
+    #   because another model produced it, kept so the export stays faithful.
+    # @return [RubyLLM::Message] +msg+, so call sites can wrap in place.
+    def track_message(msg, kind: 'user', id: nil, thinking: nil)
+      unless msg.role == :system
+        @message_meta[msg] = { id: id || History.mint_id, kind: kind, thinking: thinking }
+      end
+      msg
+    end
+
+    # Whether a turn's thinking may be replayed to +current+ — true only where
+    # this model demonstrably produced it.
+    #
+    # Unknown provenance counts as foreign: a +model_id+ nobody recorded is
+    # indistinguishable from another model's, and attributing one model's
+    # reasoning to another is the failure this guards against.
+    #
+    # The two ids come from different places — +current+ is what pikuri
+    # *requested*, +model_id+ what the server *reported* — so a backend that
+    # does not echo the requested id back makes every turn look foreign. That
+    # only ever over-drops (a model loses its own reasoning; none is ever
+    # attributed to another), which is why the weaker test is tolerated; the
+    # fakes in +Pikuri::Testing+ are themselves such a backend. Measured
+    # echoing verbatim on llama.cpp — see +DECISIONS.md+
+    # +D_thinking_block_replay+.
+    #
+    # @param thinking [History::Thinking, RubyLLM::Thinking, nil]
+    # @param model_id [String, nil] who produced the turn.
+    # @param current [String, nil] the agent's model now.
+    # @return [Boolean]
+    def keep_thinking?(thinking, model_id, current)
+      thinking.nil? || (!model_id.nil? && model_id == current)
+    end
+
+    # Withhold every thinking block the current model did not produce from the
+    # live conversation, parking it in +@message_meta+ so {#export_history}
+    # still writes it.
+    #
+    # {#load_history!} covers a conversation that arrives stale; this covers
+    # one that goes stale under a running agent, which +Chat#with_model+ leaves
+    # untouched. +RubyLLM::Message+ has no thinking writer, so a stripped turn
+    # is a rebuilt object and its metadata is re-keyed onto the replacement.
+    #
+    # @return [void]
+    def strip_foreign_thinking!
+      current = @chat.model&.id
+      @chat.messages.map! do |msg|
+        next msg if keep_thinking?(msg.thinking, msg.model_id, current)
+
+        meta = @message_meta.delete(msg) || { id: History.mint_id, kind: 'user' }
+        stripped = RubyLLM::Message.new(
+          role: msg.role, content: msg.content, tool_calls: msg.tool_calls,
+          tool_call_id: msg.tool_call_id, model_id: msg.model_id,
+          tokens: msg.tokens, raw: msg.raw, thinking: nil
+        )
+        @message_meta[stripped] = meta.merge(
+          thinking: History::Thinking.new(text: msg.thinking.text, signature: msg.thinking.signature)
+        )
+        stripped
+      end
+    end
+
+    # Answer every call the last assistant turn left unanswered, emitting each
+    # synthesized observation as an {Event::ToolResult} so a host can show what
+    # it appended. Rationale in {#run_loop}'s +== Repairing an unwound tool
+    # batch+.
+    #
+    # Order carries the first-vs-rest split ({CANCELLED_RESULT}): +tool_calls+
+    # is insertion-ordered and ruby_llm runs it with +each_value+, so the first
+    # gap is the culprit — true only while +tool_concurrency+ stays off, which
+    # {Pikuri::Tool}'s +== Sharing+ asks for on separate grounds.
+    #
+    # Not {History#repair_interrupted_tool_calls}: damage here is always the
+    # tail, and that walk is over +History::Message+, whose +role+ is a +String+
+    # where ruby_llm's is a +Symbol+.
+    #
+    # @param cause [Exception, nil] what the turn is unwinding with; +nil+ on
+    #   the success path, where nothing dangles.
+    # @return [void]
+    # @raise [RuntimeError] if calls dangle with no +cause+ — pikuri lost a
+    #   batch on a turn that succeeded. Safe to raise from an +ensure+ here
+    #   precisely because there is no in-flight exception to clobber.
+    def repair_dangling_tool_calls!(cause)
+      messages = @chat.messages
+      opener_index = messages.rindex { |m| m.role == :assistant && m.tool_calls&.any? }
+      return if opener_index.nil?
+
+      answered = messages[(opener_index + 1)..].filter_map { |m| m.tool_call_id if m.role == :tool }
+      dangling = messages[opener_index].tool_calls.each_value.reject { |c| answered.include?(c.id) }
+      return if dangling.empty?
+
+      if cause.nil?
+        raise 'unanswered tool calls on a turn that did not unwind: ' \
+              "#{dangling.map { |c| "#{c.name}(#{c.id})" }.join(', ')}"
+      end
+
+      culprit, skipped = unanswered_results(cause)
+      dangling.each_with_index do |call, i|
+        content = i.zero? ? culprit : skipped
+        track_message(@chat.add_message(role: :tool, content: content, tool_call_id: call.id))
+        @listeners.emit(Event::ToolResult.new(content: content))
       end
+      LOGGER.warn { "answered #{dangling.size} dangling tool call(s) after #{cause.class}" }
       nil
     end
 
-    # Build the per-chunk streaming block passed to +Chat#complete+.
-    # Each invocation of the returned proc converts one
-    # +RubyLLM::Chunk+ into zero, one, or two delta events
-    # ({Event::ThinkingDelta} / {Event::AssistantDelta}) on
-    # +@listeners+. Tool-call chunks are intentionally ignored —
-    # partial JSON has no useful rendering; the assembled
-    # +tool_calls+ surface through {Event::ToolCall} once the
-    # message completes.
+    # @param cause [Exception]
+    # @return [Array(String, String)] what the call that raised (or was about
+    #   to) is told, then what the calls behind it that never started are told.
+    #   See {CANCELLED_RESULT}.
+    def unanswered_results(cause)
+      case cause
+      when Control::Cancellable::Cancelled then [CANCELLED_RESULT, CANCELLED_SKIPPED_RESULT]
+      # An exhausted budget singles no call out.
+      when Control::StepLimit::Exceeded then [STEP_BUDGET_RESULT, STEP_BUDGET_RESULT]
+      # Deliberately unsanitized: the message can carry untrusted bytes (a
+      # filename off a scraped page), which {Tool#run}'s own +"Error: ..."+
+      # already puts in the conversation — and a model cannot react to a
+      # failure it is not told about.
+      else ["Error: #{cause.class}: #{cause.message}", FAILED_SKIPPED_RESULT]
+      end
+    end
+
+    # Build the per-chunk block passed to +Chat#complete+. Each call converts
+    # one +RubyLLM::Chunk+ into zero, one, or two delta events
+    # ({Event::ThinkingDelta}/{Event::AssistantDelta}). Tool-call chunks are
+    # ignored — partial JSON has no useful rendering; the assembled call
+    # surfaces via {Event::ToolCall} once the message completes.
     #
     # == Cancellation polling
     #
-    # When +@cancellable+ is non-nil, {Control::Cancellable#check!}
-    # fires *before* each chunk's emit. The +before_tool_call+
-    # wiring in {#run_configure} only fires when the model requests a
-    # tool, which leaves a no-tool turn (e.g. a plain greeting)
-    # with zero cancellation points — Ctrl+C trips the flag but
-    # nothing reads it. Polling on every streamed chunk closes
-    # that gap: an in-flight Cancellation+check! raises on the
-    # next chunk delivered after the flag flips, the exception
-    # propagates out through ruby_llm's streaming path
-    # (+Chat#complete+ doesn't rescue), and {#run_loop} catches it,
-    # emits {Event::Cancelled}, and re-raises. The pre-emit
-    # ordering is deliberate: a chunk that arrives after a cancel
-    # request shouldn't render — the user has said stop.
-    #
-    # @return [Proc] a +-> (chunk) { ... }+ proc suitable for
-    #   passing to +Chat#complete+ with +&+
+    # When +@cancellable+ is set, {Control::Cancellable#check!} fires *before*
+    # each chunk's emit. The +before_tool_call+ wiring only fires on a tool
+    # request, so a no-tool turn (a plain greeting) has zero cancellation
+    # points; polling per chunk closes that gap. Pre-emit ordering is
+    # deliberate — a chunk arriving after a cancel request shouldn't render.
+    #
+    # @return [Proc] a +->(chunk) { ... }+ for +Chat#complete+
     def streaming_block
       ->(chunk) {
         @cancellable&.check!
@@ -698,21 +1018,39 @@ module Pikuri
       }
     end
 
-    # Normalize a +RubyLLM::Chat+ +after_message+ payload into
-    # zero, one, or two {Event} variants (+Thinking+ and/or
-    # +Assistant+) plus one {Event::Tokens} for the usage block.
-    # Empty thinking / empty content are filtered here so
-    # listeners never see vacuous events. Non-assistant roles
-    # (e.g. tool-role messages echoed back through
-    # +after_message+) are skipped entirely.
-    #
-    # +msg+ is a +RubyLLM::Message+. Beyond +role+, +content+,
-    # +thinking+, and the +*_tokens+ accessors used here, it also
-    # carries +msg.tool_calls+ on assistant turns that requested
-    # one and +msg.raw+ for the unparsed provider payload.
+    # Normalize an +after_message+ payload into zero, one, or two {Event}s
+    # (+Thinking+ and/or +Assistant+) plus one {Event::Tokens}. Empty
+    # thinking/content are filtered here so listeners never see vacuous
+    # events; non-assistant roles are skipped.
     #
     # @param msg [RubyLLM::Message]
     # @return [void]
+    # Whether +msg+ closed a tool batch — the only mid-turn moment an injected
+    # message may be appended.
+    #
+    # An assistant message carrying +tool_calls+ and the +:tool+ messages
+    # answering it are one indivisible unit on the wire: OpenAI rejects a
+    # +tool+ message that does not follow its call, Anthropic requires the
+    # results to open the very next message, and a local chat template groups
+    # them into one block. Anything appended between the two halves is
+    # therefore either an error or, worse, silently mangled prose — which is
+    # what draining at ruby_llm's +after_tool_result+ did, since that fires
+    # *before* the result message is added.
+    #
+    # @param msg [RubyLLM::Message]
+    # @return [Boolean] true when +msg+ is the last tool result its assistant
+    #   message was waiting for (so parallel calls drain once, at the end)
+    def tool_batch_complete?(msg)
+      return false unless msg.role == :tool
+
+      messages = @chat.messages
+      opener_index = messages.rindex { |m| m.role == :assistant && m.tool_calls&.any? }
+      return true if opener_index.nil?
+
+      answered = messages[(opener_index + 1)..].filter_map { |m| m.tool_call_id if m.role == :tool }
+      messages[opener_index].tool_calls.each_key.all? { |id| answered.include?(id) }
+    end
+
     def emit_after_message(msg)
       return unless msg.role == :assistant
 
@@ -732,16 +1070,9 @@ module Pikuri
                       ))
     end
 
-    # Normalize a +RubyLLM::Chunk+ from a streaming completion
-    # into zero, one, or two delta events
-    # ({Event::ThinkingDelta} / {Event::AssistantDelta}). Empty
-    # +thinking.text+ and empty +content+ are filtered here so
-    # listeners never see vacuous fragments. Tool-call deltas are
-    # intentionally skipped — see {#streaming_block}.
-    #
-    # +chunk+ is a +RubyLLM::Chunk+ (subclass of +RubyLLM::Message+),
-    # so the same +.thinking+ / +.content+ accessors used in
-    # {#emit_after_message} apply.
+    # Normalize a streaming +RubyLLM::Chunk+ into zero, one, or two delta
+    # events ({Event::ThinkingDelta}/{Event::AssistantDelta}). Empty
+    # fragments are filtered; tool-call deltas skipped (see {#streaming_block}).
     #
     # @param chunk [RubyLLM::Chunk]
     # @return [void]
@@ -753,26 +1084,37 @@ module Pikuri
       @listeners.emit(Event::AssistantDelta.new(content: content)) if content.is_a?(String) && !content.empty?
     end
 
-    # Drain the interloper queue: for each pending item, append a
-    # +role: :user+ message to the chat history so the next
-    # round-trip sees it, emit an {Event::UserTurn} with
-    # +mid_loop: true+ to the listener stream so renderers see the
-    # injection, then run the per-turn {Extension#on_user_message}
-    # dispatch (so mid-loop injections are prefetched + recorded
-    # exactly like initial turns).
+    # Drain the interloper queue, landing each item per its
+    # {Control::Interloper::Item#kind}:
+    #
+    # - +:user+ — append +role: :user+ verbatim, emit {Event::UserTurn}
+    #   (+mid_loop: true+), then run the {Extension#on_user_message} dispatch
+    #   (so mid-loop injections are prefetched + recorded like initial turns).
+    #   The dispatch runs *after* the append so an injected +<memory-context>+
+    #   lands right behind the turn it annotates.
+    # - +:system+ — {#append_reference_block}: reference text, so no
+    #   +on_user_message+ dispatch and no +UserTurn+.
     #
-    # The dispatch runs *after* the +:user+ append so any
-    # +<memory-context>+ it injects lands as a +:system+ message
-    # right behind the user turn it annotates — the same
-    # append-at-the-tail ordering {#run_loop} produces for initial
-    # turns.
+    # Both kinds reach the wire as +role: :user+ and differ in dispatch and in
+    # the envelope — only the +:system+ kind is wrapped. That is the whole
+    # distinction, and it is why the queue keeps two kinds rather than a
+    # +wrap:+ flag.
     #
     # @return [void]
+    # @raise [RuntimeError] on an unknown item kind (a bug — only the two
+    #   +inject_*+ producers exist)
     def drain_interloper
-      @interloper.drain!.each do |content|
-        @chat.add_message(role: :user, content: content)
-        @listeners.emit(Event::UserTurn.new(content: content, mid_loop: true))
-        dispatch_ext_on_user_message(content)
+      @interloper.drain!.each do |item|
+        case item.kind
+        when :user
+          @chat.add_message(role: :user, content: item.content)
+          @listeners.emit(Event::UserTurn.new(content: item.content, mid_loop: true))
+          dispatch_ext_on_user_message(item.content)
+        when :system
+          append_reference_block(item.content)
+        else
+          raise "unknown interloper item kind: #{item.kind.inspect}"
+        end
       end
     end
   end