Behaviour for implementing pluggable approval hooks.

Hooks can provide synchronous or asynchronous approval decisions for tool invocations, command executions, and file access operations.

Callbacks

• prepare/2 - Called before the approval review, can mutate metadata
• review_tool/3 - Review a tool invocation
• review_command/3 - Review a command execution (optional)
• review_file/3 - Review a file access operation (optional)
• await/2 - Wait for an async approval decision (optional)

Return Values

Synchronous hooks return:

• :allow - approve the operation
• {:allow, opts} - approve with additional options (used by app-server approvals)
• {:deny, reason} - deny with a reason string

Asynchronous hooks return:

• {:async, ref} - defer decision, will call await/2 later
• {:async, ref, metadata} - defer decision with additional metadata

{:allow, opts} supports :grant_root to grant file-change approvals for the session when requested by the app-server.

Example

defmodule MyApp.SlackApprovalHook do
  @behaviour Codex.Approvals.Hook

  @impl true
  def prepare(event, context) do
    # Add custom metadata before review
    {:ok, Map.put(context, :slack_channel, "#approvals")}
  end

  @impl true
  def review_tool(event, context, _opts) do
    # Post to Slack and return async ref
    ref = make_ref()
    MyApp.SlackClient.post_approval_request(ref, event, context)
    {:async, ref}
  end

  @impl true
  def await(ref, timeout) do
    # Wait for Slack response
    receive do
      {:approval_decision, ^ref, decision} -> {:ok, decision}
    after
      timeout -> {:error, :timeout}
    end
  end
end