Struct ToolContext 

pub struct ToolContext<'a> {
    pub agent_id: String,
    pub tool_call_id: String,
    pub tool_name: String,
    /* private fields */
}

Execution context made available to a running tool.

Fields

agent_id: String

tool_call_id: String

tool_name: String

Implementations

impl ToolContext<'_>

pub fn working_directory(&self) -> &Path

pub fn child_run_options(&self) -> RunOptions

RunOptions for a run this tool spawns, derived from the options of the run this tool is executing under — see RunOptions::child for what a child inherits and what it resets.

Thread these into the spawned run’s own Agent::run call. A subagent driven on RunOptions::default() instead gets a fresh, unbounded token counter, so its spend escapes the parent’s token_budget and a parent cancel, stop, or deadline never reaches it.

pub fn emit_progress(&self, progress: String)

Emit a progress event for the currently executing tool.

pub fn agent_name(&self) -> &str

pub fn model(&self) -> &str

pub fn history_len(&self) -> usize

pub fn tasks(&self) -> &[TaskItem]

pub fn resolve_working_directory( &self, working_directory: Option<&str>, ) -> Result<PathBuf, String>

pub fn load_skill(&self, name: &str) -> Result<String, String>

pub fn skill_descriptions(&self) -> Option<String>

pub fn app_context<T>(&self) -> Result<Arc<T>, String>

where T: Any + Send + Sync + 'static,

pub async fn execute_shell_command( &self, command: String, justification: Option<String>, requested_timeout: Option<Duration>, cwd: PathBuf, ) -> Result<ExecOutput, String>

Runs one command on the local executor.

pub async fn execute_shell_command_on( &self, target: Option<String>, command: String, justification: Option<String>, requested_timeout: Option<Duration>, cwd: PathBuf, ) -> Result<ExecOutput, String>

Runs one command on the executor the host named.

A tool that lets its caller say where a command runs passes the name here; None is the local executor. The name reaches the installed crate::runtime::RuntimeExecutor on the request and is interpreted only there, so a tool can route a command without gaining any way to route around the policy that authorized it.

pub fn start_background_task( &self, command: String, justification: Option<String>, requested_timeout: Option<Duration>, cwd: PathBuf, ) -> Result<BackgroundTaskSummary, String>

pub fn check_background_task( &self, task_id: Option<&str>, ) -> Result<String, String>

pub fn request_idle(&mut self)

pub async fn compact_history( &mut self, ) -> Result<Option<CompactionDetails>, RuntimeError>

pub fn execute_task_tool( &self, tool: &TaskIntrinsicTool, input: Value, ) -> Result<String, String>

pub fn refresh_tasks(&mut self) -> Result<(), RuntimeError>

pub async fn read_file( &self, path: &str, max_lines: Option<usize>, ) -> Result<String, String>

pub fn spawn_subagent(&self) -> Result<Agent, RuntimeError>

pub fn disposable_subagent_template(&self) -> DisposableSubagentTemplate

A template cloned from this agent’s own config exactly as it stands at this call — the same snapshot spawn_subagent takes when it is called — for a caller that wants to override the child’s tool profile, model, or system prompt before spawning it via spawn_subagent_from. A later change to this agent (e.g. set_model) does not reach back into a template already taken.

pub async fn spawn_subagent_from( &self, template: DisposableSubagentTemplate, ) -> Result<Agent, RuntimeError>

Spawns through the agent’s source-verifying template path.

pub fn register_subagent(&mut self, agent: &Agent) -> SpawnedAgentSummary

Records a spawned subagent and announces it on the parent’s stream.

Emitting is part of registering here, where for the task intrinsic the two are separate calls: a tool that registered a child without announcing it left the child in the parent’s snapshot and absent from every observer’s view of it, and there is no reason a caller would want that. The event is the same SubagentSpawned the intrinsic emits.

pub fn finish_subagent( &mut self, id: &str, status: SpawnedAgentStatus, ) -> Option<SpawnedAgentSummary>

Marks a subagent finished and announces it on the parent’s stream.

The other half of register_subagent. Returns None — and announces nothing — when no subagent under id was registered.

pub fn relay_subagent_usage(&self, child: &Agent) -> AgentEventTapGuard

Relays a child agent’s token usage onto this agent’s event stream.

A subagent has its own event bus, so an observer watching the parent sees none of what a delegated run spent — while that spend still counts against the parent’s token_budget. Relaying UsageReport keeps the parent’s stream summing to the same total the accounting reports.

The returned guard must outlive the child’s run: dropping it stops the relay, so binding it to _ ends it immediately.

pub fn relay_subagent_events( &self, child: &Agent, filter: impl Fn(&AgentEvent) -> bool + Send + Sync + 'static, ) -> AgentEventTapGuard

Relays the child agent’s events that filter accepts onto this agent’s stream.

The general form of relay_subagent_usage, for a tool that wants a delegated run’s tool calls or text visible to whoever is watching the parent. Relaying everything means a parent’s observer sees two interleaved runs, so the filter is the parameter rather than a default.

The returned guard must outlive the child’s run.

pub fn record_delegation_request( &mut self, content: impl Into<String>, delegation: DelegationArtifact, edge: Option<DelegationEdge>, ) -> Result<(), RuntimeError>

Records a delegation this tool performed in the parent’s transcript.

Delegation entries are what a transcript reader follows to reconstruct who asked whom for what. Only the task intrinsic could write them, so a tool that delegated work its own way left no trace of the delegation — the result appeared in the transcript with nothing saying where it came from.

pub fn record_delegation_result( &mut self, content: impl Into<String>, delegation: DelegationArtifact, edge: Option<DelegationEdge>, ) -> Result<(), RuntimeError>

Records the outcome of a delegation this tool performed.

The other half of record_delegation_request: the request says what was asked and this says what came back, and a reader following the edges needs both.

pub async fn spawn_teammate( &mut self, name: impl Into<String>, role: impl Into<String>, prompt: Option<String>, ) -> Result<TeamMemberSummary, RuntimeError>

pub fn send_team_message( &self, to: &str, content: impl Into<String>, ) -> Result<TeamDispatch, RuntimeError>

pub fn broadcast_team_message( &self, content: impl Into<String>, ) -> Result<Vec<TeamDispatch>, RuntimeError>

pub fn read_team_inbox(&self) -> Result<Vec<TeamMessage>, RuntimeError>

pub fn request_team_protocol( &self, to: &str, protocol: impl Into<String>, content: impl Into<String>, ) -> Result<TeamProtocolRequestSummary, RuntimeError>

pub fn respond_team_protocol( &self, request_id: &str, approve: bool, reason: Option<String>, ) -> Result<TeamProtocolRequestSummary, RuntimeError>

Trait Implementations

impl From<ToolContext<'_>> for ParallelToolContext

fn from(ctx: ToolContext<'_>) -> ParallelToolContext

Converts to this type from the input type.