# `Nous.PubSub.Approval`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/pubsub/approval.ex#L1)

Async HITL approval via PubSub.

Provides a handler function compatible with `Nous.Plugins.HumanInTheLoop`
that broadcasts approval requests and waits for responses via PubSub.
This enables LiveView or other external processes to approve/reject
tool calls asynchronously.

## Usage

    # In your agent setup:
    deps = %{
      hitl_config: %{
        tools: ["send_email"],
        handler: Nous.PubSub.Approval.handler(
          pubsub: MyApp.PubSub,
          session_id: session_id,
          timeout: :timer.minutes(5)
        )
      }
    }

    # In your LiveView:
    def handle_info({:approval_required, approval}, socket) do
      {:noreply, assign(socket, pending_approval: approval)}
    end

    def handle_event("approve", _params, socket) do
      approval = socket.assigns.pending_approval
      Nous.PubSub.Approval.respond(
        MyApp.PubSub, approval.session_id, approval.tool_call_id, :approve
      )
      {:noreply, socket}
    end

# `handler`

```elixir
@spec handler(keyword()) :: (map() -> :approve | :reject | {:edit, map()})
```

Build an approval handler function for use with `Nous.Plugins.HumanInTheLoop`.

The returned function:
1. Broadcasts `{:approval_required, info}` on the agent topic
2. Subscribes to the approval topic and blocks via `receive`
3. Returns the decision when received, or `:reject` on timeout

## Options

  * `:pubsub` - PubSub module (falls back to `Nous.PubSub.configured_pubsub/0`)
  * `:session_id` - Session ID for topic routing (required)
  * `:timeout` - How long to wait for a response (default: 5 minutes)

# `respond`

```elixir
@spec respond(module(), String.t(), String.t(), :approve | :reject | {:edit, map()}) ::
  :ok | {:error, term()}
```

Send an approval response for a pending tool call.

Broadcasts `{:approval_response, tool_call_id, decision}` on the
approval topic for the given session.

## Parameters

  * `pubsub` - PubSub module
  * `session_id` - Session ID
  * `tool_call_id` - The tool call ID to respond to
  * `decision` - `:approve`, `:reject`, or `{:edit, new_args}`

---

*Consult [api-reference.md](api-reference.md) for complete listing*