Struct Scratchpad 

pub struct Scratchpad { /* private fields */ }

A run-scoped, shared scratchpad passed to every hook via HookContext.

A type-map with interior mutability: cooperating hooks read and write typed values keyed by type, sharing per-run state (a turn counter, a running budget, a phase flag) without each rolling its own Arc<Mutex<…>>. Every hook in a run receives the same HookContext by shared reference, so they all see one scratchpad (and cloning a Scratchpad shares its storage too); a fresh run starts with an empty one.

Hooks receive &HookContext (shared), so every accessor here takes &self and mutates through an internal lock. Reads clone the stored value out (the lock cannot hand out a borrow), so store cheaply-cloneable values.

Concurrency

Most events are dispatched sequentially within a run, but at tool_concurrency > 1 the ToolCall / ToolResult hooks for different tools in the same turn may run concurrently, all sharing this one scratchpad. Each accessor (insert, update, …) is race-free per operation (it holds the lock for the whole read-modify-write), but the framework imposes no deterministic ordering across those concurrent tool hooks — the order in which two tools’ hooks touch the scratchpad depends on tool completion timing. Prefer commutative / idempotent state (a counter, a set union), or key per-tool state by the tool call id / internal call id, rather than relying on the order of concurrent updates.

Example

#[derive(Clone, Default)]
struct Calls(u32);

let pad = Scratchpad::default();
pad.update(|c: &mut Calls| c.0 += 1);
assert_eq!(pad.get::<Calls>().map(|c| c.0), Some(1));

Implementations

impl Scratchpad

pub fn insert<T: Clone + WasmCompatSend + WasmCompatSync + 'static>( &self, val: T, ) -> Option<T>

Insert a typed value, returning the previous value of the same type.

pub fn get<T: Clone + WasmCompatSend + WasmCompatSync + 'static>( &self, ) -> Option<T>

Get a clone of the stored value of type T, if present.

pub fn contains<T: WasmCompatSend + WasmCompatSync + 'static>(&self) -> bool

Whether a value of type T is present.

pub fn remove<T: Clone + WasmCompatSend + WasmCompatSync + 'static>( &self, ) -> Option<T>

Remove and return the stored value of type T, if present.

pub fn update<T, R>(&self, f: impl FnOnce(&mut T) -> R) -> R

where T: Clone + Default + WasmCompatSend + WasmCompatSync + 'static,

Read-modify-write the value of type T under one lock acquisition, starting from Default when absent. The value is stored back and the closure’s return value is returned.

The whole read-modify-write is atomic (no lost updates), but at tool_concurrency > 1 it imposes no ordering across concurrent tool hooks — see the type-level concurrency note. This is the race-free way to bump a counter or accumulate:

pad.update(|t: &mut Total| t.0 += 10);

Trait Implementations

impl Clone for Scratchpad

fn clone(&self) -> Scratchpad

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Scratchpad

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

Formats the value using the given formatter.

impl Default for Scratchpad

fn default() -> Scratchpad

Returns the “default value” for a type.