brute 0.1.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a36d054875f1465a0e9bfc380187c98ff08f837f8477f062f784652246d4256
-  data.tar.gz: a7c4df2710346a213b3ded2ee9be7d84b0bbe50d04c9e1ac9eaa679b9a35a7b2
+  metadata.gz: 434ac3760153b860523176d38105ee8618ec95025713a332745281cda1af4cb8
+  data.tar.gz: 3358b33334bf01bd79188c1fb488729997b090bb4617063bc2f61579358b63d6
 SHA512:
-  metadata.gz: 7893f212130fc7dd94d80e3bf6b926d47ab86e37fc629866bbbec674121d4e8083791a2b66b4437af98d2cb694c0dc89655519844f5797fe1f17e8652d4ddd01
-  data.tar.gz: 1c48113815f9ad3f2d068252e851167b369e22ab8c1d5bd1d314387acab5f1e4169a49cde91f7c5bbb4847ade234779712f3f7b5d3fcc43b6c76b80478017a26
+  metadata.gz: 03a3b9866b7e32cc44b260bdd8655983f2776d9c14235bc98f04a26e57f949070b9a3bae87008fb940bd44e9eb671f373f5544759f5ced71026a2c55eac6df44
+  data.tar.gz: f3896062d7c20fb622463c4af6b122b8d1281a9ff1147d2b8d8a747ea372fc8631609449652229dd10a604570b866119005449673273ac029d43ab087d9f5b5f

data/lib/brute/agent_stream.rb

@@ -1,32 +1,38 @@
 # frozen_string_literal: true
 
 module Brute
-  # Bridges llm.rb's streaming callbacks to forge-rb's callback system.
+  # Bridges llm.rb's streaming callbacks to the host application.
   #
   # Text and reasoning chunks fire immediately as the LLM generates them.
-  # Tool calls spawn threads on arrival — tools start running while the
-  # response is still streaming. on_tool_result fires as each thread finishes.
+  # Tool calls are collected but NOT executed — execution is deferred to the
+  # orchestrator after the stream completes. This ensures text is never
+  # concurrent with tool execution.
+  #
+  # After the stream finishes, the orchestrator reads +pending_tools+ to
+  # dispatch all tool calls concurrently, then fires +on_tool_call_start+
+  # once with the full batch.
   #
   class AgentStream < LLM::Stream
     # Tool call metadata recorded during streaming, used by ToolUseGuard
     # when ctx.functions is empty (nil-choice bug in llm.rb).
-    # Cleared by the guard after consumption to prevent stale data from
-    # causing duplicate synthetic assistant messages on subsequent calls.
     attr_reader :pending_tool_calls
 
-    def clear_pending_tool_calls!
-      @pending_tool_calls.clear
-    end
+    # Deferred tool/error pairs: [(LLM::Function, error_or_nil), ...]
+    # The orchestrator reads these after the stream completes.
+    attr_reader :pending_tools
 
-    def initialize(on_content: nil, on_reasoning: nil, on_tool_call: nil, on_tool_result: nil, on_question: nil)
+    def initialize(on_content: nil, on_reasoning: nil, on_question: nil)
       @on_content = on_content
       @on_reasoning = on_reasoning
-      @on_tool_call = on_tool_call
-      @on_tool_result = on_tool_result
       @on_question = on_question
       @pending_tool_calls = []
+      @pending_tools = []
     end
 
+    # The on_question callback, needed by the orchestrator to set
+    # thread/fiber-locals before tool execution.
+    attr_reader :on_question
+
     def on_content(text)
       @on_content&.call(text)
     end
@@ -35,30 +41,17 @@ module Brute
       @on_reasoning&.call(text)
     end
 
+    # Called by llm.rb per tool as it arrives during streaming.
+    # Records only — no execution, no threads, no queue pushes.
     def on_tool_call(tool, error)
       @pending_tool_calls << { id: tool.id, name: tool.name, arguments: tool.arguments }
-      @on_tool_call&.call(tool.name, tool.arguments)
-
-      if error
-        queue << error
-        @on_tool_result&.call(tool.name, error.value)
-      else
-        queue << LLM::Function::Task.new(spawn_with_callback(tool))
-      end
+      @pending_tools << [tool, error]
     end
 
-    private
-
-    def spawn_with_callback(tool)
-      on_result = @on_tool_result
-      on_question = @on_question
-      name = tool.name
-      Thread.new do
-        Thread.current[:on_question] = on_question
-        result = tool.call
-        on_result&.call(name, result.respond_to?(:value) ? result.value : result)
-        result
-      end
+    # Clear all deferred state after the orchestrator has consumed it.
+    def clear_pending!
+      @pending_tool_calls.clear
+      @pending_tools.clear
     end
   end
 end

data/lib/brute/middleware/tool_use_guard.rb

@@ -56,7 +56,7 @@ module Brute
           stream = resolve_stream(ctx)
           if stream
             data = stream.pending_tool_calls.dup
-            stream.clear_pending_tool_calls!
+            stream.clear_pending!
             data
           else
             []

data/lib/brute/orchestrator.rb

@@ -17,6 +17,11 @@ module Brute
   #   2. Executes any tool calls the LLM requested
   #   3. Repeats until done or a limit is hit
   #
+  # Tool execution is always deferred until after the LLM response (including
+  # streaming) completes. Tools then run concurrently with each other via
+  # Async::Barrier. on_tool_call_start fires once with the full batch before
+  # execution begins; on_tool_result fires per-tool as each finishes.
+  #
   class Orchestrator
     MAX_REQUESTS_PER_TURN = 100
 
@@ -33,7 +38,7 @@ module Brute
       agent_name: nil,
       on_content: nil,
       on_reasoning: nil,
-      on_tool_call: nil,
+      on_tool_call_start: nil,
       on_tool_result: nil,
       on_question: nil,
       logger: nil
@@ -62,8 +67,6 @@ module Brute
         AgentStream.new(
           on_content: on_content,
           on_reasoning: on_reasoning,
-          on_tool_call: on_tool_call,
-          on_tool_result: on_tool_result,
           on_question: on_question,
         )
       end
@@ -95,7 +98,7 @@ module Brute
         callbacks: {
           on_content: on_content,
           on_reasoning: on_reasoning,
-          on_tool_call: on_tool_call,
+          on_tool_call_start: on_tool_call_start,
           on_tool_result: on_tool_result,
           on_question: on_question,
         },
@@ -131,15 +134,28 @@ module Brute
 
       # --- Agent loop ---
       loop do
-        break if @context.functions.empty? && (!@stream || @stream.queue.empty?)
-
-        # Collect tool results.
-        # Streaming: tools already spawned threads during the LLM response — just join them.
-        # Non-streaming: execute manually (parallel or sequential).
-        results = if @stream && !@stream.queue.empty?
-          @context.wait(:thread)
-        else
-          execute_tool_calls
+        # Collect pending tools from either source:
+        # - Streaming: AgentStream deferred tools (collected during stream)
+        # - Non-streaming: ctx.functions (populated by llm.rb after response)
+        pending = collect_pending_tools
+        break if pending.empty?
+
+        # Fire on_tool_call_start ONCE with the full batch
+        on_start = @env.dig(:callbacks, :on_tool_call_start)
+        on_start&.call(pending.map { |tool, _| { name: tool.name, arguments: tool.arguments } })
+
+        # Separate errors (tool not found) from executable tools
+        errors = pending.select { |_, err| err }
+        executable = pending.reject { |_, err| err }.map(&:first)
+
+        # Execute tools concurrently, collect results
+        results = execute_tool_calls(executable)
+
+        # Append error results (tool not found, etc.)
+        errors.each do |_, err|
+          on_result = @env.dig(:callbacks, :on_tool_result)
+          on_result&.call(err.name, result_value(err))
+          results << err
         end
 
         # Send results back through the pipeline
@@ -151,7 +167,7 @@ module Brute
         @request_count += 1
 
         # Check limits
-        break if @context.functions.empty? && (!@stream || @stream.queue.empty?)
+        break if collect_pending_tools.empty?
         break if @request_count >= MAX_REQUESTS_PER_TURN
         break if @env[:metadata][:tool_error_limit_reached]
       end
@@ -222,24 +238,55 @@ module Brute
       end
     end
 
+    # ------------------------------------------------------------------
+    # Pending tool collection
+    # ------------------------------------------------------------------
+
+    # Collect pending tools from the stream (streaming) or context (non-streaming).
+    # Returns an array of [tool, error_or_nil] pairs.
+    # Clears the stream's deferred state after consumption.
+    def collect_pending_tools
+      if @stream&.pending_tools&.any?
+        tools = @stream.pending_tools.dup
+        @stream.clear_pending!
+        tools
+      elsif @context.functions.any?
+        @context.functions.to_a.map { |fn| [fn, nil] }
+      else
+        []
+      end
+    end
+
     # ------------------------------------------------------------------
     # Tool execution
     # ------------------------------------------------------------------
 
-    def execute_tool_calls
-      pending = @context.functions.to_a
-      return execute_sequential(pending) if pending.size <= 1
+    def execute_tool_calls(functions)
+      return [] if functions.empty?
+
+      # Questions block execution — they must complete before other tools
+      # run, since the LLM may need the answer to inform subsequent work.
+      # Execute any question tools first (sequentially), then dispatch
+      # the remaining tools concurrently.
+      questions, others = functions.partition { |fn| fn.name == "question" }
 
-      execute_parallel(pending)
+      results = []
+      results.concat(execute_sequential(questions)) if questions.any?
+      if others.size <= 1
+        results.concat(execute_sequential(others))
+      else
+        results.concat(execute_parallel(others))
+      end
+      results
     end
 
     # Run a single tool call synchronously.
     def execute_sequential(functions)
-      on_call = @env.dig(:callbacks, :on_tool_call)
       on_result = @env.dig(:callbacks, :on_tool_result)
+      on_question = @env.dig(:callbacks, :on_question)
 
       functions.map do |fn|
-        on_call&.call(fn.name, fn.arguments)
+        Thread.current[:on_question] = on_question
         result = fn.call
         on_result&.call(fn.name, result_value(result))
         result
@@ -256,8 +303,8 @@ module Brute
     # The barrier is stored in @barrier so abort! can cancel in-flight tools.
     #
     def execute_parallel(functions)
-      on_call = @env.dig(:callbacks, :on_tool_call)
       on_result = @env.dig(:callbacks, :on_tool_result)
+      on_question = @env.dig(:callbacks, :on_question)
 
       results = Array.new(functions.size)
 
@@ -266,7 +313,7 @@ module Brute
 
         functions.each_with_index do |fn, i|
           @barrier.async do
-            on_call&.call(fn.name, fn.arguments)
+            Thread.current[:on_question] = on_question
             results[i] = fn.call
             r = results[i]
             on_result&.call(r.name, result_value(r))

data/lib/brute/pipeline.rb

@@ -22,7 +22,7 @@ module Brute
   #     tools:     [Tool, ...],       # tool classes
   #     params:    {},                # extra LLM call params (reasoning config, etc.)
   #     metadata:  {},                # shared scratchpad for middleware state
-  #     callbacks: {},                # :on_content, :on_tool_call, :on_tool_result
+  #     callbacks: {},                # :on_content, :on_tool_call_start, :on_tool_result
   #   }
   #
   # ## The response

data/lib/brute/providers/models_dev.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Brute
+  module Providers
+    # Fetches and caches model metadata from the models.dev catalog.
+    #
+    # Quacks like llm.rb's provider.models so that the REPL's model
+    # picker can call:
+    #
+    #   provider.models.all.select(&:chat?)
+    #
+    # Models are fetched from https://models.dev/api.json and cached
+    # in-memory for the lifetime of the process (with a TTL).
+    #
+    class ModelsDev
+      CATALOG_URL = "https://models.dev/api.json"
+      CACHE_TTL = 3600 # 1 hour
+
+      ModelEntry = Struct.new(:id, :name, :chat?, :cost, :limit, :reasoning, :tool_call, keyword_init: true)
+
+      # @param provider [LLM::Provider] the provider instance (for delegating execute/headers)
+      # @param provider_id [String] the provider key in models.dev (e.g., "opencode", "opencode-go")
+      def initialize(provider:, provider_id: "opencode")
+        @provider = provider
+        @provider_id = provider_id
+      end
+
+      # Returns all models for this provider from the models.dev catalog.
+      # @return [Array<ModelEntry>]
+      def all
+        entries = fetch_provider_models
+        entries.map do |id, model|
+          ModelEntry.new(
+            id: id,
+            name: model["name"] || id,
+            chat?: true,
+            cost: model["cost"],
+            limit: model["limit"],
+            reasoning: model["reasoning"] || false,
+            tool_call: model["tool_call"] || false
+          )
+        end.sort_by(&:id)
+      end
+
+      private
+
+      def fetch_provider_models
+        catalog = self.class.fetch_catalog
+        provider_data = catalog[@provider_id]
+        return {} unless provider_data
+
+        provider_data["models"] || {}
+      end
+
+      class << self
+        # Fetch the models.dev catalog, with in-memory caching.
+        # Thread-safe via a simple mutex.
+        def fetch_catalog
+          @mutex ||= Mutex.new
+          @mutex.synchronize do
+            if @catalog && @fetched_at && (Time.now - @fetched_at < CACHE_TTL)
+              return @catalog
+            end
+
+            @catalog = download_catalog
+            @fetched_at = Time.now
+            @catalog
+          end
+        end
+
+        # Force a cache refresh on next access.
+        def invalidate_cache!
+          @mutex&.synchronize do
+            @catalog = nil
+            @fetched_at = nil
+          end
+        end
+
+        private
+
+        def download_catalog
+          uri = URI.parse(CATALOG_URL)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 10
+          http.read_timeout = 30
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          request["User-Agent"] = "brute/#{Brute::VERSION}"
+          request["Accept"] = "application/json"
+
+          response = http.request(request)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise "Failed to fetch models.dev catalog: HTTP #{response.code}"
+          end
+
+          JSON.parse(response.body)
+        rescue => e
+          # Return empty catalog on failure so the provider still works
+          # with default_model, just without a model list.
+          warn "[brute] Warning: Could not fetch models.dev catalog: #{e.message}"
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/brute/providers/opencode_go.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module LLM
+  ##
+  # OpenAI-compatible provider for the OpenCode Go API gateway.
+  #
+  # OpenCode Go is the low-cost subscription plan with a restricted
+  # (lite) model list. Same gateway as Zen, different endpoint path.
+  #
+  # @example
+  #   llm = LLM::OpencodeGo.new(key: ENV["OPENCODE_API_KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello from brute"
+  #
+  class OpencodeGo < OpencodeZen
+    ##
+    # @return [Symbol]
+    def name
+      :opencode_go
+    end
+
+    ##
+    # Returns models from the models.dev catalog.
+    # Note: The Go gateway only accepts lite-tier models, but models.dev
+    # doesn't distinguish between Zen and Go tiers. We show the full
+    # catalog; the gateway returns an error for unsupported models.
+    # @return [Brute::Providers::ModelsDev]
+    def models
+      Brute::Providers::ModelsDev.new(provider: self, provider_id: "opencode")
+    end
+
+    private
+
+    def completions_path
+      "/zen/go/v1/chat/completions"
+    end
+  end
+end

data/lib/brute/providers/opencode_zen.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Ensure the OpenAI provider is loaded (llm.rb lazy-loads providers).
+unless defined?(LLM::OpenAI)
+  require "llm/providers/openai"
+end
+
+module LLM
+  ##
+  # OpenAI-compatible provider for the OpenCode Zen API gateway.
+  #
+  # OpenCode Zen is a curated model gateway at opencode.ai that proxies
+  # requests to upstream LLM providers (Anthropic, OpenAI, Google, etc.).
+  # All models are accessed via the OpenAI-compatible chat completions
+  # endpoint; the gateway handles format conversion internally.
+  #
+  # @example
+  #   llm = LLM::OpencodeZen.new(key: ENV["OPENCODE_API_KEY"])
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello from brute"
+  #
+  # @example Anonymous access (free models only)
+  #   llm = LLM::OpencodeZen.new(key: "public")
+  #   ctx = LLM::Context.new(llm)
+  #   ctx.talk "Hello"
+  #
+  class OpencodeZen < OpenAI
+    HOST = "opencode.ai"
+
+    ##
+    # @param key [String] OpenCode API key, or "public" for anonymous access
+    # @param (see LLM::Provider#initialize)
+    def initialize(key: "public", **)
+      super(host: HOST, key: key, **)
+    end
+
+    ##
+    # @return [Symbol]
+    def name
+      :opencode_zen
+    end
+
+    ##
+    # Returns the default model (Claude Sonnet 4, the most common Zen model).
+    # @return [String]
+    def default_model
+      "claude-sonnet-4-20250514"
+    end
+
+    ##
+    # Returns models from the models.dev catalog for the opencode provider.
+    # @return [Brute::Providers::ModelsDev]
+    def models
+      Brute::Providers::ModelsDev.new(provider: self, provider_id: "opencode")
+    end
+
+    # -- Unsupported sub-APIs --
+
+    def responses    = raise(NotImplementedError, "Use chat completions via the Zen gateway")
+    def images       = raise(NotImplementedError, "Not supported via Zen gateway")
+    def audio        = raise(NotImplementedError, "Not supported via Zen gateway")
+    def files        = raise(NotImplementedError, "Not supported via Zen gateway")
+    def moderations  = raise(NotImplementedError, "Not supported via Zen gateway")
+    def vector_stores = raise(NotImplementedError, "Not supported via Zen gateway")
+
+    private
+
+    def completions_path
+      "/zen/v1/chat/completions"
+    end
+
+    def headers
+      lock do
+        (@headers || {}).merge(
+          "Content-Type" => "application/json",
+          "Authorization" => "Bearer #{@key}",
+          "x-opencode-client" => "brute"
+        )
+      end
+    end
+  end
+end

data/lib/brute/providers/shell.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Brute
+  module Providers
+    # A pseudo-LLM provider that executes user input as code via the
+    # existing Brute::Tools::Shell tool.
+    #
+    # Models correspond to interpreters:
+    #
+    #   bash   - pass-through (default)
+    #   ruby   - ruby -e '...'
+    #   python - python3 -c '...'
+    #   nix    - nix eval --expr '...'
+    #
+    # The provider's #complete method returns a synthetic response
+    # containing a single "shell" tool call. The orchestrator executes
+    # it through the normal pipeline — all middleware (message tracking,
+    # session persistence, token tracking, etc.) fires as usual.
+    #
+    class Shell
+      MODELS = %w[bash ruby python nix].freeze
+
+      INTERPRETERS = {
+        "bash"   => ->(cmd) { cmd },
+        "ruby"   => ->(cmd) { "ruby -e #{Shellwords.escape(cmd)}" },
+        "python" => ->(cmd) { "python3 -c #{Shellwords.escape(cmd)}" },
+        "nix"    => ->(cmd) { "nix eval --expr #{Shellwords.escape(cmd)}" },
+      }.freeze
+
+      # ── LLM::Provider duck-type interface ──────────────────────────
+
+      def name           = :shell
+      def default_model  = "bash"
+      def user_role      = :user
+      def tool_role      = :tool
+      def assistant_role = :assistant
+      def system_role    = :system
+      def tracer         = LLM::Tracer::Null.new(self)
+
+      def complete(prompt, params = {})
+        model = params[:model]&.to_s || default_model
+        text  = extract_text(prompt)
+        tools = params[:tools] || []
+
+        # nil text means we received tool results (second call) —
+        # return an empty assistant response so the orchestrator exits.
+        return ShellResponse.new(model: model, tools: tools) if text.nil?
+
+        wrap    = INTERPRETERS.fetch(model, INTERPRETERS["bash"])
+        command = wrap.call(text)
+
+        ShellResponse.new(command: command, model: model, tools: tools)
+      end
+
+      # For the REPL model picker: provider.models.all.select(&:chat?)
+      def models
+        ModelList.new(MODELS)
+      end
+
+      # ── Internals ──────────────────────────────────────────────────
+
+      private
+
+      # Extract the user's text from whatever prompt format ctx.talk sends.
+      # Returns nil when the prompt contains tool results (the second
+      # round-trip) so #complete knows to return an empty response.
+      def extract_text(prompt)
+        case prompt
+        when String
+          prompt
+        when ::Array
+          return nil if prompt.any? { |p| LLM::Function::Return === p }
+
+          user_msg = prompt.reverse_each.find { |m| m.respond_to?(:role) && m.role.to_s == "user" }
+          user_msg&.content.to_s
+        else
+          if prompt.respond_to?(:to_a)
+            msgs = prompt.to_a
+            return nil if msgs.any? { |m| m.respond_to?(:content) && LLM::Function::Return === m.content }
+
+            user_msg = msgs.reverse_each.find { |m| m.respond_to?(:role) && m.role.to_s == "user" }
+            user_msg&.content.to_s
+          else
+            prompt.to_s
+          end
+        end
+      end
+
+      # ── ModelList ──────────────────────────────────────────────────
+
+      # Minimal object that quacks like provider.models so the REPL's
+      # fetch_models can call provider.models.all.select(&:chat?).
+      class ModelList
+        ModelEntry = Struct.new(:id, :chat?, keyword_init: true)
+
+        def initialize(names)
+          @entries = names.map { |n| ModelEntry.new(id: n, chat?: true) }
+        end
+
+        def all
+          @entries
+        end
+      end
+    end
+  end
+end

data/lib/brute/providers/shell_response.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Brute
+  module Providers
+    # Synthetic completion response returned by Brute::Providers::Shell.
+    #
+    # When +command+ is present, the response contains a single assistant
+    # message with a "shell" tool call. The orchestrator picks it up and
+    # executes Brute::Tools::Shell through the normal pipeline.
+    #
+    # When +command+ is nil (tool results round-trip), the response
+    # contains an empty assistant message with no tool calls, causing
+    # the orchestrator loop to exit.
+    #
+    class ShellResponse
+      def initialize(command: nil, model: "bash", tools: [])
+        @command    = command
+        @model_name = model
+        @tools      = tools || []
+      end
+
+      def messages
+        return [empty_assistant] if @command.nil?
+
+        call_id    = "shell_#{SecureRandom.hex(8)}"
+        tool_call  = LLM::Object.from(
+          id: call_id,
+          name: "shell",
+          arguments: { "command" => @command },
+        )
+        original = [{
+          "type"  => "tool_use",
+          "id"    => call_id,
+          "name"  => "shell",
+          "input" => { "command" => @command },
+        }]
+
+        [LLM::Message.new(:assistant, "", {
+          tool_calls: [tool_call],
+          original_tool_calls: original,
+          tools: @tools,
+        })]
+      end
+      alias_method :choices, :messages
+
+      def model
+        @model_name
+      end
+
+      def input_tokens
+        0
+      end
+
+      def output_tokens
+        0
+      end
+
+      def reasoning_tokens
+        0
+      end
+
+      def total_tokens
+        0
+      end
+
+      def content
+        messages.find(&:assistant?)&.content
+      end
+
+      def content!
+        LLM.json.load(content)
+      end
+
+      def reasoning_content
+        nil
+      end
+
+      def usage
+        LLM::Usage.new(
+          input_tokens: 0,
+          output_tokens: 0,
+          reasoning_tokens: 0,
+          total_tokens: 0,
+        )
+      end
+
+      # Contract must be included AFTER method definitions —
+      # LLM::Contract checks that all required methods exist at include time.
+      include LLM::Contract::Completion
+
+      private
+
+      def empty_assistant
+        LLM::Message.new(:assistant, "")
+      end
+    end
+  end
+end

data/lib/brute/system_prompt.rb

@@ -26,9 +26,17 @@ module Brute
     # prepare-time, then appends conditional sections based on runtime state.
     def self.default
       build do |prompt, ctx|
-        # Provider-specific base stack
+        # Provider-specific base stack.
+        # For gateway providers (opencode_zen, opencode_go), infer the
+        # upstream model family from the model name so we use the most
+        # appropriate prompt stack (e.g., anthropic stack for claude-*).
         provider = ctx[:provider_name].to_s
-        STACKS.fetch(provider, STACKS["default"]).each do |mod|
+        stack_key = if provider.start_with?("opencode")
+                      infer_stack_from_model(ctx[:model_name].to_s)
+                    else
+                      provider
+                    end
+        STACKS.fetch(stack_key, STACKS["default"]).each do |mod|
           prompt << mod.call(ctx)
         end
 
@@ -114,6 +122,21 @@ module Brute
       ],
     }.freeze
 
+    # Infer the best prompt stack from a model name.
+    # Used for gateway providers that route to multiple upstream model families.
+    def self.infer_stack_from_model(model_name)
+      case model_name
+      when /\bclaude\b/i, /\bbig.?pickle\b/i
+        "anthropic"
+      when /\bgpt\b/i, /\bo[134]\b/i, /\bcodex\b/i
+        "openai"
+      when /\bgemini\b/i, /\bgemma\b/i
+        "google"
+      else
+        "default"
+      end
+    end
+
     def initialize(block)
       @block = block
     end

data/lib/brute/tools/delegate.rb

@@ -28,7 +28,31 @@ module Brute
           rounds += 1
         end
 
-        {result: res.content}
+        {result: extract_content(res, sub)}
+      end
+
+      private
+
+      # Safely extract text content from the sub-agent response.
+      #
+      # When the LLM returns only tool calls (no text content block),
+      # res.content raises NoMethodError because the response adapter's
+      # choices array is empty (it only maps over text blocks), or
+      # returns nil when the response has no text. Fall back to the
+      # last assistant text in the conversation history.
+      def extract_content(res, context)
+        text = begin
+          res.content
+        rescue NoMethodError
+          nil
+        end
+        return text if text.is_a?(::String) && !text.empty?
+
+        last_assistant = context.messages.to_a
+          .select(&:assistant?)
+          .reverse
+          .find { |m| m.content.is_a?(::String) && !m.content.empty? }
+        last_assistant&.content || "(sub-agent completed but produced no text response)"
       end
     end
   end

data/lib/brute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brute
-  VERSION = "0.1.9"
+  VERSION = "0.3.0"
 end

data/lib/brute.rb

@@ -90,6 +90,13 @@ require_relative 'brute/tools/todo_read'
 require_relative 'brute/tools/delegate'
 require_relative 'brute/tools/question'
 
+# Providers
+require_relative 'brute/providers/shell_response'
+require_relative 'brute/providers/shell'
+require_relative 'brute/providers/models_dev'
+require_relative 'brute/providers/opencode_zen'
+require_relative 'brute/providers/opencode_go'
+
 # Orchestrator (depends on tools, middleware, and infrastructure)
 require_relative 'brute/orchestrator'
 
@@ -139,10 +146,14 @@ module Brute
     'google' => ->(key) { LLM.google(key: key) },
     'deepseek' => ->(key) { LLM.deepseek(key: key) },
     'ollama' => ->(key) { LLM.ollama(key: key) },
-    'xai' => ->(key) { LLM.xai(key: key) }
+    'xai' => ->(key) { LLM.xai(key: key) },
+    'opencode_zen' => ->(key) { LLM::OpencodeZen.new(key: key) },
+    'opencode_go' => ->(key) { LLM::OpencodeGo.new(key: key) },
+    'shell' => ->(_key) { Providers::Shell.new },
   }.freeze
 
   # List provider names that have API keys configured in the environment.
+  # The shell provider is always available (no key needed).
   def self.configured_providers
     PROVIDERS.keys.select { |name| api_key_for(name) }
   end
@@ -161,6 +172,14 @@ module Brute
 
   # Look up the API key for a given provider name.
   def self.api_key_for(name)
+    # Shell provider needs no key.
+    return "none" if name == "shell"
+
+    # OpenCode providers: check OPENCODE_API_KEY, fall back to "public" for anonymous access.
+    if name == "opencode_zen" || name == "opencode_go"
+      return ENV["OPENCODE_API_KEY"] || "public"
+    end
+
     # Explicit generic key always works
     return ENV["LLM_API_KEY"] if ENV["LLM_API_KEY"]
 
@@ -178,6 +197,7 @@ module Brute
   #   2. ANTHROPIC_API_KEY (implicit: provider = anthropic)
   #   3. OPENAI_API_KEY   (implicit: provider = openai)
   #   4. GOOGLE_API_KEY   (implicit: provider = google)
+  #   5. OPENCODE_API_KEY  (implicit: provider = opencode_zen)
   #
   # Returns nil if no key is found. Error is deferred to Orchestrator#run.
   def self.resolve_provider
@@ -193,6 +213,9 @@ module Brute
     elsif ENV['GOOGLE_API_KEY']
       key = ENV['GOOGLE_API_KEY']
       name = 'google'
+    elsif ENV['OPENCODE_API_KEY']
+      key = ENV['OPENCODE_API_KEY']
+      name = 'opencode_zen'
     else
       return nil
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.3.0
 platform: ruby
 authors:
 - Brute Contributors
 bindir: bin
 cert_chain: []
-date: 1980-01-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -155,6 +155,11 @@ files:
 - lib/brute/prompts/text/tool_usage/google.txt
 - lib/brute/prompts/tone_and_style.rb
 - lib/brute/prompts/tool_usage.rb
+- lib/brute/providers/models_dev.rb
+- lib/brute/providers/opencode_go.rb
+- lib/brute/providers/opencode_zen.rb
+- lib/brute/providers/shell.rb
+- lib/brute/providers/shell_response.rb
 - lib/brute/session.rb
 - lib/brute/skill.rb
 - lib/brute/snapshot_store.rb