Module protocol 

Conversation-protocol policy: the seam between the generic loop and a product’s tool vocabulary.

The core loop is provider-agnostic, sandbox-agnostic, and tooling-agnostic. It must not know the names of any particular product’s tools — there is no message_result, no plan, no capability profile baked into the runtime. But three behaviors genuinely need product-specific knowledge to do their job well:

1. Plain-text recovery. When a provider returns prose instead of a structured tool call, the loop nudges it back onto the protocol. A good nudge names the product’s actual delivery / ask tools.
2. Tool-call alias repair. Models sometimes emit a tool name the product folds into a canonical tool (e.g. advance(...) → plan(action="advance", ...)). The product knows its aliases; the core does not.
3. Hidden-tool errors. When a per-turn crate::plugin::ToolGate narrows the catalog and the model calls a tool that isn’t advertised, the most useful error names the product concept that hid it (“call plan(action=\"set\") first”). The core can only say “that tool isn’t available this turn.”

Rather than hardcode any product’s vocabulary, the loop delegates all three to a ProtocolPolicy. The core ships DefaultProtocolPolicy, whose methods all return generic, vocabulary-free behavior. Downstream product crates implement their own policy and install it via crate::AgentBuilder::protocol_policy. This keeps product tool names out of the open-source core entirely.

Structs

DefaultProtocolPolicy

The generic, vocabulary-free policy installed when a caller does not supply one. Every method takes its trait default.

HiddenToolContext

Context for ProtocolPolicy::hidden_tool_error.

HiddenToolError

A rendered hidden-tool error: prose the model reads plus a structured details payload for typed downstream handling.

PlainTextRecoveryContext

Context for ProtocolPolicy::plain_text_recovery_prompt.

Constants

DEFAULT_PLAIN_TEXT_RECOVERY_PROMPT

Generic, product-agnostic plain-text recovery prose. Used when the active ProtocolPolicy returns None from ProtocolPolicy::plain_text_recovery_prompt.

Traits

ProtocolPolicy

Product-specific conversation-protocol policy.