pikuri-core 0.0.6 → 0.0.7

data/lib/pikuri/agent/extension.rb

@@ -10,6 +10,14 @@ module Pikuri
     # is fully constructed, and {#on_user_message} on every user turn
     # thereafter.
     #
+    # Each phase receives that phase's context object: +configure+
+    # gets the build-time {Configurator}; +bind+ and
+    # +on_user_message+ get the runtime {ExtensionContext} — the
+    # capability facade for everything that acts on the live agent
+    # (domain-event emission, raw tool registration, sub-agent
+    # listener derivation), with the agent itself readable via
+    # {ExtensionContext#agent}.
+    #
     # Mix this module into an extension class to inherit empty
     # default implementations of all three hooks; override the ones
     # you need. Extensions that don't +include+ this module still
@@ -59,25 +67,30 @@ module Pikuri
       def configure(c); end
 
       # Called by {Agent#initialize} after the block returns and the
-      # chat is fully wired, with the live {Agent} as the argument.
-      # Fires once per agent the extension was registered to via
-      # {Configurator#add_extension} — in the typical setup that's
-      # the parent agent only, since sub-agents do not inherit
-      # extensions. The default is a no-op; override when you need
-      # to install state keyed to the live agent object. Things
-      # you typically do here:
+      # chat is fully wired, with the agent's {ExtensionContext} as
+      # the argument. Fires once per agent the extension was
+      # registered to via {Configurator#add_extension} — in the
+      # typical setup that's the parent agent only, since sub-agents
+      # do not inherit extensions. The default is a no-op; override
+      # when you need to install state keyed to the live agent.
+      # Things you typically do here:
       #
-      # * register dynamic tools via {Agent#internal_add_tool}
+      # * register dynamic tools via {ExtensionContext#add_raw_tool}
       #   (used by {Pikuri::Mcp::Extension} for +mcp_connect+,
-      #   whose +execute+ closure needs the live agent so
-      #   activations register on the right chat)
-      # * register +on_close+ handlers via {Agent#on_close}
-      # * stash an +@agent+ reference if the extension's tools need
-      #   to act on this specific agent later
+      #   whose +execute+ closure needs the context so activations
+      #   register on the right chat)
+      # * wire domain-event emission via
+      #   {ExtensionContext#emit_event} (e.g. +Pikuri::Tasks::Extension+
+      #   arms its list's +on_change+ here)
+      # * register per-agent +on_close+ handlers via
+      #   {ExtensionContext#on_close}
+      # * stash the +ctx+ if the extension's tools need to act on
+      #   this specific agent later
       #
-      # @param agent [Agent] the live agent, fully wired
+      # @param ctx [ExtensionContext] capability facade for the
+      #   live, fully wired agent
       # @return [void]
-      def bind(agent); end
+      def bind(ctx); end
 
       # Optional per-turn hook fired by the {Agent} after a user-message
       # is added to the chat. The
@@ -97,12 +110,13 @@ module Pikuri
       # only — sub-agents do not inherit extensions, so a persona's turns are
       # never prefetched or recorded by the parent's memory.
       #
-      # @param agent [Agent] the live agent whose turn this is
+      # @param ctx [ExtensionContext] capability facade for the live
+      #   agent whose turn this is — same instance +bind+ received
       # @param content [String] the user message (initial or interloper) about
       #   to be sent to the model
       # @return [String, nil] an optional block of text to be injected verbatim as
       #   a system-role message (after the user message), or +nil+ to inject nothing
-      def on_user_message(agent, content); end
+      def on_user_message(ctx, content); end
     end
   end
 end

data/lib/pikuri/agent/extension_context.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # Capability facade handed to {Extension#bind} and
+    # {Extension#on_user_message} — the runtime counterpart of
+    # {Configurator}. Where the Configurator collects *build-time*
+    # declarations (tools, listeners, prompt snippets), this object
+    # grants the *runtime* capabilities an extension needs once the
+    # agent is fully wired: emitting domain events onto the listener
+    # stream, registering raw per-agent tools, and deriving sub-agent
+    # listener lists.
+    #
+    # == Why a handed object, not a getter on Agent
+    #
+    # The {Agent} deliberately exposes NO public path to these
+    # capabilities — no +listeners+ reader, no +chat+ reader, no
+    # emit method. Holding an agent reference grants read access to
+    # its configuration ({Agent#tools}, {Agent#transport}, ...) and
+    # nothing more; the write capabilities live here, and the only
+    # way to obtain this object is to be an {Extension} receiving a
+    # +bind+ / +on_user_message+ call (or to be handed it onward by
+    # one, e.g. {Pikuri::SubAgent::SubAgentTool} and
+    # {Pikuri::Mcp::Servers::Connect} both capture the context their
+    # extension's +bind+ received). Capabilities flow by explicit
+    # handoff, never by fetching from a globally reachable object.
+    #
+    # The usual Ruby caveat applies: nothing here is mechanically
+    # sealed (+instance_variable_get+ exists). The boundary is the
+    # API contract — same as every seam in CLAUDE.md.
+    #
+    # == Boundary rule
+    #
+    # Operations that *act on* the live agent's wiring live here.
+    # Passive readers of constructor-given config (+transport+,
+    # +id+, +streaming+, +tools+, +cancellable+, ...) stay on
+    # {Agent}, reachable via {#agent}. Don't move readers in; don't
+    # add capabilities to Agent.
+    #
+    # == Audit
+    #
+    # One context per agent, constructed by {Agent#initialize} right
+    # before the extension +bind+ sweep. {ListenerList#emit} has
+    # exactly two callers: {Agent} (loop narration) and this class
+    # (extension domain events). The roster of capability users is
+    # +grep -rn 'emit_event\|add_raw_tool\|sub_agent_listeners'
+    # pikuri-*/lib/+.
+    class ExtensionContext
+      # @param agent [Agent] the live, fully wired agent.
+      # @param chat [RubyLLM::Chat] the agent's underlying chat —
+      #   target of {#add_raw_tool}.
+      # @param listeners [ListenerList] the agent's listener list —
+      #   target of {#emit_event} / {#sub_agent_listeners}.
+      # @param on_close_sink [Array<Proc>] the agent's live
+      #   +@on_close_handlers+ array, which {#on_close} appends to —
+      #   same live-sink shape as {Configurator}'s +on_close_sink:+.
+      def initialize(agent:, chat:, listeners:, on_close_sink:)
+        @agent = agent
+        @chat = chat
+        @listeners = listeners
+        @on_close_handlers = on_close_sink
+      end
+
+      # @return [Agent] the live agent, for read access to its
+      #   configuration (tools, transport, id, streaming, ...).
+      attr_reader :agent
+
+      # Emit a domain event onto the agent's listener stream.
+      #
+      # Core {Event} variants narrate the chat loop and are emitted
+      # by {Agent} alone; gems define their own variants (e.g.
+      # +Pikuri::Tasks::ListChanged+) in their own namespace and
+      # emit them here. Listeners must no-op on variants they don't
+      # recognize — {Listener::Base#on_event}'s default and
+      # +case+-fallthrough give that for free.
+      #
+      # Called on the agent's thread (typically from inside a tool's
+      # +execute+, where the event lands between {Event::ToolCall}
+      # and {Event::ToolResult} in the stream). Listeners doing
+      # cross-thread handoff snapshot/serialize inside +on_event+.
+      #
+      # @param event [Object] an immutable event value (by
+      #   convention a +Data+ instance).
+      # @return [void]
+      def emit_event(event)
+        @listeners.emit(event)
+        nil
+      end
+
+      # Register a raw +RubyLLM::Tool+ subclass on the agent's
+      # underlying chat, bypassing the {Pikuri::Tool}
+      # strict-validation seam — hence "raw": native pikuri tools
+      # should go through {Pikuri::Tool} (registered at build time
+      # via {Configurator#add_tool}) so they get {Tool::Parameters}
+      # validation and the LLM-actionable +"Error: ..."+ contract.
+      # Intended callers: {Pikuri::Mcp::Servers} (MCP tools
+      # deliberately bypass — see IDEAS.md §"MCP tools bypass
+      # +Pikuri::Tool+ entirely") and
+      # {Pikuri::SubAgent::Extension} (the +agent+ tool must
+      # register after the parent's tool list is final).
+      #
+      # The added tool does NOT enter {Agent#tools}, only the chat's
+      # tool list. Sub-agents therefore cannot snapshot it — which
+      # is the whole point: activation is strictly per-agent, see
+      # IDEAS.md §"Per-agent activation, no propagation".
+      #
+      # @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
+      # @return [void]
+      def add_raw_tool(ruby_llm_tool)
+        @chat.with_tool(ruby_llm_tool)
+        nil
+      end
+
+      # Derive a listener list for a spawned sub-agent via
+      # {ListenerList#for_sub_agent}. Sole intended caller:
+      # {Pikuri::SubAgent::SubAgentTool}, once per spawn.
+      #
+      # The derived list deliberately aliases the parent's listener
+      # *instances* where a listener opts to share by reference
+      # (stateful sinks like {Listener::InMemoryEventList}) — see
+      # {ListenerList#for_sub_agent} for the per-listener semantics.
+      #
+      # @param params [Hash{Symbol => Object}] forwarded to each
+      #   listener's +for_sub_agent+ hook (currently +id:+).
+      # @return [ListenerList]
+      def sub_agent_listeners(**params)
+        @listeners.for_sub_agent(**params)
+      end
+
+      # Register a handler called by {Agent#close}. Symmetric to
+      # {Configurator#on_close} — same LIFO + per-handler-rescue +
+      # idempotent semantics — but available post-construction, so
+      # an {Extension}'s +bind+ can install per-agent cleanup keyed
+      # to this specific agent (e.g. +Pikuri::Memory::Extension+
+      # arms its recorder's bounded flush here).
+      #
+      # @yield called with no arguments at close time
+      # @return [void]
+      def on_close(&blk)
+        raise ArgumentError, 'on_close requires a block' unless block_given?
+
+        @on_close_handlers << blk
+        nil
+      end
+    end
+  end
+end

data/lib/pikuri/agent/listener/terminal.rb

@@ -8,7 +8,8 @@ module Pikuri
       # Terminal renderer for the normalized event stream: dim grey
       # reasoning, assistant content printed raw (Markdown as-is),
       # cyan tool-call and tool-result lines, yellow fallback
-      # notice, red cancelled notice. An {Event::SystemInjected} block (recalled
+      # notice, red cancelled notice, magenta model-switch notice.
+      # An {Event::SystemInjected} block (recalled
       # memory / context an extension injected) renders dim grey
       # with a +⊕+ marker. {Event::UserTurn} is intentionally silent
       # (the terminal user just typed the message, so re-rendering
@@ -131,6 +132,8 @@ module Pikuri
             println(indent(Rainbow("→ #{name}(#{args})").cyan))
           in Event::ToolResult(content:)
             println(indent(Rainbow("= #{truncate_tool_result(content)}").cyan))
+          in Event::ModelSwitched(from:, to:)
+            println(indent(Rainbow("⇄ model: #{from.model} → #{to.model}").magenta))
           in Event::FallbackNotice(reason:)
             println(indent(Rainbow("! #{reason}").yellow))
           in Event::Cancelled
@@ -234,12 +237,20 @@ module Pikuri
         # exactly this" from "tool returned much more, you're
         # seeing a slice."
         #
+        # Whitespace is flattened *first* (collapsing real tabs, CRs and
+        # newlines into single spaces — fine here, since this passive
+        # echo is a status line, not an approval artifact), then the
+        # result runs through {Pikuri::Sanitizer} so a tool observation
+        # can't smuggle an ESC or other control byte into this cyan line.
+        # The sanitizer's warnings are dropped — they belong at a
+        # confirmation prompt, not the stream narration.
+        #
         # @param content [String] tool observation
         # @return [String] single-line display form, possibly
         #   truncated
         def truncate_tool_result(content)
           original_bytes = content.to_s.bytesize
-          flattened = content.to_s.gsub(/\s+/, ' ').strip
+          flattened = Sanitizer.sanitize(content.to_s.gsub(/\s+/, ' ').strip).text
           return flattened if flattened.length <= MAX_TOOL_RESULT_CHARS
 
           "#{flattened[0, MAX_TOOL_RESULT_CHARS]}… (#{original_bytes} bytes total)"

data/lib/pikuri/agent/listener/token_log.rb

@@ -6,8 +6,12 @@ module Pikuri
       # Logs the conversation's context-window consumption per
       # assistant turn via +Pikuri.logger_for('Tokens')+. Consumes
       # {Event::Tokens} (one log line per emission) and
-      # {Event::ContextCap} (one-shot cap, picked off and cached);
-      # every other event variant is a no-op.
+      # {Event::ContextCap} (the cap, picked off and cached —
+      # refreshed if a later {Event::ContextCap} arrives after a
+      # model switch); every other event variant is a no-op. A
+      # switch does not reset the running size or message count: the
+      # next {Event::Tokens} self-corrects the headline to the new
+      # model's count.
       #
       # Existence rationale: catch context-window growth before the
       # provider raises +RubyLLM::ContextLengthExceededError+.
@@ -96,12 +100,19 @@ module Pikuri
         #   listener you get a fresh instance via {#for_sub_agent}.
         attr_reader :id
 
-        # The most recent log line, in the exact format written to
-        # {LOGGER} (including any +[<id>] + prefix). Empty until
-        # the first {Event::Tokens} has been processed. Hosts that
+        # The most recent status line, *without* the +[<id>] +
+        # prefix — the prefix is {LOGGER}'s concern (the log
+        # stream interleaves agents, so its lines must carry the
+        # id inline); consumers of this reader get the id
+        # separately ({#id} here, the first callable parameter on
+        # {#on_status_line}) and decide the presentation
+        # themselves. Empty until the first {Event::Tokens} has
+        # been processed. Hosts that
         # want to surface the current context-window snapshot in
         # their own UI (e.g. a TUI status footer) read this
-        # instead of re-implementing the formatting.
+        # instead of re-implementing the formatting. Hosts that
+        # want to be *pushed* each new line instead of polling
+        # set {#on_status_line}.
         #
         # Thread safety: a single instance-variable read of a
         # +String+ — safe to read from any thread; readers may
@@ -112,6 +123,34 @@ module Pikuri
         # @return [String]
         attr_reader :status_line
 
+        # Optional status-line observer, +nil+ by default. When
+        # set to a callable, it is invoked with the owning
+        # agent's {#id} and the freshly formatted {#status_line}
+        # after every {Event::Tokens} — the push counterpart to
+        # polling {#status_line}, for hosts that stream the line
+        # onward (a Sinatra SSE endpoint pushing it to the
+        # browser, a websocket, a TUI redraw trigger). Fires on
+        # whatever thread runs the owning agent's loop, so the
+        # callable must hand off to its sink thread-safely; and
+        # like any listener it sits on the loop's path — an
+        # exception it raises propagates into the conversation,
+        # so handle dead connections inside the callable.
+        #
+        # Instances derived via {#for_sub_agent} copy the
+        # observer set at derivation time, so one callable
+        # receives parent and sub-agent lines alike; the +id+
+        # parameter (+""+ for the main agent, the generated id
+        # for a sub-agent) is what lets the UI route each line to
+        # the right status row — the line itself is unprefixed
+        # (see {#status_line}). An observer assigned *after*
+        # a sub-agent spawned doesn't reach that sub-agent's
+        # instance.
+        #
+        # @return [Proc, nil] called with +(id, status_line)+ —
+        #   the owning agent's id +String+ and the unprefixed
+        #   {#status_line} +String+
+        attr_accessor :on_status_line
+
         # @param id [String] owning agent's id, prepended to each
         #   log line as +[<id>] + when non-empty. Defaults to +""+
         #   for the main agent.
@@ -122,6 +161,7 @@ module Pikuri
           @context_window_size = 0
           @context_window_cap = nil
           @status_line = ''
+          @on_status_line = nil
         end
 
         # Sub-agent variant: a fresh +TokenLog+ with a zeroed
@@ -132,12 +172,17 @@ module Pikuri
         # prefix; defaults to +""+ when absent. The cap is left
         # +nil+ here; the sub-agent's {Agent#initialize} emits a
         # fresh {Event::ContextCap} immediately after construction
-        # and this listener picks it up off the stream.
+        # and this listener picks it up off the stream. The
+        # {#on_status_line} observer carries over by reference, so
+        # a host streaming the parent's lines sees the sub-agent's
+        # too — distinguished by the +id+ the callable receives.
         #
         # @param id [String] sub-agent's id
         # @return [TokenLog]
         def for_sub_agent(id: '', **)
-          self.class.new(id: id)
+          derived = self.class.new(id: id)
+          derived.on_status_line = @on_status_line
+          derived
         end
 
         # @param event [Agent::Event]
@@ -162,8 +207,9 @@ module Pikuri
 
         private
 
-        # Update the snapshot and write one +INFO+ line to the
-        # subsystem logger.
+        # Update the snapshot, write one +INFO+ line to the
+        # subsystem logger, and push the line to the status-line
+        # observer (when one was given at construction).
         #
         # @param tokens [Event::Tokens]
         # @return [void]
@@ -178,13 +224,14 @@ module Pikuri
           delta = @context_window_size - prev_ctx
 
           @status_line = format_line(input_now, tokens.output.to_i, delta)
-          LOGGER.info(@status_line)
+          prefix = @id.empty? ? '' : "[#{@id}] "
+          LOGGER.info("#{prefix}#{@status_line}")
+          @on_status_line&.call(@id, @status_line)
         end
 
         def format_line(input, output, delta)
           sign = delta.negative? ? '-' : '+'
-          prefix = @id.empty? ? '' : "[#{@id}] "
-          "#{prefix}msg ##{@msg}: ctx=#{format_ctx}  Δ#{sign}#{format_k(delta.abs)}  ↑#{format_k(input)}  ↓#{format_k(output)}"
+          "msg ##{@msg}: ctx=#{format_ctx}  Δ#{sign}#{format_k(delta.abs)}  ↑#{format_k(input)}  ↓#{format_k(output)}"
         end
 
         # +<used>+ when no cap is set, +<used>/<cap>+ when one is.

data/lib/pikuri/agent/listener.rb

@@ -11,10 +11,12 @@ module Pikuri
     # == What lives here, what doesn't
     #
     # The directory holds *pure consumers*: code whose only side
-    # effect is to react to events the +Agent+ has already emitted.
-    # No listener writes back into the stream — the +Agent+ is the
-    # only emitter — and no listener reaches into ruby_llm's chat
-    # callbacks. Both responsibilities live in {Agent}.
+    # effect is to react to events already emitted. No listener
+    # writes back into the stream — emission belongs to the +Agent+
+    # (loop narration) and to extensions via
+    # {Agent::ExtensionContext#emit_event} (domain events) — and no
+    # listener reaches into ruby_llm's chat callbacks (that wiring
+    # lives in {Agent}).
     #
     # Host-facing signal holders — step budget, cancellation flag,
     # mid-loop user input queue — are *controls*, not listeners.
@@ -45,7 +47,12 @@ module Pikuri
         #   Event::ThinkingDelta, Event::Assistant,
         #   Event::AssistantDelta, Event::ToolCall,
         #   Event::ToolResult, Event::Tokens, Event::ContextCap,
-        #   Event::FallbackNotice, Event::Cancelled]
+        #   Event::FallbackNotice, Event::Cancelled, Object] one of
+        #   the core loop-narration variants, or a gem-defined
+        #   domain event emitted via
+        #   {Agent::ExtensionContext#emit_event} (e.g.
+        #   +Pikuri::Tasks::ListChanged+) — match the variants you
+        #   know, let everything else fall through
         # @return [void]
         def on_event(event); end
       end

data/lib/pikuri/agent/listener_list.rb

@@ -24,10 +24,14 @@ module Pikuri
       end
 
       # Dispatch one event to every listener, in registration order.
-      # Called exclusively by {Agent} — listeners themselves never
-      # call this; the stream is one-way.
+      # Exactly two callers: {Agent} (loop-narration {Event}
+      # variants) and {ExtensionContext#emit_event} (extension
+      # domain events). Listeners themselves never call this; the
+      # stream is one-way.
       #
-      # @param event [Agent::Event]
+      # @param event [Object] an {Agent::Event} variant or a
+      #   gem-defined domain event (an immutable value, by
+      #   convention a +Data+ instance)
       # @return [void]
       def emit(event)
         @listeners.each { |l| l.on_event(event) }
@@ -78,20 +82,6 @@ module Pikuri
         self.class.new(swapped)
       end
 
-      # Return a new {ListenerList} containing this list's listeners
-      # plus the given extras, in order. Used by {Synthesizer} and
-      # other internal consumers to derive a list from an existing
-      # one. Returns +self+ when +extras+ is empty so the common
-      # no-op case allocates nothing.
-      #
-      # @param extras [Array<Listener::Base>] listeners to append
-      # @return [ListenerList]
-      def with(*extras)
-        return self if extras.empty?
-
-        self.class.new(@listeners + extras)
-      end
-
       # @example
       #   list.to_s # => "[Terminal, TokenLog(ctx=0.0k)]"
       #

data/lib/pikuri/agent/synthesizer.rb

@@ -2,13 +2,13 @@
 
 module Pikuri
   class Agent
-    # Step-exhaustion rescue. When an +Agent+'s
-    # {Control::StepLimit} trips, +Agent#run_loop+ catches the
-    # +Exceeded+ exception and hands off to {Synthesizer.run} so
-    # the run still produces something useful — a tools-free
-    # assistant turn that answers the user's question from
-    # whatever evidence the failed agent collected before running
-    # out of budget.
+    # Prompt builder for the step-exhaustion rescue. When an
+    # +Agent+'s {Control::StepLimit} trips with the +:synthesize+
+    # policy, +Agent#run_loop+ runs this module's prompt on a
+    # nested tools-free agent so the run still produces something
+    # useful — an assistant turn that answers the user's question
+    # from whatever evidence the failed agent collected before
+    # running out of budget.
     #
     # == Why this exists
     #
@@ -22,16 +22,24 @@ module Pikuri
     # answer is largely in the messages — it just needs a
     # tools-free pass to synthesize.
     #
+    # Salvage is the wrong move for some agents, which is why the
+    # policy lives on {Control::StepLimit} and defaults to
+    # +:raise+ — a coding agent's half-finished work can't be
+    # completed by a tools-free pass, only described. See
+    # {Control::StepLimit}'s class header.
+    #
     # == Seam discipline
     #
-    # {Synthesizer.run} does not reference +RubyLLM::*+. +Agent+
-    # constructs the synth chat itself (the one +RubyLLM.chat+
-    # call lives in +lib/agent.rb+, same as the parent chat) and
-    # passes it in. +Synthesizer+ only calls instance methods on
-    # whatever +chat+ it receives — +#with_instructions+,
-    # +#ask+, +#messages+ — and uses {Agent.wire_chat} for the
-    # event-stream wiring so the synth chat emits events with
-    # the same shape as the main chat.
+    # This module is pure prompt construction — no chat handling,
+    # no +RubyLLM.chat+ call, no event wiring. The execution side
+    # (constructing the nested agent, sharing the parent's
+    # listener stream and cancellable, capturing the answer) is
+    # +Agent#run_synthesizer+'s job: the synth is a regular
+    # tools-free +Agent+, the same construction shape the +agent+
+    # tool from +pikuri-subagents+ uses for sub-agents. The only
+    # +RubyLLM::*+ surface read here is the value-type
+    # +RubyLLM::Message+ / +ToolCall+ passthrough (per the
+    # value-type rule in CLAUDE.md).
     module Synthesizer
       # The synthesizer's system prompt. Strict and short: use
       # the evidence, don't apologize, admit gaps when present.
@@ -39,58 +47,6 @@ module Pikuri
         You are given evidence another agent collected before running out of steps. Answer the user's question using only this evidence. You have no tools. If the evidence is insufficient, state plainly what's missing and what partial answer you can give. Do not apologize or comment on the previous agent.
       PROMPT
 
-      # Configure +chat+ for synthesis, run one turn against it,
-      # and return the final assistant content. The chat is wired
-      # for the event stream via {Agent.wire_chat} so the synth's
-      # reasoning and answer flow through the same listener
-      # surface the parent agent uses — terminal renders them
-      # inline (padded under sub-agent), an in-memory recorder
-      # picks them up, a TokenLog tags them with the synth id.
-      #
-      # @param chat [RubyLLM::Chat] a *fresh* chat with no tools.
-      #   The caller is responsible for constructing it with the
-      #   same model/provider configuration the parent used.
-      # @param parent_messages [Array<RubyLLM::Message>] the
-      #   parent chat's full message history at the moment of
-      #   step exhaustion. Used to build the evidence transcript.
-      # @param user_message [String] the user's original question
-      #   from the parent turn that exhausted.
-      # @param listeners [Agent::ListenerList] listeners to wire
-      #   the synth chat into. Typically the parent agent's list
-      #   run through {ListenerList#for_sub_agent} with the
-      #   synth's +id:+ so any +TokenLog+ tags its lines with
-      #   the synth bracket and any +Terminal+ pads its output.
-      # @param step_limit [Control::StepLimit, nil] defensive
-      #   step budget. The synth has no tools so it should never
-      #   trip +before_tool_call+, but a buggy provider that
-      #   somehow returned a tool call would loop without one.
-      #   Pass +nil+ to skip.
-      # @param cancellable [Control::Cancellable, nil]
-      #   cancellation control. Typically the parent's instance,
-      #   shared by reference so a user cancel during synthesis
-      #   still works. Pass +nil+ to skip.
-      # @param streaming [Boolean] mirror the parent agent's
-      #   +streaming+ flag. When +true+, {Agent.streaming_block}
-      #   is passed to +chat.ask+ so the synth's reasoning and
-      #   answer flow through the listener stream as deltas in
-      #   addition to the final {Event::Thinking} / {Event::Assistant}
-      #   bookends.
-      # @return [String, nil] the synth's final assistant
-      #   content, or +nil+ if the synth somehow produced no
-      #   assistant message
-      def self.run(chat:, parent_messages:, user_message:, listeners:,
-                   step_limit: nil, cancellable: nil, streaming: false)
-        chat.with_instructions(SYSTEM_PROMPT)
-        Agent.wire_chat(chat, listeners: listeners, step_limit: step_limit, cancellable: cancellable)
-        prompt = build_prompt(parent_messages: parent_messages, user_message: user_message)
-        if streaming
-          chat.ask(prompt, &Agent.streaming_block(listeners: listeners, cancellable: cancellable))
-        else
-          chat.ask(prompt)
-        end
-        chat.messages.reverse.find { |m| m.role == :assistant }&.content
-      end
-
       # Render the user's question plus an "Evidence gathered"
       # section built from +parent_messages+ as a single prompt
       # string. Pure function — no I/O, safe to test directly
@@ -140,6 +96,76 @@ module Pikuri
         lines.join("\n").rstrip
       end
       private_class_method :format_evidence
+
+      # The +:synthesize+ arm of the step-exhaustion policy (see the
+      # class header). Runs the {Synthesizer} prompt over the
+      # exhausted chat's history on a nested tools-free +Agent+ —
+      # the same construction shape the +agent+ tool from
+      # +pikuri-subagents+ uses for sub-agents, so the synth gets
+      # listener propagation, transport / context-window-cap /
+      # streaming inheritance, and teardown via +close+ for free.
+      # The synth's answer is returned.
+      #
+      # @param ctx [ExtensionContext]
+      # @param chat_messages [Array<RubyLLM::Message>] the
+      #   exhausted chat's full message history, the evidence
+      #   {.build_prompt} renders
+      # @param user_message [String] the user's original question
+      #   from the turn that exhausted
+      # @raise [Control::Cancellable::Cancelled] when a cancel
+      #   landed between the budget tripping and this rescue —
+      #   cancellation wins over salvage
+      # @return [String] the synth answer
+      def self.run_synthesizer(ctx, chat_messages, user_message)
+        # Check the cancel flag *before* constructing the synth: the
+        # nested run_loop resets the shared cancellable at its turn
+        # boundary, which would erase a cancel requested in this
+        # window. The raise propagates without a parent-side
+        # {Event::Cancelled} — a cancel *during* synthesis emits it
+        # from the synth's own rescue (on the derived listener list)
+        # instead, so either way the stream sees at most one.
+        ctx.agent.cancellable&.check!
+
+        ctx.emit_event(Event::FallbackNotice.new(
+                         reason: "agent exhausted #{ctx.agent.step_limit.max} steps; " \
+                                                 'synthesizing answer from gathered evidence'
+                       ))
+
+        # Synth runs under this agent's identity but with a
+        # different system prompt, so it gets a distinct
+        # +_synthesizer+ suffix on the id — same +_+ separator the
+        # sub-agent generator uses, so main becomes +"synthesizer"+
+        # and a sub-agent +"researcher 0"+ becomes
+        # +"researcher 0_synthesizer"+. Any +TokenLog+ in the list
+        # tags the synth's prompt under that bracket so it's
+        # obvious from the log which turns were the rescue rather
+        # than the original loop.
+        synth_id = ctx.agent.id.empty? ? 'synthesizer' : "#{ctx.agent.id}_synthesizer"
+        synth = Agent.new(
+          # Carry the parent's resolved cap on the transport so the synth
+          # reuses it without a re-probe — the cap rides {ChatTransport}
+          # now, not an +Agent.new(context_window:)+ kwarg.
+          transport: ctx.agent.transport.with(context_window: ctx.agent.context_window_cap),
+          system_prompt: Synthesizer::SYSTEM_PROMPT,
+          # Defensive budget with the default :raise policy: the
+          # synth has no tools so it should never tick, but a buggy
+          # provider that somehow returns a tool call must not loop
+          # forever — and a synth that needs its own synth is a bug,
+          # not a rescue.
+          step_limit: Control::StepLimit.new(max: 1),
+          cancellable: ctx.agent.cancellable,
+          id: synth_id,
+          streaming: ctx.agent.streaming
+        ) { |c| c.add_listeners(ctx.sub_agent_listeners(id: synth_id)) }
+        begin
+          synth.run_loop(user_message: Synthesizer.build_prompt(
+            parent_messages: chat_messages, user_message: user_message
+          ))
+          synth.last_assistant_content
+        ensure
+          synth.close
+        end
+      end
     end
   end
 end