Module tool_handles 

Per-runtime registry of detached tool invocations (C2).

A ToolCall action with a detached car_ir::tool_stream::ToolInvocationMode (streaming / long_running) is started, not awaited: dispatch registers the invocation here, hands the caller a ToolHandle as the action’s output, and the DAG proceeds. Chunks the executor yields are buffered per handle (drained by ToolHandleRegistry::poll) and fanned out on a broadcast channel so a server can forward them to subscribed clients as tools.stream.event notifications.

Lifecycle: register → zero or more push_chunk → a terminal chunk (done / error) or cancel seals the entry. A sealed entry stays queryable until a poll observes it after draining its last chunks; that poll removes it (the “read your final answer once” contract — mirrors how idempotency results are consumed).

Structs

ToolHandleRegistry

Registry of live (and recently-terminal) detached tool invocations. One per crate::executor::Runtime; cheap to share via Arc.

ToolPollResult

What poll returns: the drained chunks since the last poll plus the invocation’s current status and, once terminal, its final result or error extracted from the terminal chunk.

Functions

spawn_drain

Spawn the drain task tying an executor’s chunk stream to the registry: forwards chunks until a terminal chunk, stream close, or cancellation. Returns immediately; the task owns the receiver.