Trait ListenExecuteTool

Source

pub trait ListenExecuteTool<Ctx>: Send + Sync {
    type Name: ToolName;

    // Required methods
    fn name(&self) -> Self::Name;
    fn display_name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn input_schema(&self) -> Value;
    fn listen(
        &self,
        ctx: &ToolContext<Ctx>,
        input: Value,
    ) -> impl Stream<Item = ListenToolUpdate> + Send;
    fn execute(
        &self,
        ctx: &ToolContext<Ctx>,
        operation_id: &str,
        expected_revision: u64,
    ) -> impl Future<Output = Result<ToolResult>> + Send;

    // Provided methods
    fn tier(&self) -> ToolTier { ... }
    fn cancel(
        &self,
        _ctx: &ToolContext<Ctx>,
        _operation_id: &str,
        _reason: ListenStopReason,
    ) -> impl Future<Output = Result<()>> + Send { ... }
}

Expand description

A tool whose runtime has two phases:

listen() - starts preparation and streams updates
execute() - performs final execution after confirmation

This abstraction is useful when runtime state can expire or evolve before execution (quotes, challenge windows, leases, approvals).

Ordering note: the agent loop consumes listen() updates before AgentHooks::pre_tool_use() runs. Hooks can therefore block execute(), but any side effects done during listen() have already happened.