# `ExMCP.ACP.Client.Handler`
[🔗](https://github.com/azmaveth/ex_mcp/blob/v1.0.0/lib/ex_mcp/acp/client/handler.ex#L1)

Behaviour for handling ACP session events and agent requests.

Implement this behaviour to customize how your application responds to
streaming session updates, permission requests, and file access requests
from ACP agents.

See `ExMCP.ACP.Client.DefaultHandler` for a reference implementation.

# `state`

```elixir
@type state() :: any()
```

# `handle_file_read`
*optional* 

```elixir
@callback handle_file_read(
  session_id :: String.t(),
  path :: String.t(),
  opts :: map(),
  state()
) ::
  {:ok, content :: String.t(), state()}
  | {:error, reason :: String.t(), state()}
```

Called when the agent requests to read a file.

Return `{:ok, content, state}` with the file contents, or
`{:error, reason, state}` to deny access.

# `handle_file_write`
*optional* 

```elixir
@callback handle_file_write(
  session_id :: String.t(),
  path :: String.t(),
  content :: String.t(),
  state()
) :: {:ok, state()} | {:error, reason :: String.t(), state()}
```

Called when the agent requests to write a file.

Return `{:ok, state}` to allow the write, or
`{:error, reason, state}` to deny it.

# `handle_permission_request`

```elixir
@callback handle_permission_request(
  session_id :: String.t(),
  tool_call :: map(),
  options :: [map()],
  state()
) :: {:ok, outcome :: map(), state()}
```

Called when the agent requests permission to use a tool.

Must return an outcome map with an `"optionId"` matching one of the
provided options.

# `handle_session_update`

```elixir
@callback handle_session_update(session_id :: String.t(), update :: map(), state()) ::
  {:ok, state()}
```

Called for each `session/update` notification from the agent.

The `update` map contains a `"sessionUpdate"` discriminator field indicating
the update type (e.g., `"agent_message_chunk"`, `"tool_call"`, `"plan"`, etc.).

# `handle_terminal_request`
*optional* 

```elixir
@callback handle_terminal_request(
  method :: String.t(),
  params :: map(),
  id :: integer() | String.t() | nil,
  state()
) :: {:ok, result :: map(), state()} | {:error, reason :: String.t(), state()}
```

Called when the agent requests a terminal operation.

The `method` is one of the stable `terminal/*` methods and `params` is the
raw ACP params map. Return `{:ok, result, state}` with the method-specific
result map, or `{:error, reason, state}` to deny or fail the operation.

# `init`

```elixir
@callback init(opts :: keyword()) :: {:ok, state()}
```

Called when the handler is initialized.

# `terminate`
*optional* 

```elixir
@callback terminate(reason :: any(), state()) :: :ok
```

Called when the handler is being terminated.

---

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