pikuri-core 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9d64fe3a6b311841de49b193f6caa92cdb2ba0e627ef0195c73824d803fcafa
-  data.tar.gz: fa1112813faf7c4d6d162d467b4977c7b800bc647d35c0fe6fec79a1f30e6112
+  metadata.gz: 914f6e02052e97773e630e32bc9689bf7edc0eee4e962419aa41a15ca4afa667
+  data.tar.gz: e9a68c3813a0bbcd292757ee2cb4dbce6df7abc890e0d4afa6cf51cae77a6247
 SHA512:
-  metadata.gz: f9b5618853d0501a417fbcfd021e1dd65fe45fef42331d9f8b4f1c8ab273a91437f433b7065512b46340d98670e53127cb49a5149eb7078750bd99a0e6ad22fa
-  data.tar.gz: a9ce6040b23bcd4a2eb4f11bc10c50cd64ad8fdba685e2eba51f9181a3f3503617adb230b0601257e3f0ec3122c14d1a12b5091ab03b7612f906d72c54938189
+  metadata.gz: 3f0bdf7af9a4a85d3669b01f0929b92fdb2acbc9c7cb083611c4acaecc4d3b5b37a3e3d97a1fd060bec143016f4db00968707d149f127eb1dea5a7243dd51a73
+  data.tar.gz: cf92ad370fed6574f9cd7cc44fbd93e36c6bb03c6d56555267dc0a22a723ca9ce298231495b902570bfbbdde6b5e6b319860b2b625818eb2bdbb51d5dd2346e2

data/README.md

@@ -65,3 +65,13 @@ agent.run_loop(user_message: 'What is 17 * 23?')
 
 See `bin/pikuri-chat` for a worked example with REPL, signal
 handling, and cancellation.
+
+## Further reading
+
+- **Narrative walkthrough:** [chapter 1 of the pikuri guide](../docs/guide/01-chat.md)
+  — install llama.cpp, start the server, run `pikuri-chat`, the
+  agentic loop, the four bundled tools, and search-provider
+  privacy postures.
+- **API reference:** browse the YARD docs at
+  <https://rubydoc.info/gems/pikuri-core> (once published), or run
+  `bundle exec yard` in this directory for a local copy.

data/lib/pikuri/agent/chat_transport.rb

@@ -8,11 +8,12 @@ module Pikuri
     #
     # Bundling them is structural protection against a recurring bug
     # class — every forwarding site (the synthesizer rescue in
-    # {Agent#run_loop}, {Tool::SubAgent} spawning a sub-agent) used to
-    # pass the three individually, and dropping one routed the spawned
-    # chat to a different server or raised +RubyLLM::ModelNotFoundError+
-    # on the unknown model id. With a single value object the call site
-    # can't silently miss a field.
+    # {Agent#run_loop}, the +agent+ tool from +pikuri-subagents+
+    # spawning a sub-agent) used to pass the three individually, and
+    # dropping one routed the spawned chat to a different server or
+    # raised +RubyLLM::ModelNotFoundError+ on the unknown model id.
+    # With a single value object the call site can't silently miss a
+    # field.
     #
     # Pure data carrier: no +RubyLLM+ references here, so the seam stays
     # in {Agent}, +bin/pikuri-chat+, and {Tool}.

data/lib/pikuri/agent/configurator.rb

@@ -5,8 +5,9 @@ module Pikuri
     # Build-time collector yielded into the +Pikuri::Agent.new+ block.
     # Hosts and {Extension} implementations call its methods to declare
     # additional tools, listeners, system-prompt snippets, +on_close+
-    # handlers, and extension instances; {Agent#initialize} drains the
-    # collected state into the agent's final wiring before returning.
+    # handlers, extension instances, and persona-flavored sub-agents;
+    # {Agent#initialize} drains the collected state into the agent's
+    # final wiring before returning.
     #
     # == Why this exists
     #
@@ -15,10 +16,27 @@ module Pikuri
     #
     #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
     #     c.add_listener Pikuri::Agent::Listener::Terminal.new
-    #     c.add_tool     Pikuri::Tool::CALCULATOR
+    #     c.add_tool     Pikuri::Tool::WEB_SEARCH
+    #     c.add_tool     Pikuri::Tool::WEB_SCRAPE
+    #     c.add_tool     Pikuri::Tool::FETCH
     #     c.add_extension Pikuri::Skill::Extension.new(catalog: catalog)
     #   end
     #
+    # == Two tool pools: regular vs. sub-agent-only
+    #
+    # {#add_tool} registers a tool the parent agent can call: it lands
+    # in {#tools} and gets handed to ruby_llm via +chat.with_tool+.
+    # {#add_sub_agent_tool} registers a tool the parent *cannot* call
+    # — it lands in {#sub_agent_tools} and is never sent to ruby_llm
+    # for the parent, but is visible to {Pikuri::SubAgent::Extension}'s
+    # persona-tool-name resolution. The use case is the lethal-trifecta
+    # defense in {Pikuri::Code::Bash::Sandbox} terms: keep network tools
+    # (+web_search+ / +web_scrape+ / +fetch+) off the parent so a prompt-
+    # injected file read cannot egress through the parent's own tools,
+    # while still letting the +researcher+ persona reach them via the
+    # +agent+ delegation tool. See SECURITY.md §"Defense: capability
+    # boundaries via sub-agents".
+    #
     # Extensions implement their +configure(c)+ hook against the same
     # type, so the call sites for "block users add stuff" and
     # "extensions add stuff" share one API.
@@ -44,9 +62,9 @@ module Pikuri
       #   available for diagnostics.
       attr_reader :system_prompt_base
 
-      # @return [String] this agent's identifier; empty for the main
-      #   agent, hierarchical (+"sub_agent 0_1"+) for sub-agents.
-      attr_reader :name
+      # @return [String] this agent's unique identifier; empty for the
+      #   main agent, persona-rooted (e.g. +"researcher 0"+) for sub-agents.
+      attr_reader :id
 
       # @return [Boolean] +true+ when the agent opted into chunk-level
       #   streaming.
@@ -68,9 +86,18 @@ module Pikuri
       attr_reader :interloper
 
       # @return [Array<Tool>] tools added via {#add_tool}, in
-      #   declaration order. Drained by {Agent#initialize}.
+      #   declaration order. Drained by {Agent#initialize} and
+      #   registered with ruby_llm so the parent LLM can call them.
       attr_reader :tools
 
+      # @return [Array<Tool>] tools added via {#add_sub_agent_tool},
+      #   in declaration order. Drained by {Agent#initialize} but
+      #   *not* registered with ruby_llm — invisible to the parent
+      #   LLM, available only to sub-agents through
+      #   {Pikuri::SubAgent::Extension}'s persona-tool-name
+      #   resolution. See the class header.
+      attr_reader :sub_agent_tools
+
       # @return [Array<Listener::Base>] listeners added via
       #   {#add_listener}, in declaration order. Drained by
       #   {Agent#initialize}.
@@ -93,41 +120,35 @@ module Pikuri
       #   wiring is complete.
       attr_reader :extensions
 
-      # @return [SubAgentRequest, nil] set when the block called
-      #   {#allow_sub_agent}; +nil+ otherwise. The Agent ctor uses
-      #   this to decide whether to create a {Tool::SubAgent}
-      #   instance after the chat is wired (so the SubAgent tool's
-      #   parent.tools snapshot doesn't include itself —
-      #   recursion guard).
-      attr_reader :sub_agent_request
-
-      # Record holding the +max_steps+ value the host passed to
-      # {#allow_sub_agent}. The Agent ctor consumes one of these
-      # records to build a {Tool::SubAgent} keyed to that step
-      # budget.
-      SubAgentRequest = Data.define(:max_steps)
-
       # @param transport [Agent::ChatTransport]
       # @param system_prompt_base [String]
-      # @param name [String]
+      # @param id [String]
       # @param streaming [Boolean]
       # @param step_limit [Control::StepLimit, nil]
       # @param cancellable [Control::Cancellable, nil]
       # @param interloper [Control::Interloper, nil]
-      def initialize(transport:, system_prompt_base:, name:, streaming:,
-                     step_limit:, cancellable:, interloper:)
+      # @param on_close_sink [Array<Proc>, nil] array that {#on_close}
+      #   appends to. {Agent#initialize} passes its own live
+      #   +@on_close_handlers+ so a handler an extension arms via
+      #   +c.on_close+ is reachable the instant it's registered — which
+      #   is what lets the constructor close a half-built agent if a
+      #   later extension's +configure+ raises. Defaults to a fresh
+      #   array for standalone use (e.g. specs).
+      def initialize(transport:, system_prompt_base:, id:, streaming:,
+                     step_limit:, cancellable:, interloper:, on_close_sink: nil)
         @transport = transport
         @system_prompt_base = system_prompt_base
-        @name = name
+        @id = id
         @streaming = streaming
         @step_limit = step_limit
         @cancellable = cancellable
         @interloper = interloper
 
         @tools = []
+        @sub_agent_tools = []
         @listeners = []
         @system_prompt_additions = []
-        @on_close_handlers = []
+        @on_close_handlers = on_close_sink || []
         @extensions = []
       end
 
@@ -142,8 +163,6 @@ module Pikuri
 
       # Append several tools at once. Equivalent to calling {#add_tool}
       # for each element of +tools+; declaration order is preserved.
-      # Sole intended caller today is {Tool::SubAgent}, which seeds a
-      # sub-agent's Configurator from the parent's tool snapshot.
       #
       # @param tools [Enumerable<Tool>]
       # @return [void]
@@ -152,6 +171,18 @@ module Pikuri
         nil
       end
 
+      # Append a tool to the sub-agent-only pool. The parent LLM
+      # never sees it; only sub-agents whose persona +tool_names+
+      # include the tool's +name+ get it in their toolset. See the
+      # class header for the trifecta-defense rationale.
+      #
+      # @param tool [Tool]
+      # @return [void]
+      def add_sub_agent_tool(tool)
+        @sub_agent_tools << tool
+        nil
+      end
+
       # Append a listener to the agent's listener list.
       #
       # @param listener [Listener::Base]
@@ -163,9 +194,6 @@ module Pikuri
 
       # Append several listeners at once. Accepts any enumerable
       # (Array, {ListenerList}, …); declaration order is preserved.
-      # Sole intended caller today is {Tool::SubAgent}, which seeds a
-      # sub-agent's Configurator from the parent's listener list (run
-      # through {ListenerList#for_sub_agent}).
       #
       # @param listeners [Enumerable<Listener::Base>]
       # @return [void]
@@ -207,26 +235,6 @@ module Pikuri
         nil
       end
 
-      # Retain a list of already-configured extensions for the
-      # bind sweep without re-running +configure+. Sole intended
-      # caller is {Tool::SubAgent}, which seeds a sub-agent's
-      # Configurator from the parent's extension list — the parent
-      # already drove +configure+ and its system-prompt snippets /
-      # static tools are inherited by the sub-agent verbatim
-      # through {#add_tools} + {#add_listeners} + the augmented
-      # +system_prompt+; re-running +configure+ on the sub-agent
-      # would double up those contributions. The +bind(sub_agent)+
-      # sweep in {Agent#initialize} still fires on each inherited
-      # extension so per-agent state (MCP's per-agent connect tool,
-      # for example) gets installed fresh on the sub-agent.
-      #
-      # @param extensions [Enumerable<Extension>]
-      # @return [void]
-      def inherit_extensions(extensions)
-        extensions.each { |ext| @extensions << ext }
-        nil
-      end
-
       # Register a handler called by {Agent#close}. Handlers fire in
       # LIFO order, each inside its own +rescue+ — same semantics as
       # +ensure+-block cleanup discipline.
@@ -239,32 +247,6 @@ module Pikuri
         @on_close_handlers << blk
         nil
       end
-
-      # Enable the +sub_agent+ tool on this agent. Records the
-      # +max_steps+ budget for sub-agent runs; the Agent ctor reads
-      # {#sub_agent_request} after the block returns and constructs
-      # the actual {Tool::SubAgent} so its snapshot of the parent's
-      # tool list doesn't include itself (recursion guard).
-      #
-      # Sub-agents inherit the parent's tool list (minus +sub_agent+
-      # itself), augmented system prompt, listeners (via
-      # +for_sub_agent+ per listener), controls (per the per-control
-      # rule), and the parent's extension list. Each inherited
-      # extension's +bind(sub_agent)+ fires during the sub-agent's
-      # construction — that's how MCP's per-agent connect tool ends
-      # up keyed to the sub-agent rather than the parent.
-      #
-      # @param max_steps [Integer] step budget for each sub-agent
-      #   run, passed to {Tool::SubAgent#initialize}.
-      # @raise [RuntimeError] if called more than once on the same
-      #   Configurator.
-      # @return [void]
-      def allow_sub_agent(max_steps: 10)
-        raise 'allow_sub_agent may only be called once per agent' if @sub_agent_request
-
-        @sub_agent_request = SubAgentRequest.new(max_steps: max_steps)
-        nil
-      end
     end
   end
 end

data/lib/pikuri/agent/context_window_detector.rb

@@ -2,6 +2,7 @@
 
 require 'faraday'
 require 'json'
+require 'cgi'
 
 module Pikuri
   class Agent
@@ -31,6 +32,20 @@ module Pikuri
     #    (typically +bin/pikuri-chat+) derives the right URL from its configured
     #    base.
     #
+    # == llama.cpp router mode
+    #
+    # A llama.cpp *router* (the multi-instance front that proxies to N
+    # on-demand model servers) answers a bare +/props+ with
+    # +{"role":"router", ..., "n_ctx":0}+ — there is no single loaded
+    # model at the router itself, so its top-level +n_ctx+ is +0+. The
+    # real per-model cap is one proxied hop away: +GET /props?model=<id>+
+    # routes the probe to that model's instance, whose +/props+ carries
+    # the launched +n_ctx+. So when the bare probe reports +role: router+
+    # and a +model_id+ is known, this re-probes with the model id before
+    # giving up. A plain single-model server is untouched: its bare
+    # +/props+ already carries a positive +n_ctx+, so the router branch
+    # never runs.
+    #
     # == Failure handling
     #
     # The probe is best-effort. HTTP error, timeout, non-JSON body, or a
@@ -64,10 +79,15 @@ module Pikuri
       #   +RubyLLM::Chat#model.context_window+
       # @param llama_probe_url [String, nil] full URL to llama.cpp +/props+;
       #   +nil+ or empty string skips the probe
-      def initialize(override:, ruby_llm_reported:, llama_probe_url:)
+      # @param model_id [String, nil] the chat model id, used only to
+      #   follow a llama.cpp router via +/props?model=<id>+ when the bare
+      #   probe reports +role: router+. +nil+ or empty disables that
+      #   second hop.
+      def initialize(override:, ruby_llm_reported:, llama_probe_url:, model_id: nil)
         @override = override
         @ruby_llm_reported = ruby_llm_reported
         @llama_probe_url = llama_probe_url
+        @model_id = model_id
       end
 
       # @return [Integer, nil] resolved cap, or +nil+ if no source produced
@@ -83,25 +103,65 @@ module Pikuri
       private
 
       def probe_llama_cpp
-        response = Faraday.new(
-          request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
-        ).get(@llama_probe_url) do |req|
-          req.headers['Accept'] = 'application/json'
-        end
+        data = fetch_props(@llama_probe_url)
+        return nil if data.nil?
 
-        return warn_and_nil("HTTP #{response.status} from #{@llama_probe_url}") unless response.status == 200
+        n_ctx = positive_n_ctx(data)
+        return n_ctx if n_ctx
 
-        data = JSON.parse(response.body)
-        n_ctx = data.dig('default_generation_settings', 'n_ctx')
-        return n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
+        # llama.cpp router: the bare /props carries no model, so its
+        # n_ctx is 0. Follow the router to the model's own instance.
+        return probe_router_model if data['role'] == 'router' && model_id_present?
 
         warn_and_nil(
           "no positive integer at default_generation_settings.n_ctx in #{@llama_probe_url} response"
         )
+      end
+
+      def probe_router_model
+        url = "#{@llama_probe_url}?model=#{CGI.escape(@model_id)}"
+        data = fetch_props(url)
+        return nil if data.nil?
+
+        n_ctx = positive_n_ctx(data)
+        return n_ctx if n_ctx
+
+        warn_and_nil(
+          "no positive integer at default_generation_settings.n_ctx in router probe #{url}"
+        )
+      end
+
+      # GETs +url+ and parses its JSON body.
+      #
+      # @param url [String] a llama.cpp +/props+ URL
+      # @return [Hash, nil] the parsed body, or +nil+ (after one +warn+
+      #   line) on non-200, timeout, transport error, or non-JSON body
+      def fetch_props(url)
+        response = Faraday.new(
+          request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
+        ).get(url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+
+        return warn_and_nil("HTTP #{response.status} from #{url}") unless response.status == 200
+
+        JSON.parse(response.body)
       rescue Faraday::Error, JSON::ParserError => e
         warn_and_nil("#{e.class.name.split('::').last}: #{e.message}")
       end
 
+      # @param data [Hash] a parsed +/props+ body
+      # @return [Integer, nil] the launched +n_ctx+ when present and
+      #   positive, else +nil+
+      def positive_n_ctx(data)
+        n_ctx = data.dig('default_generation_settings', 'n_ctx')
+        n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
+      end
+
+      def model_id_present?
+        !@model_id.nil? && !@model_id.empty?
+      end
+
       def warn_and_nil(reason)
         LOGGER.warn("llama.cpp /props probe failed: #{reason}")
         nil

data/lib/pikuri/agent/control/cancellable.rb

@@ -40,13 +40,13 @@ module Pikuri
       #
       # == Sub-agent semantics
       #
-      # {#for_sub_agent} returns +self+ — the same instance is
-      # shared by reference across the parent, every sub-agent,
-      # and the synthesizer rescue. One {#cancel!} call stops the
-      # whole tree. This contrasts with {StepLimit}, which gives
-      # each agent its own counter (because step budgets are
-      # per-agent concerns) — cancellation is a global signal
-      # from the user, so it must propagate down.
+      # Cancellation is a global "stop the whole tree" signal —
+      # the +agent+ tool from +pikuri-subagents+ shares the
+      # parent's +Cancellable+ by reference when spawning a child,
+      # so one {#cancel!} call stops the parent, every running
+      # sub-agent, and the synthesizer rescue. The sharing rule
+      # lives at the spawn site (sub-agent code), not on this
+      # class.
       class Cancellable
         # Raised by {#check!} once {#cancel!} has been called.
         # Carries no fields; the cancellation reason ("the user
@@ -105,16 +105,6 @@ module Pikuri
           @cancelled = false
         end
 
-        # Sub-agent variant: the same instance, shared by
-        # reference, so a single {#cancel!} stops the parent,
-        # every running sub-agent, and the synthesizer rescue.
-        # See the class header for the rationale.
-        #
-        # @return [Cancellable] the receiver
-        def for_sub_agent(**)
-          self
-        end
-
         # @return [String] short label for {Agent#to_s}; reflects
         #   the current flag state so a startup banner or debug
         #   print can tell an armed token apart from one that has

data/lib/pikuri/agent/control/interloper.rb

@@ -70,16 +70,16 @@ module Pikuri
       #
       # == Sub-agent semantics
       #
-      # {#for_sub_agent} returns +nil+. Sub-agents are private to
-      # the parent agent; the host has no handle to them, so a
-      # child +Interloper+ would be unreachable. The sub-agent's
-      # {Agent#initialize} simply receives +interloper: nil+ from
-      # {Tool::SubAgent}, which is its default. The behavior
-      # contrasts with {Control::Cancellable}, which shares its
-      # instance by reference so the parent's signal propagates
-      # to children — cancellation is a global "stop the whole
-      # tree" event, whereas injection is a directed "talk to the
-      # main agent" event.
+      # Sub-agents are private to the parent agent; the host has
+      # no handle to them, so a child +Interloper+ would be
+      # unreachable. The +agent+ tool from +pikuri-subagents+
+      # therefore omits the kwarg when spawning a child, leaving
+      # the sub-agent's +interloper+ at its default +nil+. The
+      # behavior contrasts with {Control::Cancellable}, which is
+      # shared by reference so the parent's signal propagates to
+      # children — cancellation is a global "stop the whole tree"
+      # event, whereas injection is a directed "talk to the main
+      # agent" event.
       class Interloper
         def initialize
           @mutex = Mutex.new
@@ -123,6 +123,14 @@ module Pikuri
           @mutex.synchronize { !@items.empty? }
         end
 
+        # @return [Integer] number of pending injections; like
+        #   {#pending?} and {#peek}, a snapshot observable from
+        #   any thread — by the time the caller reads it the
+        #   queue may already have drained
+        def size
+          @mutex.synchronize { @items.size }
+        end
+
         # Atomically take and remove all pending items. Called by
         # {Agent}'s +after_tool_result+ wiring; the +Agent+ then
         # appends each item to the chat history and emits an
@@ -143,23 +151,12 @@ module Pikuri
           end
         end
 
-        # Sub-agent variant: +nil+, signalling to {Agent} (and
-        # transitively to {Tool::SubAgent}) that no +Interloper+
-        # should be wired on a spawned sub-agent. See the class
-        # header for the "host has no handle to sub-agents"
-        # rationale.
-        #
-        # @return [nil]
-        def for_sub_agent(**)
-          nil
-        end
-
         # @return [String] short label for {Agent#to_s}; reflects
         #   the pending-count so a debug print or banner can tell
         #   an idle interloper apart from one with queued items
         def to_s
-          size = @mutex.synchronize { @items.size }
-          size.zero? ? 'Interloper' : "Interloper(#{size} pending)"
+          pending = size
+          pending.zero? ? 'Interloper' : "Interloper(#{pending} pending)"
         end
       end
     end

data/lib/pikuri/agent/control/step_limit.rb

@@ -69,20 +69,6 @@ module Pikuri
         #   can introspect it (and so tests can assert it)
         attr_reader :step
 
-        # Sub-agent variant: a fresh +StepLimit+ at the
-        # caller-supplied +max_steps:+, or — when the key is
-        # absent — at the receiver's own cap. The mutable counter
-        # is per-chat, so the parent's instance cannot govern a
-        # sub-agent's chat; every sub-agent needs its own.
-        #
-        # @param max_steps [Integer] positive step cap for the
-        #   sub-agent; defaults to the receiver's current cap
-        # @return [StepLimit]
-        # @raise [ArgumentError] if +max_steps+ is non-positive
-        def for_sub_agent(max_steps: @max)
-          self.class.new(max: max_steps)
-        end
-
         # @return [String] short config dump for {Agent#to_s}
         def to_s
           "StepLimit(max=#{@max})"

data/lib/pikuri/agent/event.rb

@@ -45,6 +45,21 @@ module Pikuri
         end
       end
 
+      # A system-role block an {Extension#on_user_message} hook
+      # injected into the chat log — recalled reference (memory
+      # context, retrieved snippets) tagged +role: :system+ so the
+      # model reads it as background, not new user input. Carries
+      # the injected text verbatim.
+      #
+      # Emitted by {Agent#dispatch_ext_on_user_message}, once per
+      # extension that returns a non-empty block, at the same site
+      # that grows the chat log — so the event stream stays a
+      # faithful mirror of what the model actually sees. Without it
+      # an injection is invisible: it never surfaces in the stream,
+      # only as a secondary echo in the assistant's later reasoning.
+      # {Listener::Terminal} renders it dim grey with a +⊕+ marker.
+      SystemInjected = Data.define(:content)
+
       # Assistant reasoning ("thinking") block, extracted from the
       # +thinking.text+ field on a +RubyLLM::Message+ with role
       # +:assistant+. Emitted by {Agent}'s +after_message+ wiring;

data/lib/pikuri/agent/extension.rb

@@ -5,17 +5,20 @@ module Pikuri
     # The Extension protocol — how hosts bolt extra capabilities
     # (system-prompt snippets, tools, lifecycle hooks) onto an
     # {Agent}. Extensions are added via {Configurator#add_extension}
-    # inside the +Agent.new+ block; the Agent then drives two hooks
-    # on each — {#configure} during the block, {#bind} once the
-    # agent is fully constructed.
+    # inside the +Agent.new+ block; the Agent then drives three hooks
+    # on each — {#configure} during the block, {#bind} once the agent
+    # is fully constructed, and {#on_user_message} on every user turn
+    # thereafter.
     #
     # Mix this module into an extension class to inherit empty
-    # default implementations of both hooks; override the ones you
-    # need. Extensions that don't +include+ this module still work
-    # if they define both methods themselves (the Agent and
-    # Configurator call them by name) — the module exists to make
-    # the protocol *explicit* and to give "I want to implement just
-    # +configure+" extensions a free no-op +bind+ (and vice versa).
+    # default implementations of all three hooks; override the ones
+    # you need. Extensions that don't +include+ this module still
+    # work *if they define all three methods themselves* — the Agent
+    # and Configurator call them by name with no +respond_to?+ guard,
+    # so a missing one raises. The module exists to make the protocol
+    # *explicit* and to give "I want to implement just +configure+"
+    # extensions free no-op +bind+ / +on_user_message+ defaults (and
+    # any other combination).
     #
     # == Example
     #
@@ -57,26 +60,49 @@ module Pikuri
 
       # Called by {Agent#initialize} after the block returns and the
       # chat is fully wired, with the live {Agent} as the argument.
-      # Runs once per agent — on the parent during its construction,
-      # and once more on each sub-agent during the sub-agent's
-      # construction (same extension instance, multiple +bind+ calls
-      # — per-agent state lives in +bind+'s closures, not in
-      # extension instance state). The default is a no-op; override
-      # when you need to install *per-agent* state. Things you
-      # typically do here:
+      # 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:
       #
-      # * register per-agent dynamic tools via
-      #   {Agent#internal_add_tool}
-      # * register per-agent +on_close+ handlers via
-      #   {Agent#on_close}
+      # * register dynamic tools via {Agent#internal_add_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 (e.g. when a tool
-      #   fires and wants to register more tools on its owning
-      #   chat)
+      #   to act on this specific agent later
       #
       # @param agent [Agent] the live agent, fully wired
       # @return [void]
       def bind(agent); end
+
+      # Optional per-turn hook fired by the {Agent} after a user-message
+      # is added to the chat. The
+      # default is a no-op returning +nil+; override and return {String}
+      # to emit a `:system` message with that text.
+      #
+      # == Append-only, never mutate
+      #
+      # The Agent only ever *appends* the returned block at the tail; it never
+      # rewrites or removes an earlier one. Mutating mid-log would bust the
+      # provider prefix cache for every message after the edit. Stale blocks
+      # ride the existing context-window machinery, not a per-turn rewrite.
+      #
+      # == Not inherited by sub-agents
+      #
+      # Like the rest of the extension surface, this fires on the parent agent
+      # 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 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
     end
   end
 end

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

@@ -9,7 +9,9 @@ module Pikuri
       # Terminal renderer for the normalized event stream: dim grey
       # reasoning, Markdown-rendered assistant content, cyan tool-
       # call and tool-result lines, yellow fallback notice, red
-      # cancelled notice. {Event::UserTurn} is intentionally silent
+      # cancelled 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
       # it adds nothing); {Event::Tokens} and {Event::ContextCap}
       # are silent too (their consumer is {TokenLog}).
@@ -123,6 +125,8 @@ module Pikuri
             stream_fragment(Rainbow(content).color(85, 85, 85)) if @streaming
           in Event::AssistantDelta(content:)
             stream_fragment(content) if @streaming
+          in Event::SystemInjected(content:)
+            println(indent(Rainbow("⊕ #{content}").color(85, 85, 85)))
           in Event::ToolCall(name:, arguments:)
             args = arguments.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
             println(indent(Rainbow("→ #{name}(#{args})").cyan))