# `MingaClaudeBridge.ToolCalls`
[🔗](https://github.com/jsmestad/minga-claude-bridge/blob/main/lib/minga_claude_bridge/tool_calls.ex#L1)

Pairs held MCP `tools/call` control requests with the tool results Minga sends later.

When Claude Code calls a Minga tool, the bridge does not answer the control request. It holds the request here, keyed by the `tool_use` id from `params._meta["claudecode/toolUseId"]`, and ends the Minga turn with the tool calls. The next Minga request carries the results; `resolve/3` turns each result into the reply line for its held request.

The correlator is a pure value: `tool_use_id => {control_request_id, jsonrpc_id}`.

  * `hold/2` rejects a `tool_use_id` that is already held.
  * `resolve/3` removes the id, so each held id resolves at most once. A second resolve, an id that was never held, and a resolve after `abort_all/1` return `{:error, :unknown_tool_use}`. Resolve order does not matter.
  * `abort_all/1` answers every held call with JSON-RPC error `-32800` (request cancelled) and returns an empty correlator.

The correlator does not remember resolved ids. A later `hold/2` of an id that was resolved before is accepted; Claude Code assigns a new `tool_use` id to every call, so this does not happen in a valid session.

## Tool results

A result is `%{content: [part], is_error: boolean}` where a part is `{:text, text}` or `{:image, media_type, data}` with `data` as raw bytes. It becomes the MCP `CallToolResult`: text parts become `{"type": "text", "text": ...}`, image parts become `{"type": "image", "data": base64, "mimeType": ...}`, and `isError` is set from `is_error`. Results are conversation content; do not log them.

# `held`

```elixir
@type held() :: %{
  tool_use_id: String.t(),
  control_request_id: String.t(),
  jsonrpc_id: MingaClaudeBridge.Wire.jsonrpc_id()
}
```

One call to hold: the ids needed to answer its control request later.

# `part`

```elixir
@type part() ::
  {:text, String.t()} | {:image, media_type :: String.t(), data :: binary()}
```

# `result`

```elixir
@type result() :: %{content: [part()], is_error: boolean()}
```

# `t`

```elixir
@opaque t()
```

# `abort_all`

```elixir
@spec abort_all(t()) :: {[MingaClaudeBridge.Wire.line()], t()}
```

Answers every held call with JSON-RPC error `-32800` and returns an empty correlator. Lines are ordered by `tool_use_id`.

# `call_tool_result`

```elixir
@spec call_tool_result(result()) :: map()
```

Converts a tool result to an MCP `CallToolResult` map.

# `hold`

```elixir
@spec hold(t(), held()) :: {:ok, t()} | {:error, :duplicate_tool_use}
```

Holds a call until its result arrives. Rejects a `tool_use_id` that is already held.

# `new`

```elixir
@spec new() :: t()
```

Returns an empty correlator.

# `pending_ids`

```elixir
@spec pending_ids(t()) :: [String.t()]
```

Returns the held `tool_use` ids in sorted order.

# `resolve`

```elixir
@spec resolve(t(), String.t(), result()) ::
  {:ok, MingaClaudeBridge.Wire.line(), t()} | {:error, :unknown_tool_use}
```

Answers the held call `tool_use_id` with `result`. Returns the `control_response` line to write and the correlator without that call.

---

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