Global plugin behaviour for intercepting the Runner pipeline.

Unlike callbacks (per-invocation, per-agent), plugins are global — registered at the application level and applied to every Runner.run/5 call. Plugins can inspect/transform the context before execution, and inspect/transform results after.

Behaviour

Implement any subset of callbacks:

• init/1 — initialize plugin state from config, return {:ok, state}
• before_run/2 — called before Runner executes, receives {context, plugin_state}, returns {:cont, context, state} or {:halt, result, state}
• after_run/3 — called after Runner executes, receives {result, context, plugin_state}, returns {result, state}

Per-model and per-tool hooks (stateless)

These hooks are called inline during LLM agent execution. They do not carry plugin state (use ETS or GenServer in init/1 for statefulness across calls):

• before_model/2 — called before each LLM call; can modify the request or skip the call entirely by returning a canned response
• after_model/2 — called after each LLM call; can transform the response
• before_tool/3 — called before each tool execution; can modify args or skip the tool call by returning a canned result
• after_tool/3 — called after each tool execution; can transform the result
• on_event/2 — called for each event emitted during execution; observe-only

Example

defmodule MyPlugin do
  @behaviour ADK.Plugin

  @impl true
  def init(config), do: {:ok, config}

  @impl true
  def before_run(context, state) do
    {:cont, context, state}
  end

  @impl true
  def after_run(result, _context, state) do
    {result, state}
  end

  @impl true
  def before_model(context, request) do
    # Inject extra context into every model request
    {:ok, Map.put(request, :extra, "injected")}
  end

  @impl true
  def after_model(_context, response) do
    response
  end

  @impl true
  def before_tool(_context, tool_name, args) do
    IO.puts("Calling tool: #{tool_name}")
    {:ok, args}
  end

  @impl true
  def after_tool(_context, _tool_name, result) do
    result
  end

  @impl true
  def on_event(_context, event) do
    IO.inspect(event, label: "event")
    :ok
  end
end

# Register globally
ADK.Plugin.Registry.start_link([])
ADK.Plugin.register({MyPlugin, my_config: true})