Crate embacle_tool_host 

Host your own tools to an ACP agent.

Why this exists

An ACP agent such as copilot --acp runs its own tool loop inside its own subprocess. It never asks its caller to execute a tool; it executes them itself and reports afterwards, and the report carries no tool name — ACP’s session/update notification has toolCallId, title, kind and status, and nothing that identifies which tool ran.

So a caller that wants the agent to use ITS tools has exactly one channel: declare an MCP server in session/new. The agent then speaks MCP to that server, and tools/call carries the name and the arguments in full fidelity.

That channel cannot be an in-process callback. The agent forks the MCP server itself when the transport is stdio, so the server is a grandchild process in a different address space, and the ACP frame carries only command/args/env — no socket, no file descriptor, no back-channel. Reaching a caller’s McpToolExecutor therefore requires a real listener, and loopback HTTP is the smallest one that works.

Why it is not in the root crate

AGENTS.md states “No HTTP dependencies in core” as a design decision, and the root crate earns it: ffi = ["copilot-headless"] ships a staticlib compiled panic = "abort", where a panic inside a tool handler would abort the host application. Consumers that enable copilot-headless without ever hosting tools should not pay for a web stack. This crate is opt-in by existing separately.

Lifetime

One ToolHost per process binds one listener. Each turn opens a ToolSession carrying its own bearer token and its own tool surface. Dropping the session revokes the bearer immediately — an orphaned agent subprocess that retries after the turn ends gets 401 instead of executing an irreversible action for a user who has already gone.

Structs

StaticSurface

A surface whose tool list never changes, backed by an McpToolExecutor.

ToolHost

A bound loopback MCP endpoint. Cheap to clone.

ToolHostConfig

How the endpoint binds.

ToolOutcome

One tool call’s outcome, in MCP’s own shape.

ToolSession

A turn’s credential and tool surface.

Traits

ToolSurface

The caller’s tool surface, consulted per request.