pikuri-core 0.0.3

data/lib/pikuri/tool/search/engines.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Namespace for the web-search stack used by {Tool::WEB_SEARCH}: per-
+    # provider modules ({DuckDuckGo}, {Brave}, {Exa}), the {Result} value
+    # object they all return, the cross-provider {Engines} cascade with
+    # its on-disk cache, and the shared {RateLimiter} a provider can wire
+    # in to back off when a quota header says so.
+    module Search
+      # Search-orchestration entry point: the cascade across configured
+      # providers, the result cache, and the {Unavailable} protocol marker
+      # the cascade uses to fall back. The LLM-facing tool itself
+      # ({Tool::WEB_SEARCH}) lives in +lib/tool/web_search.rb+ and calls
+      # into {.search} below. Each {Tool::Search} provider module
+      # ({DuckDuckGo}, {Brave}, {Exa}) raises {Unavailable} when it wants
+      # the cascade to try the next one.
+      module Engines
+        # Subsystem logger; set its level with +PIKURI_LOG_ENGINES+
+        # (e.g. +PIKURI_LOG_ENGINES=debug+) or the global +PIKURI_LOG+.
+        #
+        # @return [Logger]
+        LOGGER = Pikuri.logger_for('Engines')
+
+        # Raised by a provider when it is temporarily unavailable (rate-limited,
+        # bot-blocked, quota-exhausted, or otherwise saying "try again later"
+        # rather than "your request is wrong"). The cascade in {Engines.search}
+        # catches this and tries the next provider; any other exception bubbles
+        # up unchanged so genuine bugs and config errors stay visible.
+        class Unavailable < StandardError; end
+
+        # All providers that are currently configured. {DuckDuckGo} is always
+        # available (no API key needed); {Brave} and {Exa} each join the
+        # list when their API token is present in the environment. Recomputed
+        # on every call so a process picks up a newly-set token without a
+        # restart.
+        #
+        # @return [Array<Module>] +Tool::Search::*+ provider modules, each
+        #   exposing +.search(query, max_results:)+ → +Array<Result>+
+        def self.providers
+          list = [DuckDuckGo]
+          list << Brave unless ENV[Brave::ENV_KEY].to_s.strip.empty?
+          list << Exa unless ENV[Exa::ENV_KEY].to_s.strip.empty?
+          list
+        end
+
+        # On-disk cache used by {.search} to memoize answered queries.
+        # Defined as a method so specs can swap it for an isolated cache
+        # or {UrlCache::NULL} without touching the shared instance.
+        #
+        # @return [UrlCache, #fetch]
+        CACHE = UrlCache.new(ttl: UrlCache::DEFAULT_TTL, dir: "#{UrlCache::ROOT_DIR}/web_search")
+        # Accessor for {CACHE}; specs override this to swap in
+        # {UrlCache::NULL} or an isolated cache.
+        #
+        # @return [UrlCache, #fetch]
+        def self.cache
+          CACHE
+        end
+
+        # Run +query+ through the configured providers in random order, falling
+        # back to the next one each time a provider raises {Unavailable}. The
+        # shuffle spreads load so a single provider isn't always hit first
+        # (and exhausted first); revisit if it stops being the right default.
+        #
+        # The query is whitespace-trimmed and runs of whitespace collapsed
+        # to a single space before the cascade runs. The winning provider's
+        # +Array<Result>+ is rendered into smolagents-style Markdown here
+        # (+"## Search Results"+ header, then +[title](url)\nbody+ entries
+        # joined by blank lines; an empty array becomes +"No results found."+),
+        # and the rendered Markdown is cached on disk via {.cache}, keyed by
+        # the cleaned query. A cache hit short-circuits the cascade entirely
+        # (and benefits whichever provider would have answered next time too
+        # — once a query is cached, the cooldown state of the original
+        # answering provider no longer matters). +max_results+ is not part
+        # of the cache key, so callers passing a non-default value may get
+        # a result rendered with the previously-cached size.
+        #
+        # If every provider reports temporary unavailability, returns an
+        # +"Error: ..."+ string instead of raising — same convention as
+        # {Tool::Calculator.calculate}, so the agent loop can feed the failure
+        # back to the model as the next observation. Any non-{Unavailable}
+        # exception (network error, parser failure, malformed response, bad
+        # API key) bubbles up to the caller.
+        #
+        # @param query [String] search query
+        # @param max_results [Integer] maximum number of result entries
+        # @return [String] Markdown-formatted result list, or +"Error: ..."+
+        #   when all providers are exhausted
+        # @raise [ArgumentError] if the query is empty after normalization
+        def self.search(query, max_results:)
+          cleaned = query.to_s.strip.gsub(/\s+/, ' ')
+          raise ArgumentError, 'query is empty' if cleaned.empty?
+
+          current_providers = providers
+          log_providers(current_providers)
+
+          hit = true
+          result = cache.fetch(cleaned) do
+            hit = false
+            failures = []
+            results = nil
+            chosen = nil
+            current_providers.shuffle.each do |provider|
+              results = provider.search(cleaned, max_results: max_results)
+              chosen = provider
+              break
+            rescue Unavailable => e
+              failures << "#{provider.name.split('::').last} (#{e.message})"
+            end
+            # Raise so {UrlCache#fetch} does NOT persist the all-unavailable
+            # message — otherwise that string would block every future search
+            # for this query until the TTL expires. The outer +rescue+ turns
+            # the raise back into the calculator-style "Error: …" string.
+            chosen or raise Unavailable, "all search providers temporarily unavailable: #{failures.join('; ')}"
+
+            LOGGER.info do
+              "engine=#{chosen.name.split('::').last} query=#{cleaned.inspect} results=#{results.size}"
+            end
+            render(results)
+          end
+          LOGGER.info { "cache=hit query=#{cleaned.inspect} bytes=#{result.bytesize}" } if hit
+          result
+        rescue Unavailable => e
+          "Error: #{e.message}"
+        end
+
+        # Render an +Array<Result>+ into the smolagents-style Markdown the
+        # LLM consumes: +"## Search Results"+ header, then +[title](url)\nbody+
+        # entries joined by blank lines. An empty array becomes the
+        # +"No results found."+ stub so the agent still gets a real
+        # observation to act on.
+        #
+        # @param results [Array<Result>] hits from the winning provider
+        # @return [String] Markdown-formatted result list
+        def self.render(results)
+          return "## Search Results\n\nNo results found." if results.empty?
+
+          "## Search Results\n\n" + results.map { |r| "[#{r.title}](#{r.url})\n#{r.body}" }.join("\n\n")
+        end
+        private_class_method :render
+
+        # Emit an INFO log line listing the currently-available providers,
+        # but only when the set differs from the last one we logged.
+        # {.providers} is recomputed on every {.search} call so a process
+        # picks up newly-set API keys without a restart; the memo here
+        # keeps the log to one line per distinct configuration rather
+        # than one per search.
+        #
+        # @param current [Array<Module>] providers returned by {.providers}
+        # @return [void]
+        def self.log_providers(current)
+          return if @last_logged_providers == current
+
+          @last_logged_providers = current
+          names = current.map { |p| p.name.split('::').last }.join(', ')
+          LOGGER.info("engines available: #{names}")
+        end
+        private_class_method :log_providers
+      end
+    end
+  end
+end

data/lib/pikuri/tool/search/exa.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Pikuri
+  class Tool
+    module Search
+      # Performs an Exa search via the official +/search+ endpoint and
+      # returns the hits as a list of {Result} rows. Split into a thin HTTP
+      # fetch (#search) and a pure parser (#parse) so tests can exercise
+      # the parser against fixture JSON without hitting the network. The
+      # cascade in {Engines.search} owns the final Markdown rendering.
+      #
+      # Requires an Exa API key. Get one at https://exa.ai — the service is
+      # paid, so the cascade in {Engines.providers} only includes Exa when
+      # {ENV_KEY} is set in the environment; users who haven't registered
+      # never spend money on it.
+      #
+      # Calls request +type: "auto"+ (Exa picks neural vs keyword per
+      # query) and +contents: { highlights: true }+ so each result carries
+      # a short neural-ranked snippet — the closest analog to Brave's
+      # +description+ field, populating {Result#body} consistently across
+      # providers.
+      #
+      # == Privacy posture
+      #
+      # Exa's Privacy Policy states +Query Data is used to improve our
+      # products and technology, including by training and fine-tuning
+      # models that power our Services+, and the Terms of Service §1.2(c)
+      # grant Exa a +perpetual and irrevocable+, +sub-licensable+,
+      # worldwide license over User Input that can be disclosed to third
+      # parties +as needed+. Business customers under a Master Subscription
+      # Agreement / DPA get carve-outs; the default pay-as-you-go API key
+      # (which is what pikuri uses) does not.
+      #
+      # Bottom line: Exa does not sell queries to data brokers, but it
+      # does mine them to train competing models, and the license it
+      # claims is effectively "do what we want with this, forever". If a
+      # query would be embarrassing or sensitive in a training set, drop
+      # Exa out of the cascade by unsetting {ENV_KEY} — {Engines.providers}
+      # is recomputed every call.
+      module Exa
+        # @return [String] Search endpoint (POST, JSON body)
+        ENDPOINT = 'https://api.exa.ai/search'
+        # @return [Integer] default number of results returned, matching
+        #   {DuckDuckGo::DEFAULT_MAX_RESULTS}
+        DEFAULT_MAX_RESULTS = 10
+        # @return [String] env var holding the API key; sent as +x-api-key+
+        ENV_KEY = 'EXA_API_KEY'
+        # @return [RateLimiter] Exa is paid and doesn't aggressively
+        #   throttle, so no minimum interval is enforced. The 5-minute
+        #   cooldown still applies on {Engines::Unavailable} so the user's
+        #   budget isn't burned on doomed retries while a 429 / 5xx
+        #   condition persists.
+        LIMITER = RateLimiter.new(min_interval: 0.0, cooldown: 300.0)
+
+        # Fetch results for +query+ and return them as an +Array<Result>+.
+        # Calls are circuit-broken for 5 minutes on rate-limit / unavailable
+        # responses; see {LIMITER}. The caller (typically {Engines.search})
+        # is expected to have already normalized the query and to wrap this
+        # in a result cache.
+        #
+        # @param query [String] search query (already normalized)
+        # @param max_results [Integer] maximum number of result entries;
+        #   passed through as Exa's +numResults+
+        # @param api_key [String] Exa API key; defaults to the {ENV_KEY}
+        #   environment variable
+        # @return [Array<Result>] hits, possibly empty when Exa ran the
+        #   query and matched nothing
+        # @raise [ArgumentError] if no API key is available
+        # @raise [Engines::Unavailable] when Exa returns HTTP 429
+        #   (rate limit / quota exhausted) or 5xx — "try again later"
+        #   responses the cascade in {Engines.search} can fall back from.
+        #   Also raised immediately if {LIMITER} is in cooldown. Other
+        #   non-2xx (e.g. 401/403 from a bad API key) bubble up as
+        #   +RuntimeError+ so config problems stay visible.
+        # @raise [RuntimeError] for non-rate-limit HTTP failures or when the
+        #   response shape contains no results and isn't a recognized
+        #   empty-results payload.
+        def self.search(query, max_results: DEFAULT_MAX_RESULTS, api_key: ENV.fetch(ENV_KEY, nil))
+          raise ArgumentError, "Exa Search API key not set (#{ENV_KEY})" if api_key.to_s.strip.empty?
+
+          LIMITER.call do
+            response = Faraday.post(ENDPOINT) do |req|
+              req.headers['x-api-key'] = api_key
+              req.headers['Content-Type'] = 'application/json'
+              req.headers['Accept'] = 'application/json'
+              req.body = JSON.dump(
+                query: query,
+                type: 'auto',
+                numResults: max_results,
+                contents: { highlights: true }
+              )
+            end
+            unless response.success?
+              if response.status == 429 || response.status >= 500
+                raise Engines::Unavailable, "HTTP #{response.status}"
+              end
+
+              raise "Exa Search request failed: #{response.status} #{response.body}"
+            end
+
+            parse(response.body, max_results: max_results)
+          end
+        end
+
+        # Parse an Exa Search JSON response into a list of {Result} rows,
+        # where +body+ is the first non-empty +highlights+ snippet (empty
+        # when Exa returned no highlight for that result — e.g. for
+        # navigational results).
+        #
+        # When the response yields zero result entries, two cases are
+        # distinguished: a genuine "no results" payload (response carries
+        # a +requestId+ and an empty +results+ array — Exa ran the query
+        # but matched nothing) returns an empty array instead of raising,
+        # so {Engines.search} can render its standard no-results stub.
+        # Anything else (unknown shape, structured error) raises with a
+        # diagnostic so the failure surfaces.
+        #
+        # @param json [String] response body from {ENDPOINT}
+        # @param max_results [Integer] maximum number of result entries
+        # @return [Array<Result>] hits, possibly empty on a recognized
+        #   empty-results payload
+        # @raise [RuntimeError] when the response yields no result entries and
+        #   is not recognized as a genuine empty-results payload
+        def self.parse(json, max_results: DEFAULT_MAX_RESULTS)
+          data = JSON.parse(json)
+          results = Array(data['results']).take(max_results).filter_map do |r|
+            href = r['url'].to_s
+            next nil if href.empty?
+
+            Result.new(
+              url: href,
+              title: clean(r['title']) || href,
+              body: first_highlight(r['highlights'])
+            )
+          end
+
+          if results.empty?
+            return [] if genuine_no_results?(data)
+
+            raise diagnose_empty(data, json)
+          end
+
+          results
+        end
+
+        # Collapse whitespace and strip; returns +nil+ for nil/empty input
+        # so the caller can fall back (typically to the URL when a result
+        # has no usable title).
+        #
+        # @param text [String, nil] raw text from an Exa result field
+        # @return [String, nil] cleaned text, or +nil+ if input was blank
+        def self.clean(text)
+          return nil if text.nil?
+
+          cleaned = text.to_s.gsub(/\s+/, ' ').strip
+          cleaned.empty? ? nil : cleaned
+        end
+        private_class_method :clean
+
+        # First non-empty entry from a +highlights+ array, cleaned. Exa
+        # returns highlights as an array sorted by relevance; we surface
+        # only the top one to keep the observation compact and match the
+        # one-line +body+ convention used by Brave / DuckDuckGo.
+        #
+        # @param highlights [Array<String>, nil] +highlights+ field
+        # @return [String] cleaned snippet, or empty string if none usable
+        def self.first_highlight(highlights)
+          return '' unless highlights.is_a?(Array)
+
+          highlights.each do |h|
+            cleaned = clean(h)
+            return cleaned if cleaned
+          end
+          ''
+        end
+        private_class_method :first_highlight
+
+        # True when a parsed response with zero +results+ entries looks
+        # like Exa's own "search ran, nothing matched" payload rather than
+        # a malformed or error response. The marker is the +requestId+
+        # field, which Exa always sets on a successful request.
+        #
+        # @param data [Hash, Object] parsed response
+        # @return [Boolean]
+        def self.genuine_no_results?(data)
+          return false unless data.is_a?(Hash)
+          return false unless data.key?('requestId')
+
+          Array(data['results']).empty?
+        end
+        private_class_method :genuine_no_results?
+
+        # Build an error message for a parsed response that yielded zero
+        # results. Quotes Exa's +error+ / +message+ / +detail+ field if
+        # present, otherwise truncates the raw body so the caller can see
+        # the actual payload.
+        #
+        # @param data [Hash, Object] parsed response
+        # @param raw [String] raw response body
+        # @return [String] human-readable diagnostic to feed to +raise+
+        def self.diagnose_empty(data, raw)
+          if data.is_a?(Hash) && (msg = data['error'] || data['message'] || data['detail'])
+            return "Exa Search returned an error: #{msg}"
+          end
+
+          snippet = raw.to_s[0, 800]
+          snippet += '…' if raw.to_s.length > 800
+          "Exa Search returned no results. Body: #{snippet}"
+        end
+        private_class_method :diagnose_empty
+      end
+    end
+  end
+end

data/lib/pikuri/tool/search/rate_limiter.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Loaded after {Tool} itself is defined; the +class Tool+ reopening below
+  # assumes that order.
+  class Tool
+    module Search
+      # Thread-safe pacing + circuit-breaker wrapper for a search provider.
+      #
+      # +#call { ... }+ enforces a minimum interval between consecutive
+      # invocations of the block (sleeping if the previous one was too
+      # recent), and watches for {Engines::Unavailable} raised by the
+      # block: when that happens, a cooldown deadline is recorded and
+      # further calls within the window raise {Engines::Unavailable}
+      # immediately without invoking the block. This stops a provider
+      # that has been rate-limited or bot-blocked from being hammered
+      # with retries.
+      #
+      # The mutex is held across the block, so concurrent callers
+      # serialize — matching the behavior {DuckDuckGo} has always
+      # required to keep its IP-spacing throttle correct under
+      # concurrent agents.
+      #
+      # Uses wall-clock {Time.now} rather than the monotonic clock; the
+      # intervals here are 1s–5min, well above any realistic NTP step,
+      # and {Time.now} keeps tests trivially fakeable with Timecop.
+      class RateLimiter
+        # @param min_interval [Float] minimum seconds between consecutive
+        #   block invocations. {#call} sleeps if a previous call was more
+        #   recent.
+        # @param cooldown [Float] seconds to refuse calls after the block
+        #   raises {Engines::Unavailable}. Calls within this window raise
+        #   {Engines::Unavailable} immediately without invoking the block.
+        def initialize(min_interval:, cooldown:)
+          @min_interval = min_interval
+          @cooldown = cooldown
+          @mutex = Mutex.new
+          @last_call_at = nil
+          @cooldown_until = nil
+        end
+
+        # Run the given block subject to throttle and cooldown rules.
+        #
+        # The block is invoked with the mutex held, so concurrent calls
+        # serialize: only one block runs at a time per limiter instance.
+        # If the block raises {Engines::Unavailable}, the cooldown is
+        # armed and the exception is re-raised. Any other exception
+        # bubbles up without arming cooldown — only "try again later"
+        # signals from the provider are treated as backoff triggers.
+        #
+        # @yieldreturn [Object] block's return value is passed through
+        # @return [Object] whatever the block returned
+        # @raise [Engines::Unavailable] either re-raised from the block,
+        #   or raised directly when the limiter is currently in cooldown
+        def call
+          @mutex.synchronize do
+            now = Time.now
+            if @cooldown_until && now < @cooldown_until
+              remaining = (@cooldown_until - now).ceil
+              raise Engines::Unavailable, "rate-limiter cooldown active for another #{remaining}s"
+            end
+
+            if @last_call_at
+              elapsed = now - @last_call_at
+              sleep_for(@min_interval - elapsed) if elapsed < @min_interval
+            end
+            @last_call_at = Time.now
+
+            begin
+              yield
+            rescue Engines::Unavailable
+              @cooldown_until = Time.now + @cooldown
+              raise
+            end
+          end
+        end
+
+        # Sleep for +seconds+. Isolated as a private method so tests can
+        # override it on a single instance (typically to advance a frozen
+        # Timecop clock by the same amount) without monkey-patching the
+        # global +sleep+.
+        #
+        # @param seconds [Float] non-negative duration to sleep
+        # @return [void]
+        def sleep_for(seconds)
+          sleep(seconds)
+        end
+        private :sleep_for
+      end
+    end
+  end
+end

data/lib/pikuri/tool/search/result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    module Search
+      # A single search hit produced by a {Tool::Search} provider
+      # ({DuckDuckGo}, {Brave}, {Exa}). Providers return +Array<Result>+
+      # from +.parse+ / +.search+; {Engines.search} concatenates the
+      # rows into the smolagents-style Markdown the LLM sees.
+      #
+      # Splitting structure from rendering keeps the three providers
+      # interchangeable — they only have to agree on these three fields
+      # (provider-specific extras like relevance scores or published
+      # dates are discarded today, which is fine because no caller uses
+      # them).
+      #
+      # @!attribute [r] url
+      #   @return [String] absolute URL of the hit
+      # @!attribute [r] title
+      #   @return [String] plain-text title, with provider-specific
+      #     highlight markup ({Brave}'s +<strong>+, {DuckDuckGo}'s
+      #     +<b>+) already stripped
+      # @!attribute [r] body
+      #   @return [String] plain-text snippet, possibly empty (e.g. an
+      #     {Exa} navigational result with no highlights)
+      Result = Data.define(:url, :title, :body)
+    end
+  end
+end

data/lib/pikuri/tool/sub_agent.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +sub_agent+ tool, expressed as a {Tool} subclass: instantiating
+    # +Tool::SubAgent.new(parent_agent)+ produces a tool whose
+    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's,
+    # so ruby_llm sees nothing special about it. When the model calls it,
+    # the closure inside +execute+ spawns a fresh {Agent} that runs its
+    # own Thought / Tool-call / Observation loop on a clean message
+    # history, then returns only the sub-agent's final assistant message
+    # back as the parent's next observation.
+    #
+    # The sub-agent reuses the parent's +transport+, +system_prompt+,
+    # +context_window_cap+, and +name+ (as its hierarchical prefix), so
+    # it shares the same persona, hits the same server, and inherits the
+    # same context-window cap without re-probing. Its tool list is a
+    # snapshot of the parent's {Agent#tools} taken at construction —
+    # {Agent#allow_sub_agent} only appends the sub-agent tool to its own
+    # +@tools+ *after* this snapshot, so the sub-agent's tool list never
+    # contains itself (recursion guard).
+    #
+    # Its listener list comes from the parent's {Agent#listeners} via
+    # {Agent::ListenerList#for_sub_agent}, which forwards to each
+    # listener's own +for_sub_agent+ hook: +Terminal+ swaps to a padded
+    # fresh instance, +TokenLog+ resets its snapshot, and listeners
+    # without the hook ({Agent::Listener::InMemoryEventList}, …) are
+    # shared by reference so structured capture flows continuously.
+    #
+    # Controls are derived per the per-control rule: a fresh
+    # {Agent::Control::StepLimit} at the new cap (mutable counter is
+    # per-chat), the same {Agent::Control::Cancellable} shared by
+    # reference (one +cancel!+ stops the whole tree), and no
+    # {Agent::Control::Interloper} (the host has no handle to
+    # sub-agents).
+    #
+    # All parent state is captured by value at construction — the closure
+    # does not chase +parent_agent+ mutations later. The one piece of
+    # mutable state is a monotonic counter used to generate sub-agent ids:
+    # +"sub_agent 0"+, +"sub_agent 1"+, ... at the top level; nested
+    # children of +"sub_agent 0"+ are +"sub_agent 0_0"+, +"sub_agent 0_1"+,
+    # ... — the +"sub_agent "+ prefix appears once at the top and the
+    # underscore-separated counter chain records depth.
+    class SubAgent < Tool
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Delegate a self-contained task to a fresh sub-agent that runs its own Thought / Tool-call / Observation loop on a clean conversation, returning only its final assistant message.
+
+        Usage:
+        - Use to isolate side-quests — research, multi-step lookups, exploratory tool use — so intermediate observations do not clutter your own context.
+        - The sub-agent has your tools minus `sub_agent` itself, so it cannot recurse.
+        - It shares your system prompt — persona, tool-use conventions, and output format carry over. Do NOT re-explain who you are or how to use tools.
+        - It cannot see your conversation. Put ALL task-specific context inside `task`; the sub-agent has zero memory of what came before.
+      DESC
+
+      # @param parent_agent [Agent] the calling agent. Read for its
+      #   {Agent#transport}, {Agent#system_prompt}, {Agent#tools},
+      #   {Agent#listeners}, {Agent#step_limit}, {Agent#cancellable},
+      #   {Agent#context_window_cap}, {Agent#name}, and
+      #   {Agent#extensions} (so the sub-agent inherits and re-binds
+      #   the parent's extension list).
+      # @param max_steps [Integer] step budget for each sub-agent run,
+      #   used to construct the sub-agent's own
+      #   {Agent::Control::StepLimit}.
+      # @return [SubAgent]
+      def initialize(parent_agent, max_steps: 10)
+        transport         = parent_agent.transport
+        system_prompt     = parent_agent.system_prompt
+        sub_tools         = parent_agent.tools.dup
+        listeners         = parent_agent.listeners
+        parent_step_limit = parent_agent.step_limit
+        parent_cancel     = parent_agent.cancellable
+        context_window    = parent_agent.context_window_cap
+        parent_name       = parent_agent.name
+        streaming         = parent_agent.streaming
+        # Parent's extension list, captured at SubAgent construction
+        # so spawned sub-agents share the *same* extension instances
+        # (configure has already run on the parent — the resulting
+        # tools / snippets / listeners are inherited verbatim via
+        # the kwargs above). Each inherited extension's +bind+ fires
+        # inside the sub-agent's +Agent#initialize+ — that's how
+        # MCP's per-agent connect tool ends up keyed to the
+        # sub-agent rather than the parent, while still sharing the
+        # parent's live MCP clients through the extension instance.
+        # See IDEAS.md §"Sub-agent inheritance — configure-once,
+        # bind-per-agent".
+        inherited_exts    = parent_agent.extensions
+        sub_counter       = 0
+
+        super(
+          name: 'sub_agent',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :task,
+                              'Self-contained instructions for the sub-agent, ' \
+                              'e.g. "Find the populations of Reykjavik and ' \
+                              'Helsinki in 2024 and report both numbers." ' \
+                              'It has no access to the parent conversation, ' \
+                              'so include all necessary context.'
+          },
+          execute: lambda { |task:|
+            idx = sub_counter
+            sub_counter += 1
+            sub_name = parent_name.empty? ? "sub_agent #{idx}" : "#{parent_name}_#{idx}"
+            sub_listeners = listeners.for_sub_agent(name: sub_name)
+
+            # All inherited state is seeded through the Configurator
+            # block — tools and listeners via add_tools / add_listeners,
+            # extensions via inherit_extensions which retains them for
+            # the bind sweep without re-running configure (the parent
+            # already drove that and the resulting system-prompt
+            # snippets are inherited verbatim through +system_prompt+).
+            sub = Agent.new(
+              transport: transport,
+              system_prompt: system_prompt,
+              step_limit: parent_step_limit&.for_sub_agent(max_steps: max_steps),
+              cancellable: parent_cancel&.for_sub_agent,
+              context_window: context_window,
+              name: sub_name,
+              streaming: streaming
+            ) do |c|
+              c.add_tools(sub_tools)
+              c.add_listeners(sub_listeners)
+              c.inherit_extensions(inherited_exts)
+            end
+            begin
+              sub.run_loop(user_message: task)
+              sub.last_assistant_content
+            ensure
+              # The sub-agent borrows the parent's MCP clients via
+              # the shared {Mcp::Extension} instance; it doesn't own
+              # them. {#close} still fires its own +on_close+ list
+              # (empty for a sub-agent — no extensions registered
+              # any handlers via the inherited path, since they only
+              # re-bind here, not re-configure), so this is a no-op
+              # today. Calling +#close+ anyway means any future
+              # sub-agent-owned resource gets released without
+              # revisiting this site. See {Agent#close}.
+              sub.close
+            end
+          }
+        )
+      end
+    end
+  end
+end