brute 3.2.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd242366b30cf384cb0326b8fa006f43883f1cf117d410b830288164a4d13582
-  data.tar.gz: 3d4973d9a6fa69e6fd04d464343d8d2d85fb8455236e9d03f32df17888182e1f
+  metadata.gz: 65f8fa383e8c2d5793cc4ec00023ee6d2117e75535a81676617232b94748f154
+  data.tar.gz: 88f3794d39b79c3c7c03c96f54383fa8647850be1cfc77ae8877fb6ea42aa365
 SHA512:
-  metadata.gz: f0659b341410c0cb87db3cefe95e3c8c99bbf5ea9c88ba974d6b8f1adc5835919e256a577435748d652e1e229b30fb6cbaac321d297688fc9fac0812a028e369
-  data.tar.gz: 5f693c1c49b4bd74ce901e78bcd459f04c6316fe044bb871a04142b09154cb04767a1166dd64d02d2332fb9fac63572a6d13b28fbef40520c18737b1a11f98f4
+  metadata.gz: 57b849d89d406b624fe26dcbc93aa84af2f9b90b12160fb57608938ec53fd7109c87aa3d2c1357620c78f88b9702f797ff106432840a5e4ccaca343f49e7035a
+  data.tar.gz: d73709348a3f205f034389e86950a5ce171d0fd0bf62a9c9e84ad587d3ac322aad211b94d059a93b9b19e16a0c1b6211baebd7f274b88435c1cf61a9a6373007

data/lib/brute/hooks.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  # Pub/sub registry for agent lifecycle hooks, subscribed on the builder:
+  #
+  #   Brute.agent
+  #     .use(Brute::Middleware::MaxIterations)
+  #     .run(->(env) { env[:messages].assistant("done") })
+  #     .on(:before_llm) { |env| ... }
+  #     .on(:approve_tool) { |call| call[:name] != "exec" }
+  #
+  # Emission points and payloads:
+  #
+  #   :turn_start, :turn_end  → the turn env (AgentPipeline#start; turn_end
+  #                             fires from an ensure, so it also fires on error)
+  #   :before_llm, :after_llm → the turn env, around every LLM call
+  #   :before_tool            → call env {name:, arguments:, result:, events:,
+  #                             metadata:, turn_env:} — mutate :arguments to
+  #                             rewrite the call, or set :result (or return a
+  #                             value) to skip execution entirely ("respond")
+  #   :approve_tool           → call env — a false return denies the call; a
+  #                             String return denies it with that message
+  #   :after_tool             → call env — mutate :result
+  #
+  # Subscribers run inline (tool events may fire from parallel threads).
+  # Exceptions propagate to the caller — layers that want fail-open semantics
+  # rescue in their own subscriber.
+  class Hooks
+    EVENTS = %i[turn_start turn_end before_llm after_llm before_tool approve_tool after_tool].freeze
+
+    def initialize
+      @subscribers = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def on(event, &block)
+      @subscribers[event.to_sym] << block
+      self
+    end
+
+    # Fire an event; returns every subscriber's raw result (nils and false
+    # included — the deny contract distinguishes them).
+    def emit(event, payload)
+      @subscribers[event.to_sym].map { |subscriber| subscriber.call(payload) }
+    end
+
+    def any?(event) = @subscribers[event.to_sym].any?
+  end
+end
+
+__END__
+
+describe "brute/hooks" do
+  it "emits to subscribers in registration order" do
+    hooks = Brute::Hooks.new
+    seen = []
+    hooks.on(:before_llm) { |p| seen << "a#{p}" }
+    hooks.on(:before_llm) { |p| seen << "b#{p}" }
+    hooks.emit(:before_llm, 1)
+    seen.should == ["a1", "b1"]
+  end
+
+  it "returns raw results, false included (deny contract)" do
+    hooks = Brute::Hooks.new
+    hooks.on(:approve_tool) { |_call| false }
+    hooks.emit(:approve_tool, {}).should == [false]
+  end
+
+  it "answers any? and stays chainable" do
+    hooks = Brute::Hooks.new
+    hooks.any?(:turn_start).should.be.false
+    hooks.on(:turn_start) { nil }.should.equal?(hooks)
+    hooks.any?(:turn_start).should.be.true
+  end
+end

data/lib/brute/middleware/025_skills.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+
+module Brute
+  module Middleware
+    # Loads skill objects into the agent context.
+    #
+    # Skills are handed in as objects — discovery is the caller's job:
+    #
+    #   skills = Brute::Skill.all(cwd: Dir.pwd)
+    #   agent
+    #     .use(Brute::Middleware::Skills, skills: skills)
+    #     .use(Brute::Middleware::SystemPrompt)
+    #
+    # Per turn:
+    #   1. env[:skills] = the objects, for downstream middleware, tools, and
+    #      the terminal app (prime-agent's resourceLoader.getSkills() analogue)
+    #   2. env[:metadata][:skills] = the same objects, so
+    #      Middleware::SystemPrompt merges them into the prompt ctx and
+    #      Brute::Prompts::Skills renders the <available_skills> section
+    #
+    # Place it before Middleware::SystemPrompt in the stack. It never touches
+    # env[:messages] itself.
+    class Skills
+      def initialize(app, skills: [])
+        @app = app
+        @skills = skills
+      end
+
+      def call(env)
+        env[:skills] = @skills
+        env[:metadata] ||= {}
+        env[:metadata][:skills] ||= @skills
+
+        @app.call(env)
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/middleware/025_skills" do
+  def skill(name)
+    Brute::Skill.new(name: name, description: "x", file_path: "/x/#{name}/SKILL.md")
+  end
+
+  def build_middleware(skills: [], &inner)
+    Brute::Middleware::Skills.new(inner || ->(env) { env }, skills: skills)
+  end
+
+  it "stashes skill objects in env[:skills]" do
+    skills = [skill("debugging")]
+    env = { messages: Brute.log, metadata: {} }
+
+    build_middleware(skills: skills).call(env)
+
+    env[:skills].should == skills
+  end
+
+  it "mirrors skills into env[:metadata] for the prompt layer" do
+    skills = [skill("debugging")]
+    env = { messages: Brute.log }
+
+    build_middleware(skills: skills).call(env)
+
+    env[:metadata][:skills].should == skills
+  end
+
+  it "does not clobber an explicit metadata[:skills]" do
+    explicit = [skill("explicit")]
+    env = { messages: Brute.log, metadata: { skills: explicit } }
+
+    build_middleware(skills: [skill("other")]).call(env)
+
+    env[:metadata][:skills].should == explicit
+    env[:skills].map(&:name).should == ["other"]
+  end
+
+  it "defaults to an empty list and passes control down the chain" do
+    called = false
+    env = { messages: Brute.log }
+
+    build_middleware { |e| called = true }.call(env)
+
+    env[:skills].should == []
+    called.should.be.true
+  end
+end

data/lib/brute/middleware/070_tool_pipeline.rb

@@ -48,23 +48,56 @@ module Brute
                 name = tool_call.name.to_sym
                 args = tool_call.arguments
 
-                available_tools[name].call(args).then do |result|
-
-                  # Coerce to String so Hash results (e.g. Shell's
-                  # {stdout:, stderr:, exit_code:}) serialize predictably.
-                  if result.is_a?(String)
-                    content = result
-                  else
-                    content = result.to_s
+                # Lifecycle hooks (Brute::Hooks): before_tool may rewrite
+                # :arguments or short-circuit with a :result; approve_tool
+                # denies on a false (or String) return; after_tool may
+                # rewrite :result.
+                call_env = {
+                  name:      name.to_s,
+                  arguments: args,
+                  result:    nil,
+                  events:    env[:events],
+                  metadata:  {},
+                  turn_env:  env,
+                }
+                if (hooks = env[:hooks])
+                  responses = hooks.emit(:before_tool, call_env).compact
+                  call_env[:result] = responses.last if call_env[:result].nil? && !responses.empty?
+
+                  if call_env[:result].nil?
+                    denial = hooks.emit(:approve_tool, call_env).find { |r| r == false || r.is_a?(String) }
+                    unless denial.nil?
+                      call_env[:result] = denial.is_a?(String) ? denial : %(Tool call to "#{name}" was denied.)
+                    end
                   end
+                end
 
-                  # Universal truncation safety net — skip if already truncated
-                  unless Brute::Truncation.already_truncated?(content)
-                    content = Brute::Truncation.truncate(content)
-                  end
+                result = if call_env[:result].nil?
+                           available_tools[name].call(call_env[:arguments])
+                         else
+                           call_env[:result]
+                         end
+
+                if (hooks = env[:hooks])
+                  call_env[:result] = result
+                  hooks.emit(:after_tool, call_env)
+                  result = call_env[:result]
+                end
+
+                # Coerce to String so Hash results (e.g. Shell's
+                # {stdout:, stderr:, exit_code:}) serialize predictably.
+                if result.is_a?(String)
+                  content = result
+                else
+                  content = result.to_s
+                end
 
-                  results << [tool_call, content]
+                # Universal truncation safety net — skip if already truncated
+                unless Brute::Truncation.already_truncated?(content)
+                  content = Brute::Truncation.truncate(content)
                 end
+
+                results << [tool_call, content]
               rescue => e
                 # Capture the error as a tool result so the LLM can see it
                 # and reason about the failure, rather than crashing the
@@ -141,6 +174,70 @@ describe "brute/middleware/070_tool_pipeline" do
     seen.should == [tool]
   end
 
+  # --- lifecycle hooks (Brute::Hooks) ---
+
+  def hook_env(hooks)
+    { messages: Brute.log, events: [], hooks: hooks }
+  end
+
+  it "before_tool may rewrite arguments and short-circuit with a result" do
+    tool = { name: "echo", description: "", execute: ->(text:) { "ran:#{text}" } }
+    inner = ->(env) do
+      env[:messages] << Brute::Message.new(role: :assistant, content: "",
+        tool_calls: [{ id: "tc1", name: "echo", arguments: { "text" => "orig" } }])
+    end
+    hooks = Brute::Hooks.new
+    hooks.on(:before_tool) { |call| call[:arguments] = { text: "rewritten" }; nil }
+    mw = Brute::Middleware::ToolPipeline.new(inner, tools: [tool])
+    env = hook_env(hooks)
+    env[:messages].user("hi")
+    mw.call(env)
+    env[:messages].last.content.should == "ran:rewritten"
+
+    hooks2 = Brute::Hooks.new
+    hooks2.on(:before_tool) { |_call| "canned" }
+    mw2 = Brute::Middleware::ToolPipeline.new(inner, tools: [tool])
+    env2 = hook_env(hooks2)
+    env2[:messages].user("hi")
+    mw2.call(env2)
+    env2[:messages].last.content.should == "canned" # never executed
+  end
+
+  it "approve_tool denies on false (generic message) or String (custom)" do
+    tool = { name: "exec", description: "", execute: ->(**) { "ran" } }
+    inner = ->(env) do
+      env[:messages] << Brute::Message.new(role: :assistant, content: "",
+        tool_calls: [{ id: "tc1", name: "exec", arguments: {} }])
+    end
+    hooks = Brute::Hooks.new
+    hooks.on(:approve_tool) { |_call| false }
+    env = hook_env(hooks)
+    env[:messages].user("hi")
+    Brute::Middleware::ToolPipeline.new(inner, tools: [tool]).call(env)
+    env[:messages].last.content.should == %(Tool call to "exec" was denied.)
+
+    hooks2 = Brute::Hooks.new
+    hooks2.on(:approve_tool) { |_call| "denied by policy" }
+    env2 = hook_env(hooks2)
+    env2[:messages].user("hi")
+    Brute::Middleware::ToolPipeline.new(inner, tools: [tool]).call(env2)
+    env2[:messages].last.content.should == "denied by policy"
+  end
+
+  it "after_tool may rewrite the result" do
+    tool = { name: "echo", description: "", execute: ->(**) { "raw" } }
+    inner = ->(env) do
+      env[:messages] << Brute::Message.new(role: :assistant, content: "",
+        tool_calls: [{ id: "tc1", name: "echo", arguments: {} }])
+    end
+    hooks = Brute::Hooks.new
+    hooks.on(:after_tool) { |call| call[:result] = "rewrote(#{call[:result]})" }
+    env = hook_env(hooks)
+    env[:messages].user("hi")
+    Brute::Middleware::ToolPipeline.new(inner, tools: [tool]).call(env)
+    env[:messages].last.content.should == "rewrote(raw)"
+  end
+
   # --- Universal output truncation ---
 
   it "truncates large tool results via Truncation" do

data/lib/brute/middleware/open_router.rb

@@ -16,11 +16,20 @@ module Brute
         end
 
         def call(env)
+          env[:hooks]&.emit(:before_llm, env)
+
           messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
 
           ::OpenRouter::Client.new(**@config).then do |client|
             client.complete(messages, @options).then do |response|
 
+              # Expose the provider's usage for downstream accounting
+              # middleware (goal budgets, autonomous limits, compaction
+              # thresholds, usage attribution) — additive metadata only.
+              if response.respond_to?(:usage) && response.usage
+                (env[:metadata] ||= {})[:last_llm_usage] = response.usage
+              end
+
               # OpenRouter in fact only returns a single message...
               # https://github.com/estiens/open_router_enhanced/blob/main/lib/open_router/response.rb
               Brute::MessageTransport::OpenRouter.wrap_each(response) do |message|
@@ -29,9 +38,70 @@ module Brute
             end
           end
 
+          env[:hooks]&.emit(:after_llm, env)
           env
         end
       end
     end
   end
 end
+
+__END__
+
+describe "brute/middleware/open_router" do
+  require "brute/messages"
+
+  # The repo suite has no open_router gem; stub the two constants the
+  # middleware touches (the transport wraps duck-typed responses fine).
+  begin
+    require "open_router"
+  rescue LoadError
+    module OpenRouter
+      CompletionOptions = Class.new { def initialize(**_opts); end }
+      Client = Class.new
+    end
+  end
+
+  FakeUsageResponse = Struct.new(:usage) do
+    def choices
+      [{ "message" => { "role" => "assistant", "content" => "hello" } }]
+    end
+  end
+
+  it "records the provider usage into env metadata and appends the message" do
+    response = FakeUsageResponse.new({ "prompt_tokens" => 10, "completion_tokens" => 5, "total_tokens" => 15 })
+    fake_client = Object.new
+    fake_client.define_singleton_method(:complete) { |_messages, _options| response }
+    original = OpenRouter::Client.method(:new)
+    OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
+    begin
+      middleware = Brute::Middleware::OpenRouter::Completion.new(->(env) { env })
+      env = { messages: Brute.log }
+      env[:messages].user("hi")
+      middleware.call(env)
+
+      env[:messages].last.role.should == :assistant
+      env[:metadata][:last_llm_usage]["total_tokens"].should == 15
+    ensure
+      OpenRouter::Client.define_singleton_method(:new, original)
+    end
+  end
+
+  it "leaves metadata alone when the response has no usage" do
+    response = FakeUsageResponse.new(nil)
+    fake_client = Object.new
+    fake_client.define_singleton_method(:complete) { |_messages, _options| response }
+    original = OpenRouter::Client.method(:new)
+    OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
+    begin
+      middleware = Brute::Middleware::OpenRouter::Completion.new(->(env) { env })
+      env = { messages: Brute.log }
+      env[:messages].user("hi")
+      middleware.call(env)
+
+      env.key?(:metadata).should.be.false
+    ensure
+      OpenRouter::Client.define_singleton_method(:new, original)
+    end
+  end
+end

data/lib/brute/prompt_template.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "brute"
+require "erb"
+
+module Brute
+  # An ERB-backed system-prompt object for Middleware::SystemPrompt — the
+  # open alternative to Brute::SystemPrompt's built-in section stacks. You
+  # bring a template and named values; every keyword becomes an attr_accessor
+  # and an ERB local of the same name:
+  #
+  #   prompt = Brute::PromptTemplate.new(
+  #     "prompt.erb",
+  #     identity: "You are Pico.",
+  #     memory:   -> { File.read("memory/MEMORY.md") },   # zero-arity proc
+  #     env:      ->(ctx) { Brute::Prompts::Environment.call(ctx) },
+  #   )
+  #   prompt.identity = "You are Brute."   # attr_accessor per section
+  #
+  #   Brute.agent.use(Brute::Middleware::SystemPrompt, system_prompt: prompt)
+  #
+  # Proc values are re-evaluated on every prepare (zero-arity procs are
+  # called with no arguments, others receive the turn ctx), and a template
+  # path is re-read from disk each time — so file-backed sections hot-reload
+  # between turns. The prepare(ctx) -> Result(#empty?, #to_s) contract is
+  # what Middleware::SystemPrompt expects.
+  class PromptTemplate
+    Result = Struct.new(:text) do
+      def to_s = text.to_s
+      def empty? = text.to_s.strip.empty?
+    end
+
+    def initialize(template, **sections)
+      @template = template
+      @section_keys = []
+      sections.each { |key, value| self[key] = value }
+    end
+
+    def [](key)
+      public_send(key)
+    end
+
+    def []=(key, value)
+      unless respond_to?(key)
+        singleton_class.class_eval { attr_accessor key }
+        @section_keys << key
+      end
+      public_send("#{key}=", value)
+    end
+
+    # Called once per turn by Middleware::SystemPrompt.
+    def prepare(ctx = {})
+      Result.new(render(locals(ctx)))
+    end
+
+    private
+
+    def locals(ctx)
+      @section_keys.to_h do |key|
+        value = self[key]
+        resolved = value.is_a?(Proc) ? (value.arity.zero? ? value.call : value.call(ctx)) : value
+        [key, resolved]
+      end.merge(ctx: ctx)
+    end
+
+    def render(values)
+      context = binding
+      values.each { |key, value| context.local_variable_set(key, value) }
+      ERB.new(template_source, trim_mode: "-").result(context)
+    end
+
+    # A path that exists is re-read every time; anything else is treated as
+    # an inline ERB source string.
+    def template_source
+      File.exist?(@template.to_s) ? File.read(@template) : @template.to_s
+    end
+  end
+end
+
+__END__
+
+describe "brute/prompt_template" do
+  require "tmpdir"
+
+  it "renders keyword sections as ERB locals" do
+    prompt = Brute::PromptTemplate.new("Hello <%= name %>, <%= mood %> today.", name: "Pico", mood: "happy")
+    prompt.prepare.to_s.should == "Hello Pico, happy today."
+  end
+
+  it "exposes an attr_accessor per section" do
+    prompt = Brute::PromptTemplate.new("<%= name %>", name: "Pico")
+    prompt.name.should == "Pico"
+    prompt.name = "Brute"
+    prompt.prepare.to_s.should == "Brute"
+  end
+
+  it "re-evaluates zero-arity procs on every prepare" do
+    count = 0
+    prompt = Brute::PromptTemplate.new("<%= tick %>", tick: -> { count += 1 })
+    prompt.prepare.to_s.should == "1"
+    prompt.prepare.to_s.should == "2"
+  end
+
+  it "passes ctx to procs that take an argument" do
+    prompt = Brute::PromptTemplate.new("<%= who %>", who: ->(ctx) { ctx[:agent] })
+    prompt.prepare(agent: "pico").to_s.should == "pico"
+  end
+
+  it "re-reads a template file on every prepare" do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, "prompt.erb")
+      File.write(path, "v1 <%= x %>")
+      prompt = Brute::PromptTemplate.new(path, x: "a")
+      prompt.prepare.to_s.should == "v1 a"
+      File.write(path, "v2 <%= x %>")
+      prompt.prepare.to_s.should == "v2 a"
+    end
+  end
+
+  it "honours the Result contract (empty?/to_s)" do
+    Brute::PromptTemplate.new("").prepare.empty?.should.be.true
+    Brute::PromptTemplate.new("hi").prepare.empty?.should.be.false
+  end
+end

data/lib/brute/prompts/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "erb"
+
 require "bundler/setup"
 require "brute"
 
@@ -22,5 +24,108 @@ module Brute
       path = File.join(TEXT_DIR, "agents", "#{name}.txt")
       File.exist?(path) ? File.read(path) : nil
     end
+
+    # Template context handed to ERB templates. Context-hash keys become
+    # methods (<%= skills %>, <%= cwd %>), plus view helpers like +h+.
+    class Context
+      def initialize(ctx)
+        @ctx = ctx
+      end
+
+      def method_missing(name, *args)
+        return @ctx[name] if args.empty? && @ctx.key?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @ctx.key?(name) || super
+      end
+
+      # XML-escape a value for prompt markup (& < > " ').
+      def escape_xml(value)
+        value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+           .gsub('"', "&quot;").gsub("'", "&apos;")
+      end
+      alias h escape_xml
+
+      def get_binding
+        binding
+      end
+    end
+
+    # Compiled templates, keyed by absolute path. Compilation is idempotent,
+    # so a racy double-assign under Async is harmless.
+    TEMPLATES = {}
+
+    # Resolve and render text/<section>/<provider>.erb, falling back to
+    # default.erb, then to the legacy plain .txt files. Returns nil when the
+    # section has no template or text file at all.
+    #
+    # Templates are ERB: arbitrary Ruby. Only ship templates with the gem or
+    # load them from paths you trust.
+    def self.render(section, ctx)
+      provider = ctx[:provider_name].to_s
+      path = [provider, "default"]
+             .map { |variant| File.join(TEXT_DIR, section, "#{variant}.erb") }
+             .find { |candidate| File.exist?(candidate) }
+      return read(section, provider) unless path
+
+      erb = TEMPLATES[path] ||= ERB.new(File.read(path), trim_mode: "-")
+      erb.result(Context.new(ctx).get_binding)
+    end
+  end
+end
+
+__END__
+
+describe "brute/prompts/base" do
+  require "tmpdir"
+  require "fileutils"
+
+  it "interpolates ctx keys as methods" do
+    ctx = Brute::Prompts::Context.new(name: "debugging")
+    template = ERB.new("<%= name %>")
+    template.result(ctx.get_binding).should == "debugging"
+  end
+
+  it "escapes XML via h" do
+    ctx = Brute::Prompts::Context.new({})
+    ctx.h(%q{a<b>&"c'}).should == "a&lt;b&gt;&amp;&quot;c&apos;"
+  end
+
+  it "renders a section template with provider fallback" do
+    section = "base_test_render"
+    dir = File.join(Brute::Prompts::TEXT_DIR, section)
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, "default.erb"), "hello <%= thing %>")
+    begin
+      Brute::Prompts.render(section, provider_name: "nope", thing: "world").should == "hello world"
+    ensure
+      FileUtils.remove_entry(dir)
+    end
+  end
+
+  it "prefers a provider-specific template over default" do
+    section = "base_test_provider"
+    dir = File.join(Brute::Prompts::TEXT_DIR, section)
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, "default.erb"), "default")
+    File.write(File.join(dir, "anthropic.erb"), "anthropic")
+    begin
+      Brute::Prompts.render(section, provider_name: "anthropic").should == "anthropic"
+      Brute::Prompts.render(section, provider_name: "openai").should == "default"
+    ensure
+      FileUtils.remove_entry(dir)
+    end
+  end
+
+  it "falls back to a legacy plain text file when no template exists" do
+    Brute::Prompts.render("identity", provider_name: "anthropic").should ==
+      Brute::Prompts.read("identity", "anthropic")
+  end
+
+  it "returns nil for a section with no template or text file" do
+    Brute::Prompts.render("no_such_section_anywhere", provider_name: "x").should.be.nil
   end
 end

data/lib/brute/prompts/skills.rb

@@ -5,22 +5,20 @@ require "brute"
 
 module Brute
   module Prompts
+    # The <available_skills> system-prompt section.
+    #
+    # Uses skill objects from ctx[:skills] when present (handed in via
+    # Brute::Middleware::Skills -> env[:metadata][:skills]); falls back to
+    # scanning from ctx[:cwd] so the default stacks keep working unwired.
+    # Skills with disable_model_invocation? are loaded but hidden here.
+    # Returns nil when no skills are visible, dropping the section entirely.
     module Skills
       def self.call(ctx)
-        cwd = ctx[:cwd] || Dir.pwd
-        skills = Brute::Skill.all(cwd: cwd)
-        return nil if skills.empty?
+        skills = ctx[:skills] || Brute::Skill.all(cwd: ctx[:cwd] || Dir.pwd)
+        visible = skills.reject(&:disable_model_invocation?)
+        return nil if visible.empty?
 
-        listing = Brute::Skill.fmt(skills)
-
-        <<~TXT
-          Skills provide specialized instructions and workflows for specific tasks.
-          Use the skill tool to load a skill when a task matches its description. The tool
-          returns the skill's full instructions plus a base directory whose bundled files
-          (scripts, references, assets) you can read or run by relative path.
-
-          #{listing}
-        TXT
+        Prompts.render("skills", ctx.merge(skills: visible))
       end
     end
   end
@@ -31,9 +29,49 @@ __END__
 describe "brute/prompts/skills" do
   require "tmpdir"
 
+  def skill(name, description: "Does things", file_path: "/x/#{name}/SKILL.md", hidden: false)
+    Brute::Skill.new(
+      name: name, description: description, file_path: file_path,
+      disable_model_invocation: hidden,
+    )
+  end
+
   it "returns nil when no skills are found" do
     Dir.mktmpdir do |dir|
       Brute::Prompts::Skills.call(cwd: dir).should.be.nil
     end
   end
+
+  it "renders skill objects passed through ctx" do
+    out = Brute::Prompts::Skills.call(skills: [skill("debugging", description: "Debug things")])
+    out.should.include("<name>debugging</name>")
+    out.should.include("<description>Debug things</description>")
+    out.should.include("<location>/x/debugging/SKILL.md</location>")
+  end
+
+  it "prefers ctx[:skills] over scanning, even when empty" do
+    Dir.mktmpdir do |dir|
+      skill_dir = File.join(dir, ".brute", "skills", "debugging")
+      FileUtils.mkdir_p(skill_dir)
+      File.write(File.join(skill_dir, "SKILL.md"), "---\nname: debugging\ndescription: x\n---\n\nBody\n")
+
+      Brute::Prompts::Skills.call(cwd: dir, skills: []).should.be.nil
+      Brute::Prompts::Skills.call(cwd: dir).should.include("debugging")
+    end
+  end
+
+  it "hides disable-model-invocation skills from the listing" do
+    out = Brute::Prompts::Skills.call(skills: [skill("shown"), skill("hidden", hidden: true)])
+    out.should.include("shown")
+    out.should.not.include("hidden")
+  end
+
+  it "returns nil when every skill is hidden" do
+    Brute::Prompts::Skills.call(skills: [skill("hidden", hidden: true)]).should.be.nil
+  end
+
+  it "xml-escapes skill fields" do
+    out = Brute::Prompts::Skills.call(skills: [skill("debugging", description: %q{a<b>&"c'})])
+    out.should.include("a&lt;b&gt;&amp;&quot;c&apos;")
+  end
 end

data/lib/brute/prompts/text/skills/default.erb

@@ -0,0 +1,14 @@
+Skills provide specialized instructions and workflows for specific tasks.
+When a task matches a skill's description, read the file at its location for the
+full instructions. Relative paths in a skill resolve against its directory (the
+parent of its SKILL.md).
+
+<available_skills>
+<% skills.each do |skill| -%>
+  <skill>
+    <name><%= h skill.name %></name>
+    <description><%= h skill.description %></description>
+    <location><%= h skill.file_path %></location>
+  </skill>
+<% end -%>
+</available_skills>

data/lib/brute/skill.rb

@@ -6,7 +6,7 @@ require "bundler/setup"
 require "brute"
 
 module Brute
-  # Discovers, validates, and loads SKILL.md files from standard directories.
+  # A single skill: metadata plus the address of its SKILL.md on disk.
   #
   # A skill is a directory containing a SKILL.md markdown file with YAML
   # frontmatter:
@@ -18,71 +18,60 @@ module Brute
   #
   #   When debugging, follow these steps...
   #
-  # Skills are scanned from (in order):
-  #   1. .brute/skills/**/SKILL.md   (project-local)
-  #   2. ~/.config/brute/skills/**/SKILL.md (global)
+  # The object is a value object — it carries the parsed frontmatter, the
+  # body, and the file location, nothing else. Modeled on prime-agent's
+  # BaseSkill (packages/coding-agent/src/core/skills.ts).
   #
-  # Parsing and validation mirror the Agent Skills specification
-  # (https://agentskills.io/specification) and its reference validator
-  # (https://github.com/agentskills/agentskills/tree/main/skills-ref). A skill
-  # whose frontmatter violates a rule is skipped with a stderr warning naming
-  # the violated rule, never raised.
+  # Discovery is class-level and caller-side: Skill.all scans (in order)
+  #   1. <cwd>/.brute/skills/**/SKILL.md   (project-local, :project)
+  #   2. ~/.config/brute/skills/**/SKILL.md (global, :user)
+  #   3. explicit paths: (dirs or .md files, :path)
+  #
+  # First found wins on name collisions (with a stderr warning naming winner
+  # and loser), and the same file reached twice via symlinks is skipped.
   #
-  module Skill
-    Info = Struct.new(
-      :name, :description, :location, :content,
-      :license, :compatibility, :metadata, :allowed_tools,
-      keyword_init: true,
-    )
+  # Parsing and validation mirror the Agent Skills specification
+  # (https://agentskills.io/specification). A skill whose frontmatter violates
+  # a rule is skipped with a stderr warning naming the rule — never raised.
+  class Skill
+    attr_reader :name, :description, :file_path, :base_dir, :content,
+                :source, :license, :compatibility, :metadata, :allowed_tools
 
     FILENAME = "SKILL.md"
 
     # Frontmatter keys permitted by the spec. Anything else is a violation.
-    ALLOWED_FIELDS = %w[name description license allowed-tools metadata compatibility].freeze
+    ALLOWED_FIELDS = %w[name description license allowed-tools metadata compatibility disable-model-invocation].freeze
 
     MAX_NAME_LENGTH = 64
     MAX_DESCRIPTION_LENGTH = 1024
     MAX_COMPATIBILITY_LENGTH = 500
 
-    # Scan all skill directories and return an array of Info structs.
-    def self.all(cwd: Dir.pwd)
-      skills = {}
-
-      scan_dirs(cwd).each do |dir|
-        Dir.glob(File.join(dir, "**", FILENAME)).sort.each do |path|
-          info = load(path)
-          next unless info
-          # First found wins (project-local overrides global)
-          skills[info.name] ||= info
-        end
-      end
-
-      skills.values.sort_by(&:name)
+    def initialize(name:, description:, file_path:, content: nil, source: :path,
+                   license: nil, compatibility: nil, metadata: nil,
+                   allowed_tools: nil, disable_model_invocation: false)
+      @name = name
+      @description = description
+      @file_path = file_path
+      @base_dir = File.dirname(file_path)
+      @content = content
+      @source = source
+      @license = license
+      @compatibility = compatibility
+      @metadata = metadata
+      @allowed_tools = allowed_tools
+      @disable_model_invocation = disable_model_invocation
     end
 
-    # Get a single skill by name.
-    def self.get(name, cwd: Dir.pwd)
-      all(cwd: cwd).detect { |s| s.name == name }
-    end
+    # Hidden from the prompt listing (explicit invocation only), but still
+    # handed to the agent as an object.
+    def disable_model_invocation? = @disable_model_invocation
 
-    # Format skills as XML for the system prompt.
-    def self.fmt(skills)
-      return nil if skills.empty?
+    # Back-compat alias (Tools::SkillLoad era).
+    def location = file_path
 
-      lines = ["<available_skills>"]
-      skills.each do |skill|
-        lines << "  <skill>"
-        lines << "    <name>#{skill.name}</name>"
-        lines << "    <description>#{skill.description}</description>"
-        lines << "  </skill>"
-      end
-      lines << "</available_skills>"
-      lines.join("\n")
-    end
-
-    # Parse and validate a SKILL.md file into an Info struct.
+    # Parse and validate a SKILL.md file into a Skill.
     # Returns nil (with a stderr warning) if the file is invalid.
-    def self.load(path)
+    def self.load(path, source: :path)
       raw = File.read(path)
       frontmatter, content = parse_frontmatter(path, raw)
       return nil unless frontmatter
@@ -105,21 +94,86 @@ module Brute
         return nil
       end
 
-      Info.new(
+      new(
         name: frontmatter["name"].to_s.strip,
         description: frontmatter["description"].to_s.strip,
-        location: path,
+        file_path: path,
         content: content.to_s.strip,
+        source: source,
         license: frontmatter["license"]&.to_s,
         compatibility: frontmatter["compatibility"]&.to_s,
         metadata: frontmatter["metadata"],
         allowed_tools: parse_allowed_tools(frontmatter["allowed-tools"]),
+        disable_model_invocation: frontmatter["disable-model-invocation"] == true,
       )
     rescue => e
       warn "Failed to load skill #{path}: #{e.message}"
       nil
     end
 
+    # Scan all skill directories and return an array of Skills, sorted by name.
+    #
+    # Precedence is first-found-wins: project-local overrides global overrides
+    # explicit paths. Name collisions warn to stderr naming winner and loser;
+    # the same file reached via different symlinks is loaded only once.
+    def self.all(cwd: Dir.pwd, paths: [])
+      skills = {}
+      seen_files = {}
+
+      add = lambda do |path, source|
+        skill = load(path, source: source)
+        return unless skill
+
+        real = realpath(path)
+        return if seen_files[real]
+
+        if (winner = skills[skill.name])
+          warn "Skill name collision: '#{skill.name}' at #{path} ignored; " \
+               "already loaded from #{winner.file_path}"
+          return
+        end
+
+        seen_files[real] = true
+        skills[skill.name] = skill
+      end
+
+      project = File.join(cwd, ".brute", "skills")
+      glob(project) { |path| add.call(path, :project) }
+
+      global = File.join(Dir.home, ".config", "brute", "skills")
+      glob(global) { |path| add.call(path, :user) }
+
+      paths.each do |raw|
+        path = File.expand_path(raw.to_s.sub(/\A~(?=\/|\z)/, Dir.home))
+        if File.directory?(path)
+          glob(path) { |p| add.call(p, :path) }
+        elsif File.file?(path) && path.end_with?(".md")
+          add.call(path, :path)
+        else
+          warn "Skill path #{path} is not a directory or markdown file (ignored)"
+        end
+      end
+
+      skills.values.sort_by(&:name)
+    end
+
+    # Get a single skill by name through the same scan as .all.
+    def self.get(name, cwd: Dir.pwd, paths: [])
+      all(cwd: cwd, paths: paths).detect { |s| s.name == name }
+    end
+
+    def self.glob(dir, &block)
+      return unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "**", FILENAME)).sort.each(&block)
+    end
+
+    def self.realpath(path)
+      File.realpath(path)
+    rescue SystemCallError
+      path
+    end
+
     # Validate frontmatter against the spec. Returns an array of error strings
     # (empty means valid), each naming the violated rule.
     def self.validate(frontmatter, dir_name)
@@ -168,21 +222,6 @@ module Brute
       value.to_s.split(/\s+/).reject(&:empty?)
     end
 
-    # Directories to scan for skills, in priority order.
-    def self.scan_dirs(cwd)
-      dirs = []
-
-      # Project-local
-      project = File.join(cwd, ".brute", "skills")
-      dirs << project if File.directory?(project)
-
-      # Global
-      global = File.join(Dir.home, ".config", "brute", "skills")
-      dirs << global if File.directory?(global)
-
-      dirs
-    end
-
     # Split YAML frontmatter from markdown body.
     # Returns [hash, string] or [nil, nil].
     def self.parse_frontmatter(path, raw)
@@ -200,8 +239,8 @@ module Brute
       [nil, nil]
     end
 
-    private_class_method :scan_dirs, :parse_frontmatter,
-                         :validate, :validate_name, :validate_description, :parse_allowed_tools
+    private_class_method :glob, :realpath, :validate, :validate_name,
+                         :validate_description, :parse_allowed_tools, :parse_frontmatter
   end
 end
 
@@ -222,9 +261,19 @@ describe "brute/skill" do
   it "loads a valid skill" do
     Dir.mktmpdir do |root|
       path = make_skill_dir(root, "debugging", "name: debugging\ndescription: Debug things")
-      info = Brute::Skill.load(path)
-      info.name.should == "debugging"
-      info.description.should == "Debug things"
+      skill = Brute::Skill.load(path)
+      skill.name.should == "debugging"
+      skill.description.should == "Debug things"
+    end
+  end
+
+  it "exposes file_path, base_dir, and a location alias" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "debugging", "name: debugging\ndescription: x")
+      skill = Brute::Skill.load(path)
+      skill.file_path.should == path
+      skill.base_dir.should == File.dirname(path)
+      skill.location.should == path
     end
   end
 
@@ -266,9 +315,9 @@ describe "brute/skill" do
   it "loads a skill with an unexpected frontmatter field, dropping the extra" do
     Dir.mktmpdir do |root|
       path = make_skill_dir(root, "extra", "name: extra\ndescription: x\ntags: [a, b]")
-      info = Brute::Skill.load(path)
-      info.name.should == "extra"
-      info.respond_to?(:tags).should.be.false
+      skill = Brute::Skill.load(path)
+      skill.name.should == "extra"
+      skill.respond_to?(:tags).should.be.false
     end
   end
 
@@ -278,11 +327,25 @@ describe "brute/skill" do
         root, "full",
         "name: full\ndescription: x\nlicense: MIT\ncompatibility: claude\nallowed-tools: read shell\nmetadata:\n  team: core",
       )
-      info = Brute::Skill.load(path)
-      info.license.should == "MIT"
-      info.compatibility.should == "claude"
-      info.allowed_tools.should == %w[read shell]
-      info.metadata.should == { "team" => "core" }
+      skill = Brute::Skill.load(path)
+      skill.license.should == "MIT"
+      skill.compatibility.should == "claude"
+      skill.allowed_tools.should == %w[read shell]
+      skill.metadata.should == { "team" => "core" }
+    end
+  end
+
+  it "parses disable-model-invocation" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "hidden", "name: hidden\ndescription: x\ndisable-model-invocation: true")
+      Brute::Skill.load(path).disable_model_invocation?.should.be.true
+    end
+  end
+
+  it "defaults disable_model_invocation to false" do
+    Dir.mktmpdir do |root|
+      path = make_skill_dir(root, "shown", "name: shown\ndescription: x")
+      Brute::Skill.load(path).disable_model_invocation?.should.be.false
     end
   end
 
@@ -292,4 +355,72 @@ describe "brute/skill" do
       Brute::Skill.load(path).should.be.nil
     end
   end
+
+  it "tags skills with their source" do
+    Dir.mktmpdir do |root|
+      make_skill_dir(root, "debugging", "name: debugging\ndescription: x")
+      Brute::Skill.all(cwd: root).first.source.should == :project
+    end
+  end
+
+  def with_home(dir)
+    old = ENV["HOME"]
+    ENV["HOME"] = dir
+    yield
+  ensure
+    ENV["HOME"] = old
+  end
+
+  it "project-local skills override same-named global ones" do
+    Dir.mktmpdir do |project|
+      Dir.mktmpdir do |home|
+        make_skill_dir(project, "shared", "name: shared\ndescription: project variant")
+        global_dir = File.join(home, ".config", "brute", "skills", "shared")
+        FileUtils.mkdir_p(global_dir)
+        File.write(File.join(global_dir, "SKILL.md"), "---\nname: shared\ndescription: global variant\n---\n\nBody\n")
+
+        with_home(home) do
+          skills = Brute::Skill.all(cwd: project)
+          skills.size.should == 1
+          skills.first.description.should == "project variant"
+          skills.first.source.should == :project
+        end
+      end
+    end
+  end
+
+  it "loads skills from explicit paths" do
+    Dir.mktmpdir do |root|
+      dir = File.join(root, "elsewhere", "custom")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "SKILL.md"), "---\nname: custom\ndescription: explicit\n---\n\nBody\n")
+
+      skills = Brute::Skill.all(cwd: root, paths: [File.join(root, "elsewhere")])
+      skills.map(&:name).should == ["custom"]
+      skills.first.source.should == :path
+    end
+  end
+
+  it "expands ~ in explicit paths" do
+    Dir.mktmpdir do |home|
+      dir = File.join(home, "skills", "homey")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "SKILL.md"), "---\nname: homey\ndescription: x\n---\n\nBody\n")
+
+      with_home(home) do
+        skills = Brute::Skill.all(cwd: home, paths: ["~/skills"])
+        skills.map(&:name).should.include("homey")
+      end
+    end
+  end
+
+  it "loads the same file only once when reached via a symlink" do
+    Dir.mktmpdir do |root|
+      make_skill_dir(root, "debugging", "name: debugging\ndescription: x")
+      link = File.join(root, ".brute", "skills", "linked")
+      File.symlink(File.join(root, ".brute", "skills", "debugging"), link)
+
+      Brute::Skill.all(cwd: root).size.should == 1
+    end
+  end
 end

data/lib/brute/turn/agent_pipeline.rb

@@ -45,10 +45,15 @@ module Brute
           events:            events,
           metadata:          {},
           current_iteration: 1,
+          hooks:             hooks,
         }
-        env.tap do
+        hooks.emit(:turn_start, env)
+        begin
           build.call(env)
+        ensure
+          hooks.emit(:turn_end, env)
         end
+        env
       end
 
       private
@@ -119,6 +124,27 @@ describe "brute/turn/agent_pipeline" do
     agent.start("hi")[:messages].last.content.should == "from ru"
   end
 
+  it ".on chains off the builder and fires turn hooks around the turn" do
+    fired = []
+    agent = Brute.agent
+      .run(->(env) { env[:messages].assistant("done") })
+      .on(:turn_start) { |env| fired << [:start, env[:messages].last.content] }
+      .on(:turn_end) { |env| fired << [:end, env[:messages].last.content] }
+
+    env = agent.start("go")
+    env[:messages].last.content.should == "done"
+    fired.should == [[:start, "go"], [:end, "done"]]
+  end
+
+  it "fires turn_end on error (ensure)" do
+    fired = []
+    agent = Brute.agent
+      .run(->(_env) { raise "boom" })
+      .on(:turn_end) { |_env| fired << :end }
+
+    lambda { agent.start("go") }.should.raise(RuntimeError)
+    fired.should == [:end]
+  end
   it "use in a ru string wraps the terminal" do
     script = <<~RUBY
       use AgentStubMW

data/lib/brute/turn/pipeline.rb

@@ -19,6 +19,16 @@ module Brute
         #
         def use(...) = tap { super }
         def run(...) = tap { super }
+
+        # Subscribe a lifecycle hook (see Brute::Hooks):
+        #
+        #   Brute.agent
+        #     .use(MaxProfit)
+        #     .run(->(env) { ... })
+        #     .on(:before_llm) { |env| ... }
+        #     .on(:approve_tool) { |call| call[:name] != "exec" }
+        #
+        def on(...) = tap { hooks.on(...) }
       end
 
       include Chainable
@@ -40,6 +50,11 @@ module Brute
       # when `run` was never called.
       alias_method :build, :to_app
 
+      # The lifecycle-hook registry for this pipeline (see Brute::Hooks).
+      def hooks
+        @hooks ||= Brute::Hooks.new
+      end
+
       # Default null sink for env[:events] — swallows anything pushed to it.
       class NullSink
         def <<(_event); self; end

data/lib/brute/version.rb

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

data/lib/brute/version.rb.erb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Brute
+  VERSION = "<%= version %>"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brute
 version: !ruby/object:Gem::Version
-  version: 3.2.2
+  version: 4.0.0
 platform: ruby
 authors:
 - Brute Contributors
@@ -173,6 +173,7 @@ files:
 - lib/brute/events/handler.rb
 - lib/brute/events/prefixed_terminal_output.rb
 - lib/brute/events/terminal_output_handler.rb
+- lib/brute/hooks.rb
 - lib/brute/message_transport.rb
 - lib/brute/message_transport/anthropic.rb
 - lib/brute/message_transport/llm.rb
@@ -190,6 +191,7 @@ files:
 - lib/brute/middleware/010_max_iterations.rb
 - lib/brute/middleware/015_otel_token_usage.rb
 - lib/brute/middleware/020_system_prompt.rb
+- lib/brute/middleware/025_skills.rb
 - lib/brute/middleware/040_compaction_check.rb
 - lib/brute/middleware/060_questions.rb
 - lib/brute/middleware/070_tool_pipeline.rb
@@ -198,6 +200,7 @@ files:
 - lib/brute/middleware/event_handler.rb
 - lib/brute/middleware/open_router.rb
 - lib/brute/middleware/user_queue.rb
+- lib/brute/prompt_template.rb
 - lib/brute/prompts.rb
 - lib/brute/prompts/autonomy.rb
 - lib/brute/prompts/base.rb
@@ -231,6 +234,7 @@ files:
 - lib/brute/prompts/text/identity/default.txt
 - lib/brute/prompts/text/identity/google.txt
 - lib/brute/prompts/text/identity/openai.txt
+- lib/brute/prompts/text/skills/default.erb
 - lib/brute/prompts/text/tone_and_style/anthropic.txt
 - lib/brute/prompts/text/tone_and_style/default.txt
 - lib/brute/prompts/text/tone_and_style/google.txt
@@ -268,6 +272,7 @@ files:
 - lib/brute/turn/tool_pipeline.rb
 - lib/brute/utils/diff.rb
 - lib/brute/version.rb
+- lib/brute/version.rb.erb
 - lib/brute_cli/providers/shell.rb
 - lib/brute_cli/providers/shell_response.rb
 homepage: https://github.com/general-intelligence-systems/brute