Struct RequestPatch 

#[non_exhaustive]
pub struct RequestPatch {
    pub preamble: Option<String>,
    pub temperature: Option<f64>,
    pub max_tokens: Option<u64>,
    pub tool_choice: Option<ToolChoice>,
    pub active_tools: Option<Vec<String>>,
    pub additional_params: Option<Value>,
    pub extra_context: Vec<Document>,
    pub history: Option<Vec<Message>>,
}

A partial patch over the model request for a single turn, returned by a hook via Flow::PatchRequest on a StepEvent::CompletionCall event.

Every field is optional: a Some value overrides the agent’s configured value for this turn, a None value inherits it. The patch is per-turn and non-sticky — it never changes the agent’s baseline, so the next turn re-fires CompletionCall and resolves from the baseline again.

Merge behavior

Two kinds of merge apply. When several hooks in a HookStack each return a patch, they are combined hook ⊕ hook in registration order with these per-field rules; the effective patch is then applied patch → baseline.

Field	hook ⊕ hook (registration order)	patch → baseline
extra_context	append (earlier hooks’ docs first)	append after static + dynamic context
additional_params	shallow-merge top-level keys, later hook wins	shallow-merge onto baseline params
preamble	last writer wins (warns on conflict)	replaces
temperature, max_tokens, tool_choice	last writer wins (warns on conflict)	replaces
active_tools	set intersection (warns when empty)	narrows the advertised set
history	last writer wins (warns on conflict)	replaces the messages sent this turn

active_tools intersects rather than last-writer-wins because it is an allow-list guardrail: two narrowing hooks must compose as narrowing. All last-writer-wins conflicts emit a tracing::warn! so composition stays debuggable — additive guidance belongs in extra_context documents, not in preamble concatenation.

Build one with the setters:

Flow::patch_request(
    RequestPatch::new()
        .tool_choice(ToolChoice::Required)
        .active_tools(["search"])
        .temperature(0.0),
)

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

preamble: Option<String>

Override the system prompt / preamble for this turn.

temperature: Option<f64>

Override the sampling temperature for this turn.

max_tokens: Option<u64>

Override the max output tokens for this turn.

tool_choice: Option<ToolChoice>

Override the tool choice for this turn.

active_tools: Option<Vec<String>>

Restrict the advertised tools to this allow-list (by name) for this turn. Some(vec![]) advertises no executable tools; None keeps the full set.

additional_params: Option<Value>

Provider-passthrough params shallow-merged onto the agent’s for this turn.

extra_context: Vec<Document>

Extra context documents appended (after static and dynamic context) for this turn only. The passive-RAG injection point.

history: Option<Vec<Message>>

Replace the prior chat history sent to the provider this turn only. The persisted transcript and the run state are untouched, and RAG’s query text still derives from the original prompt/history — this changes only what messages are sent. None sends the real history. The enabling primitive for context-window compaction / summarization middleware.

Implementations

impl RequestPatch

pub fn new() -> Self

An empty patch — a no-op, identical to returning Flow::cont.

pub fn preamble(self, preamble: impl Into<String>) -> Self

Override the system prompt / preamble for this turn.

pub fn temperature(self, temperature: f64) -> Self

Override the sampling temperature for this turn.

pub fn max_tokens(self, max_tokens: u64) -> Self

Override the max output tokens for this turn.

pub fn tool_choice(self, tool_choice: ToolChoice) -> Self

Override the tool choice for this turn.

Not every provider honors tool_choice: some in-core providers (e.g. Ollama, Hyperbolic, Mira, Perplexity) ignore it and log a warning, so forcing a tool this way is a no-op there. A choice a provider cannot represent (e.g. a multi-name ToolChoice::Specific on Anthropic, which forces a single tool) surfaces as a request error rather than being silently downgraded.

pub fn active_tools<I, S>(self, names: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Restrict the advertised tools to this allow-list (by name) for this turn.

This narrows the executable tool set, so it composes with tool_choice: if the effective tool choice is a ToolChoice::Specific naming a tool that active_tools filters out (e.g. the agent’s baseline choice is inherited because this patch didn’t set its own), the request fails closed with a request error rather than silently forcing a dropped tool. When narrowing the set, set a compatible tool_choice in the same patch.

pub fn additional_params(self, additional_params: Value) -> Self

Shallow-merge these provider-passthrough params onto the agent’s for this turn.

pub fn extra_context<I>(self, docs: I) -> Self

where I: IntoIterator<Item = Document>,

Append extra context documents for this turn (the passive-RAG injection point). Documents are appended after the agent’s static and dynamic (vector-store) context, in the order added.

pub fn context(self, doc: Document) -> Self

Append a single extra context document for this turn.

pub fn history<I>(self, history: I) -> Self

where I: IntoIterator<Item = Message>,

Replace the prior chat history sent to the provider this turn only. The persisted transcript is untouched; RAG query text still derives from the original history. Use for context-window compaction / summarization.

Trait Implementations

impl Clone for RequestPatch

fn clone(&self) -> RequestPatch

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RequestPatch

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for RequestPatch

fn default() -> RequestPatch

Returns the “default value” for a type.

impl PartialEq for RequestPatch

fn eq(&self, other: &RequestPatch) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for RequestPatch