Struct ToolCtx 

#[non_exhaustive]
pub struct ToolCtx {
    pub pubsub: Arc<dyn Pubsub>,
    pub kv: Arc<dyn KvStore>,
    pub jobs: Arc<dyn JobQueue>,
    pub progress: Option<Sender<AgentEvent>>,
    pub cancel: CancellationToken,
    pub server_outbound: Option<Arc<dyn ServerOutbound>>,
    pub caller_principal: Option<CallerPrincipal>,
    pub parent_anchor: Option<ParentAnchor>,
}

Narrowed slice of AgentContext (see agent.rs) passed to tools.

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.

pubsub: Arc<dyn Pubsub>

Pub/sub bus.

kv: Arc<dyn KvStore>

KV store.

jobs: Arc<dyn JobQueue>

Job queue.

progress: Option<Sender<AgentEvent>>

Optional progress sender. Tools that wrap an crate::Agent (e.g. AgentAsToolInvoker in klieo-mcp-server) overlay this onto the minted AgentContext. Non-agent invokers ignore the field.

cancel: CancellationToken

Cooperative cancellation token. HTTP/SSE transports pass a request-scoped child token derived from the server’s parent cancel; tools should select! against cancel.cancelled() to honor client disconnects mid-call.

server_outbound: Option<Arc<dyn ServerOutbound>>

Optional outbound channel for server-initiated JSON-RPC (e.g. MCP sampling/createMessage). Tools requiring the outbound surface return Err(Unsupported) when None. Default: None.

caller_principal: Option<CallerPrincipal>

Verified caller principal for server-side authorisation (e.g. binding a klieo/run/resume ticket to its issuer). Server-side metadata ONLY: implementations MUST NOT append this value to short-term/episodic memory, conversation history, or any LLM-visible message — those surfaces are operator- reviewed and PII-redacted on their own contract. None when no authenticator is wired, when the transport carries no principal (stdio, unauthenticated HTTP), or when the request is anonymous.

parent_anchor: Option<ParentAnchor>

Opaque cross-hop provenance anchor supplied by an authenticated caller — by convention the caller’s own provenance chain-entry id (or its run’s episodic-root hash). When set, the run records it as its origin so klieo→klieo composition can be stitched across deployment boundaries in the audit trail. Audit metadata ONLY: implementations MUST NOT append it to short-term/episodic memory, conversation history, or any LLM-visible message. The value is recorded verbatim (stitching requires it to equal the caller’s chain-entry id), is a caller-ASSERTED, UNVERIFIED claim, and must be treated as such downstream. None when no anchor was supplied or the caller is unauthenticated.

Implementations

impl ToolCtx

pub fn new( pubsub: Arc<dyn Pubsub>, kv: Arc<dyn KvStore>, jobs: Arc<dyn JobQueue>, ) -> Self

Construct a ToolCtx with default progress = None, no outbound channel, and a fresh uncancelled CancellationToken. Builders below override.

pub fn with_cancel(self, cancel: CancellationToken) -> Self

Override the cancellation token (HTTP/SSE callers pass a request-scoped child token).

pub fn with_progress(self, progress: Sender<AgentEvent>) -> Self

Override the progress sender (HTTP/SSE callers pass the per-request broadcast for AgentEvent forwarding).

pub fn with_server_outbound(self, outbound: Arc<dyn ServerOutbound>) -> Self

Attach a server-initiated outbound channel so tools can issue reverse-direction JSON-RPC requests to the connected peer.

pub fn with_caller_principal(self, principal: String) -> Self

Stamp the verified caller principal so server-side authorisation helpers (e.g. resume-ticket issuance) can bind follow-up requests to the original caller. See the field docstring for the prohibition on leaking this value into LLM-visible memory.

pub fn with_parent_anchor(self, anchor: String) -> Self

Stamp the cross-hop provenance anchor (the caller’s chain-entry id) so the run can record its origin. See the field docstring for the verbatim-record / unverified-claim / no-LLM-leak contract.

Trait Implementations

impl Clone for ToolCtx

fn clone(&self) -> ToolCtx

Returns a duplicate of the value.

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

Performs copy-assignment from source.