Skip to main content

ProtocolPolicy

clark_agent::protocol

Trait ProtocolPolicy 

Source 
pub trait ProtocolPolicy:
    Send
    + Sync
    + 'static {
    // Provided methods
    fn name(&self) -> &'static str { ... }
    fn terminal_tool_names(&self) -> HashSet<String> { ... }
    fn plain_text_recovery_prompt(
        &self,
        _ctx: PlainTextRecoveryContext<'_>,
    ) -> Option<String> { ... }
    fn normalize_tool_calls(
        &self,
        _calls: &mut [ToolCall],
        _registry: &ToolRegistry,
    ) -> usize { ... }
    fn hidden_tool_error(
        &self,
        _ctx: HiddenToolContext<'_>,
    ) -> Option<HiddenToolError> { ... }
}
Expand description

Product-specific conversation-protocol policy.

Every method has a generic default, so a product only overrides the behaviors whose vocabulary it cares about. The core never inspects allowlist shape or tool names for product meaning — that logic lives behind this trait.

Implementations must be cheap and side-effect-free: no I/O, no LLM calls. They are pure transforms of context → text/decision, invoked on hot paths in the loop.

Provided Methods§

Source

fn name(&self) -> &'static str

Stable identifier for logs and diagnostics.

Source

fn terminal_tool_names(&self) -> HashSet<String>

Tool names — besides the configured terminal fallback tool — that count as terminal/delivery tools when the loop decides whether a turn’s allowlist has narrowed to “terminal only” (the gate the plain-text-terminal fallback waits for in its non-eager mode).

Default: empty. With no extra terminal names, an allowlist is “terminal only” exactly when it contains nothing but the fallback tool itself — a safe, vocabulary-free default. A product that advertises several delivery tools (final answer, ask-user, …) lists them here.

Source

fn plain_text_recovery_prompt( &self, _ctx: PlainTextRecoveryContext<'_>, ) -> Option<String>

Recovery prose injected as a system message when the model emits plain text with no tool call and the loop wants to nudge it back onto the protocol.

Return None to use the core’s generic, vocabulary-free nudge. Override to name the product’s actual delivery / ask tools.

Source

fn normalize_tool_calls( &self, _calls: &mut [ToolCall], _registry: &ToolRegistry, ) -> usize

Rewrite a model-emitted tool-call batch in place before registry lookup — e.g. fold a known alias name into a canonical tool and move the alias into an argument. Returns the number of calls rewritten (for diagnostics; the loop does not require it).

Default: no-op. The core performs no alias repair of its own.

Source

fn hidden_tool_error( &self, _ctx: HiddenToolContext<'_>, ) -> Option<HiddenToolError>

Render an error for a tool hidden by per-turn narrowing, when no crate::plugin::ToolGate claimed responsibility for the denial.

Return None to use the core’s generic message (“that tool isn’t available this turn; here’s what is”). Override to map the allowlist shape to a product-specific recovery instruction.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§