Behaviour + macro for user-level hook modules.

Events

There are four event types, two for tool calls and two for LLM HTTP requests:

All events share the same interest/3 + verdict/3 / verdict/4 callbacks. The tool_name for LLM events is always "LLM_REQUEST".

Usage

defmodule MyHook do
  use Eai.Hook, priority: 10

  # ── Tool hooks ──────────────────────────────────────────

  @impl true
  def interest(:pre, tool_name, _payload),
    do: String.contains?(tool_name, "WriteToSession")
  def interest(_event, _tool, _payload), do: false

  @impl true
  def verdict(:pre, _tool, payload) do
    if payload.args |> hd() |> String.contains?("rm -rf") do
      {:block, "blocked dangerous command"}
    else
      :ok
    end
  end

  @impl true
  def verdict(:post, _tool, _payload, result), do: :ok

  # ── LLM hooks ───────────────────────────────────────────

  @impl true
  def interest(:llm_pre, "LLM_REQUEST", _payload), do: true
  def interest(:llm_post, "LLM_REQUEST", _payload), do: true

  @impl true
  def verdict(:llm_pre, _tool, _payload), do: :ok

  @impl true
  def verdict(:llm_post, _tool, _payload, result) do
    case result do
      {:error, _reason, _msgs} ->
        # handle error, e.g. log or rollback
        :ok
      _ -> :ok
    end
  end
end

LLM payload shape

llm_pre and llm_post receive:

%{
  messages: [Eai.Message.t()],
  pty_session_id: String.t(),
  chat_session_id: String.t(),
  opts: map()
}

llm_post additionally receives result as the 4th argument:

{:ok, reply_text, full_history} | {:error, reason, partial_history}

The post-hook can return {:modify, modified_result} to replace the return value that bubbles up to the Chat GenServer.

Callbacks

• interest/3 — return true to opt-in. Keep fast: no I/O.

• verdict/3 — pre-hook (:pre, :llm_pre): :ok | {:block, reason} | {:modify, new_value}

• verdict/4 — post-hook (:post, :llm_post): :ok | {:block, reason} | {:modify, new_value}

Registered automatically

@before_compile injects register/0 which puts this module into :persistent_term under :eai_hooks. Called by Eai.Hub.Pipeline.register/1.