Class: Brute::Hooks

Inherits:

Object

• Object
• Brute::Hooks

Defined in:

lib/brute/hooks.rb

Overview

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.

Constant Summary

EVENTS =

%i[turn_start turn_end before_llm after_llm before_tool approve_tool after_tool].freeze

Instance Method Summary

• #any?(event) ⇒ Boolean
• #emit(event, payload) ⇒ Object

  Fire an event; returns every subscriber's raw result (nils and false included — the deny contract distinguishes them).

• #initialize ⇒ Hooks constructor

  A new instance of Hooks.

• #on(event, &block) ⇒ Object

Constructor Details

#initialize ⇒ Hooks

Returns a new instance of Hooks.

# File 'lib/brute/hooks.rb', line 34

def initialize
  @subscribers = Hash.new { |hash, key| hash[key] = [] }
end

Instance Method Details

#any?(event) ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/brute/hooks.rb', line 49

def any?(event) = @subscribers[event.to_sym].any?

#emit(event, payload) ⇒ Object

Fire an event; returns every subscriber's raw result (nils and false included — the deny contract distinguishes them).

# File 'lib/brute/hooks.rb', line 45

def emit(event, payload)
  @subscribers[event.to_sym].map { |subscriber| subscriber.call(payload) }
end

#on(event, &block) ⇒ Object

# File 'lib/brute/hooks.rb', line 38

def on(event, &block)
  @subscribers[event.to_sym] << block
  self
end