Documentation
¶
Overview ¶
Package hook provides a lightweight, generic event system for lifecycle hooks.
It allows registering handlers for arbitrary event types. Handlers run sequentially in registration order, with short-circuit on Abort and chained Modify results. Panicking handlers are recovered and converted to errors without disrupting subsequent handler dispatch.
The hook module is domain-agnostic — applications define their own event types by implementing the Event interface. For example, the agent module defines PreToolCall, PreLLMCall, TurnStart, etc.
Usage:
registry := hook.NewRegistry()
registry.On("my_event", func(ctx context.Context, e hook.Event) hook.Result {
log.Printf("event: %s", e.Type())
return hook.Continue()
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event interface {
// Type returns the event type identifier.
Type() EventType
}
Event is the interface for all hook events. Applications define concrete event types that implement this interface.
type EventType ¶
type EventType string
EventType identifies the kind of hook event. Applications define their own EventType constants.
type Handler ¶
Handler processes a hook event and returns a result. The context carries deadlines, cancellation, and request-scoped values.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages hook handlers and dispatches events. Handlers are executed sequentially in registration order. An Abort result short-circuits remaining handlers. Modify results chain — each handler sees the previous modification. Panicking handlers are recovered and converted to errors without disrupting dispatch to subsequent handlers.
func (*Registry) Clear ¶
Clear removes all handlers for the given event type. If no event type is specified, clears all handlers.
func (*Registry) Emit ¶
Emit dispatches an event to all registered handlers for its type. Handlers run sequentially. First Abort short-circuits. Returns the merged result (last non-Continue result wins). Panicking handlers are recovered: the panic is converted to an error on the Result and dispatch continues to the next handler.
func (*Registry) HasHandlers ¶
HasHandlers returns true if any handlers are registered for the event type.
type Result ¶
type Result struct {
// Action determines whether to continue, abort, or modify.
Action Action
// ModifiedData carries replacement data when Action is Modify.
ModifiedData any
// Reason explains why execution was aborted (Action == Abort).
Reason string
// Err reports an error from the handler without aborting dispatch.
Err error
}
Result is returned by hook handlers to control execution flow.
func AbortWithError ¶
AbortWithError returns a Result that stops execution with an error.
func ContinueWithError ¶
ContinueWithError returns a Result that lets execution proceed but records an error.
Source Files