@spec build_registry([hook_def()] | :undefined) :: hook_registry() | :undefined

Build a hook registry from a list of hook definitions.

Convenience function that creates a new registry and registers all provided hooks. Returns nil when the input is an empty list or nil (no hooks configured).

Used by all adapter session modules during init to convert the :sdk_hooks option into a registry.

Example

hooks = [
  BeamAgent.Hooks.hook(:pre_tool_use, &deny_bash/1),
  BeamAgent.Hooks.hook(:post_tool_use, &log_tool/1)
]
registry = BeamAgent.Hooks.build_registry(hooks)

@spec ensure_global_table() :: :ok

Create the global hooks ETS table. Idempotent.

The global hook table is an ordered_set keyed by {event, seq} where seq is a monotonically increasing integer assigned at registration time. This guarantees deterministic firing order across all OTP versions. Called automatically by BeamAgent.init/0. Safe to call multiple times — subsequent calls are no-ops.

@spec fire(hook_event(), hook_context(), hook_registry() | :undefined) ::
  {:ok, hook_context()} | {:deny, binary()} | {:ask, binary()}

Fire all hooks registered for an event.

Context is threaded through the hook chain: each hook receives the context as modified by the previous hook. The final context flows back to the caller via {:ok, final_ctx}.

• Blocking events (:pre_tool_use, :user_prompt_submit, :permission_request, :subagent_start, :pre_compact, :config_change): returns {:ok, final_ctx} if all hooks allow, {:deny, reason} on first deny, or {:ask, reason} on first ask.

• Notification-only events: always returns {:ok, final_ctx}. {:deny, _} and {:ask, _} from callbacks are ignored.

Handles nil/undefined registries (no hooks configured) gracefully. Each callback is wrapped in a try/catch for crash protection. Blocking hook crashes return {:deny, "hook crashed (fail-safe deny)"} (fail-closed). Notification hook crashes are logged and the context passes through unmodified (fail-open).

Example

case BeamAgent.Hooks.fire(:pre_tool_use, %{
  event: :pre_tool_use,
  tool_name: "Bash",
  tool_input: %{"command" => "rm -rf /"}
}, registry) do
  {:ok, final_ctx} -> proceed_with_tool(final_ctx)
  {:deny, reason} -> reject_tool(reason)
  {:ask, reason} -> escalate_to_caller(reason)
end

@spec global_registry() :: hook_registry()

Read the entire global hook registry as a hook_registry() map.

Returns a map from event atoms to lists of hook definitions, mirroring the shape of per-session registries. Returns an empty map if no global hooks are registered.

@spec hook(hook_event(), hook_callback()) :: %{
  event: hook_event(),
  callback: hook_callback()
}

Create a hook that fires on all occurrences of an event.

event is the lifecycle event atom (e.g. :pre_tool_use, :session_start). callback is a 1-arity function receiving a hook_context() map.

Returns a hook_def() map suitable for register_hook/2 or build_registry/1.

Example

hook = BeamAgent.Hooks.hook(:session_start, fn ctx ->
  IO.puts("Session started: #{Map.get(ctx, :session_id, "unknown")}")
  {:ok, ctx}
end)

@spec hook(hook_event(), hook_callback(), hook_matcher()) :: %{
  event: hook_event(),
  callback: hook_callback(),
  matcher: hook_matcher(),
  compiled_re: :re.mp()
}

Create a hook with a matcher filter.

The matcher restricts which tools trigger the hook. Only relevant for tool-related events (:pre_tool_use, :post_tool_use, :post_tool_use_failure).

The :tool_name field in the matcher can be an exact binary string or a regex pattern. Invalid regex patterns raise at registration time (fail-fast).

Example

# Only fire for Write and Edit tools:
hook = BeamAgent.Hooks.hook(
  :pre_tool_use,
  fn ctx ->
    IO.puts("File mutation: #{Map.get(ctx, :tool_name, "")}")
    :ok
  end,
  %{tool_name: "^(Write|Edit)$"}
)

@spec new_registry() :: %{}

Create an empty hook registry.

Returns a new hook_registry() map with no registered hooks.

@spec register_global(hook_def()) :: :ok

Register a hook globally (fires for every session).

Inserts the hook into the global ETS table and notifies the reload bus so live sessions pick up the change. The table is created automatically if it does not exist yet.

Example

hook = BeamAgent.Hooks.hook(:pre_tool_use, fn ctx ->
  case Map.get(ctx, :tool_name) do
    "Bash" -> {:deny, "No Bash globally"}
    _ -> {:ok, ctx}
  end
end)

:ok = BeamAgent.Hooks.register_global(hook)

@spec register_hook(hook_def(), hook_registry()) :: hook_registry()

Register a single hook in the registry.

Adds hook_def to the registry under its event key. Hooks are prepended internally (O(1)) and reversed at fire time to preserve registration order.

Returns the updated registry.

Example

registry =
  BeamAgent.Hooks.new_registry()
  |> then(fn r ->
       BeamAgent.Hooks.register_hook(
         BeamAgent.Hooks.hook(:stop, fn _ -> :ok end),
         r
       )
     end)

@spec register_hooks([hook_def()], hook_registry()) :: hook_registry()

Register multiple hooks in the registry.

Adds all hook definitions to the registry in list order.

Returns the updated registry.

@spec unregister_global(hook_def()) :: :ok

Unregister a hook from the global registry.

Removes the exact hook object. Other hooks for the same event are unaffected. Notifies the reload bus after removal.

Returns :ok even if the hook was not found (idempotent).