Nous.Hook.Runner (nous v0.13.3)

View Source

Executes hooks for lifecycle events with support for blocking, modification, and external command execution.

Execution Semantics

  • Blocking events (:pre_tool_use, :pre_request): short-circuits on first :deny
  • Non-blocking events: all hooks run, results collected
  • Hooks with the same priority run sequentially (ordered by registration)
  • Each hook has a configurable timeout (default 10s)

Handler Types

  • :function — Calls the function directly with (event, payload)
  • :module — Calls module.handle(event, payload)
  • :command — Executes shell command via NetRunner.run/2 with JSON on stdin

Summary

Functions

run(registry, event, payload)

Run all matching hooks for an event.

run_hooks(hooks, event, payload)

Run a list of hooks directly (without registry lookup).

Functions

run(registry, event, payload)

@spec run(Nous.Hook.Registry.t() | nil, Nous.Hook.event(), map()) ::
  Nous.Hook.result()

Run all matching hooks for an event.

Returns the aggregate result:

  • :allow — all hooks passed (or no hooks registered)
  • :deny or {:deny, reason} — a hook blocked the action
  • {:modify, changes} — a hook wants to modify the payload (last modify wins)

run_hooks(hooks, event, payload)

@spec run_hooks([Nous.Hook.t()], Nous.Hook.event(), map()) :: Nous.Hook.result()

Run a list of hooks directly (without registry lookup).