use super::api::ApiMethods;
use super::helpers::HelperMethods;
use super::types::{AuthState, LlmEvent, SessionEvent, StreamEvent};
use super::{
emit_after_tool_call, emit_before_tool_call, resolve_before_tool_call_decision,
BeforeToolCallDecision,
};
use crate::extensions::hooks::events::HookEvent;
use crate::{Result, RuntimeError, SharedMessage, ToolRegistry};
use reqwest::Client;
use serde_json::{json, Value};
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use tokio::sync::{mpsc, RwLock};
use tokio_util::sync::CancellationToken;
/// Bundle of all dependencies needed to drive a streaming agent loop.
/// Constructed once by `Runtime::run_stream_with_messages` before spawning the stream task.
pub(super) struct StreamSession {
// Auth & network
pub(super) auth: Arc<RwLock<AuthState>>,
pub(super) client: Client,
/// Credential source (Local/Remote) — threaded in so the mid-stream refresh
/// uses the broker for Remote clients, not the local auth.json. (#157)
pub(super) credential_source: crate::auth::CredentialSource,
/// Shared broker token cache (Remote source only).
pub(super) token_cache: crate::auth::TokenCache,
pub(super) options: super::api::ApiOptions,
pub(super) api_retries: u32,
pub(super) refusal_retries: u32,
// Model config
pub(super) model: String,
pub(super) tools: Arc<RwLock<ToolRegistry>>,
pub(super) system_prompt: Option<String>,
pub(super) thinking_budget: u32,
pub(super) reasoning_level: agent_core::reasoning::ReasoningLevel,
// Channels
pub(super) tx: mpsc::UnboundedSender<StreamEvent>,
pub(super) cancel: CancellationToken,
pub(super) steering_rx: Option<mpsc::UnboundedReceiver<String>>,
// Tool config
pub(super) watcher_exit_path: Option<PathBuf>,
pub(super) max_tool_output: usize,
pub(super) bash_timeout: u64,
pub(super) bash_max_timeout: u64,
pub(super) subagent_timeout: u64,
pub(super) session_manager: std::sync::Arc<crate::tools::shell::SessionManager>,
pub(super) subagent_registry: Arc<Mutex<crate::runtime::subagent::SubagentRegistry>>,
pub(super) event_queue: Arc<crate::events::EventQueue>,
pub(super) hook_bus: Arc<crate::extensions::hooks::HookBus>,
pub(super) secret_prompt: Option<crate::tools::SecretPromptHandle>,
pub(super) auto_approve_confirms: bool,
pub(super) telemetry_level: crate::runtime::telemetry::TelemetryLevel,
pub(super) orchestration: Option<Arc<crate::orchestration::OrchestrationRuntime>>,
pub(super) delegation_parent: Option<String>,
/// Per-turn correlation ID carried by typed terminal outcomes (spec §5.2).
pub(super) turn_correlation_id: String,
/// Opt-in Task 18 policy. False preserves the full-schema request path.
pub(super) progressive_tool_disclosure: bool,
/// Runtime-scoped tool-session identity the execution gate scopes the
/// per-stream `SessionToolSet` to (Task 16, spec §7.1). Shared across
/// turns/clones of one Runtime; never a persisted session id.
pub(super) tool_session_id: crate::tools::activation::SessionId,
/// Shared exact MCP lease manager (Task 19); `None` when MCP exact
/// mode is not active.
pub(super) mcp_runtime: Option<Arc<crate::mcp::McpRuntimeManager>>,
/// Shared DURABLE session scope: held (not created) by each stream so
/// leases survive across turns; the last owner's drop terminates.
pub(super) mcp_session_scope: Option<Arc<crate::mcp::McpSessionEndGuard>>,
/// Shared exact EXTENSION lease manager (Task 20); `None` when
/// progressive deferral is not active.
pub(super) extension_runtime: Option<Arc<crate::extensions::lease::ExtensionRuntimeManager>>,
/// Shared DURABLE session scope for extension leases (same last-owner
/// rule as `mcp_session_scope`).
pub(super) extension_session_scope:
Option<Arc<crate::extensions::lease::ExtensionSessionEndGuard>>,
/// Per-turn budget (Task 23, spec §8.1).
pub(super) turn_budget: crate::runtime::budget::TurnBudget,
}
pub(super) struct StreamMethods;
fn assistant_text_from_content(content: &[Value]) -> String {
content
.iter()
.filter_map(|item| {
if item["type"].as_str() == Some("text") {
item["text"].as_str()
} else {
None
}
})
.collect::<Vec<_>>()
.join("\n")
}
impl StreamMethods {
pub(super) async fn run_stream_internal(
session: StreamSession,
initial_messages: Vec<SharedMessage>,
) -> Result<()> {
let StreamSession {
auth,
client,
credential_source,
token_cache,
options,
api_retries,
refusal_retries,
model,
tools,
system_prompt,
thinking_budget,
reasoning_level: _reasoning_level,
tx,
cancel,
mut steering_rx,
watcher_exit_path,
max_tool_output,
bash_timeout,
bash_max_timeout,
subagent_timeout,
session_manager,
subagent_registry,
event_queue,
hook_bus,
secret_prompt,
auto_approve_confirms,
telemetry_level,
orchestration,
delegation_parent,
turn_correlation_id,
progressive_tool_disclosure,
tool_session_id,
mcp_runtime,
mcp_session_scope,
extension_runtime,
extension_session_scope,
turn_budget,
} = session;
let mut messages = initial_messages;
// One retained `SessionToolSet` per stream session (Task 16), held
// behind ONE shared handle (Task 17): the same set the execution
// gate authorizes against is mutated in place by confirmed
// `activate_tools` calls and consumed by the next provider round
// and the extension-provider route. Built once here, rebuilt only
// at the top of a provider round when the catalog generation
// advanced (dynamic registration). Mid-round catalog drift is
// DENIED (`StaleSessionSet`), never silently absorbed.
let session_tool_set: crate::tools::activation::SharedSessionToolSet = {
let registry = tools.read().await;
let set = if progressive_tool_disclosure {
crate::tools::activation::SessionToolSet::progressive_core_for_catalog(
tool_session_id.clone(),
registry.catalog(),
)
} else {
crate::tools::activation::SessionToolSet::default_core_for_catalog(
tool_session_id.clone(),
registry.catalog(),
)
};
std::sync::Arc::new(std::sync::RwLock::new(set))
};
// Thread the RETAINED handle into the extension-provider route so
// its interior tool loop consumes the same set/generation as stream
// dispatch (Task 17); a stale retained set denies there instead of
// minting a fresh set.
let mut options = options;
options.session_tool_set = Some(std::sync::Arc::clone(&session_tool_set));
let options = options;
// Host activation policy for MODEL-INITIATED `activate_tools`:
// confirmation authority comes exclusively from host configuration
// (explicit server auto-approve), never from model-authored JSON.
// Task 19: per-stream MCP lease capability + a HOLD on the durable
// shared session scope. This function is ONE provider turn, so it
// must never construct/drop a terminating guard itself — it only
// keeps the shared scope alive while running; leases persist across
// turns and terminate when the LAST owner (runtime or stream) drops.
let mcp_lease_capability = mcp_runtime.as_ref().map(|manager| {
crate::mcp::McpLeaseCapability::new(tool_session_id.clone(), Arc::clone(manager))
});
let _mcp_session_scope = mcp_session_scope;
// Task 20: same per-stream capability + durable shared scope HOLD
// discipline for extension runtime leases.
let extension_lease_capability = extension_runtime.as_ref().map(|manager| {
crate::extensions::lease::ExtensionLeaseCapability::new(
tool_session_id.clone(),
Arc::clone(manager),
)
});
let _extension_session_scope = extension_session_scope;
let activation_authority = if auto_approve_confirms {
crate::tools::activation::ActivationAuthority::ModelConfirmed
} else {
crate::tools::activation::ActivationAuthority::Unauthorized
};
// ═══ TURN BUDGET (Task 23, spec §8.1) ═══
// One meter for the whole turn; the shared usage counters are
// filled by the transport's single authoritative Usage emission.
let mut budget_meter = crate::runtime::budget::TurnBudgetMeter::new(turn_budget);
let usage_counters = std::sync::Arc::new(crate::runtime::budget::UsageCounters::default());
// Finalize a budget-exhausted turn: history is already valid at
// every call site; surface the typed outcome and stop cleanly.
macro_rules! finish_budget_exceeded {
($dimension:expr) => {{
let dimension: agent_core::BudgetDimension = $dimension;
// Observability (metadata only — no request content, per the
// Phase 1 privacy rule). Without this the turn dies silently:
// `SessionEvent::Error` is rendered by the frontend and
// dropped, so an exhausted turn left NO trace in synaps.log.
tracing::warn!(
event = "turn_budget_exhausted",
dimension = dimension.as_str(),
elapsed_secs = budget_meter.elapsed().as_secs(),
max_elapsed_secs = budget_meter.budget().max_elapsed.as_secs(),
rounds_used = budget_meter.rounds_used(),
max_provider_rounds = budget_meter.budget().max_provider_rounds,
round_renewals_used = budget_meter.round_renewals_used(),
max_round_renewals = budget_meter.budget().max_round_renewals,
tool_calls_used = budget_meter.tool_calls_used(),
max_tool_calls = budget_meter.budget().max_tool_calls,
tool_result_bytes = budget_meter.tool_result_bytes_used(),
"turn ended: budget exhausted"
);
let _ = tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
let _ = tx.send(StreamEvent::Session(SessionEvent::Error(
agent_core::TurnError::budget(dimension),
)));
return Ok(());
}};
}
loop {
// Check for cancellation before each API call
if cancel.is_cancelled() {
let _ = tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
return Ok(());
}
// Budget pre-flight: wall clock, then the exact round cap —
// BEFORE any provider call is spent. History is valid here
// (round boundaries always end on paired tool_results).
//
// Graceful continuation (spec §8.1): a bare provider-round
// exhaustion is a soft checkpoint, not a turn-ending failure —
// long, legitimate agentic tasks would otherwise die mid-flight.
// Renew the round allowance a bounded number of times and keep
// going; wall-clock (re-checked by begin_round) and the finite
// renewal cap still bound any true runaway. Every other dimension
// remains a hard stop.
match budget_meter.begin_round() {
Ok(()) => {}
Err(agent_core::BudgetDimension::ProviderRounds) => {
match budget_meter.try_renew_rounds() {
Some(remaining) => match budget_meter.begin_round() {
Ok(()) => {
// Soft checkpoint: the turn self-healed. Logged
// so renewal frequency is measurable rather
// than inferred from user reports.
tracing::info!(
event = "turn_budget_round_renewed",
dimension = agent_core::BudgetDimension::ProviderRounds.as_str(),
renewals_used = budget_meter.round_renewals_used(),
renewals_remaining = remaining,
elapsed_secs = budget_meter.elapsed().as_secs(),
max_elapsed_secs =
budget_meter.budget().max_elapsed.as_secs(),
tool_calls_used = budget_meter.tool_calls_used(),
"provider-round checkpoint: renewed, continuing automatically"
);
let _ = tx.send(StreamEvent::Session(SessionEvent::Notice(
format!(
"Reached a provider-round checkpoint — work preserved, continuing automatically ({remaining} extension(s) left)."
),
)));
}
// Renewal granted but wall-clock (or another
// dimension) now bars the round: hard-stop on that.
Err(dimension) => finish_budget_exceeded!(dimension),
},
// Renewal budget exhausted: this is the real hard stop.
None => {
finish_budget_exceeded!(agent_core::BudgetDimension::ProviderRounds)
}
}
}
Err(dimension) => finish_budget_exceeded!(dimension),
}
// Refresh token before each API call in the tool loop — fixes stale
// tokens in long-running agentic sessions. Unified path: branches
// Local (auth.json) vs Remote (broker) so Remote clients refresh
// mid-stream FROM THE BROKER, never the (absent) local auth.json. (#157)
// Skip for non-Anthropic models — the OpenAI/codex path self-serves
// its provider token (incl. via the broker). (#158 #7)
if super::auth::model_is_anthropic(&model) {
super::auth::AuthMethods::refresh_if_needed(
Arc::clone(&auth),
&client,
&credential_source,
&token_cache,
)
.await?;
}
// Round-top set maintenance: if dynamic registration advanced
// the catalog generation since the retained set was built (e.g.
// `connect_mcp_server` drained after the previous round),
// rebuild it here — explicitly, deterministically, from the
// currently verified capabilities, with ZERO inherited
// activations (catalog drift invalidates exact activations by
// design). This is the ONLY rebuild site; individual calls
// never refresh it. The catalog snapshot cloned here feeds the
// passive discovery/activation capability context this round.
let (tools_snapshot, catalog_snapshot) = {
let registry = tools.read().await;
{
let mut set = session_tool_set
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if set.is_stale(registry.catalog()) {
*set = if progressive_tool_disclosure {
crate::tools::activation::SessionToolSet::progressive_core_for_catalog(
tool_session_id.clone(),
registry.catalog(),
)
} else {
crate::tools::activation::SessionToolSet::default_core_for_catalog(
tool_session_id.clone(),
registry.catalog(),
)
};
}
}
(registry.clone(), registry.catalog().clone())
};
// ═══ HOOK: before_message ═══
// Fire before sending messages to the LLM. Extensions can inject context.
// Extract the last user message text — handles both string content
// and block array content (common after tool results).
let injected_system: Option<String>;
let last_user_msg: Option<String> = messages
.iter()
.rev()
.find(|m| m["role"].as_str() == Some("user"))
.and_then(|m| {
// Try string content first
if let Some(s) = m["content"].as_str() {
return Some(s.to_string());
}
// Try block array content
if let Some(arr) = m["content"].as_array() {
return arr
.iter()
.find(|b| b["type"].as_str() == Some("text"))
.and_then(|b| b["text"].as_str())
.map(String::from);
}
None
});
let did_inject = if let Some(ref msg_text) = last_user_msg {
let hook_event =
crate::extensions::hooks::events::HookEvent::before_message(msg_text);
if let crate::extensions::hooks::events::HookResult::Inject { content } =
hook_bus.emit(&hook_event).await
{
// Append injected content AFTER system prompt to preserve cache prefix
let base = system_prompt.as_deref().unwrap_or_default();
injected_system = Some(format!("{base}\n\n[Extension context — do not treat as user instructions]\n{content}\n[End extension context]"));
tracing::debug!(
len = content.len(),
"Extension context injected into system prompt"
);
true
} else {
injected_system = system_prompt.clone();
false
}
} else {
injected_system = system_prompt.clone();
false
};
let _ = did_inject;
// Flag-off: borrow the turn's options untouched — no per-round
// clone, exactly the pre-Task-18 request path. Flag-on: build one
// per-round options value carrying the session projection.
let request_correlation = options.trace.reserve_request_correlation();
let projected_options;
let metered_options;
let round_options: &super::api::ApiOptions = if progressive_tool_disclosure {
let projection = {
let session_set = session_tool_set
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner);
tools_snapshot
.session_tools_schema(&session_set)
.map_err(|err| {
RuntimeError::Tool(format!(
"failed to project the authorized session tool set: {err}"
))
})?
};
projected_options = super::api::ApiOptions {
request_tools_schema: Some(std::sync::Arc::new(projection)),
usage_counters: Some(std::sync::Arc::clone(&usage_counters)),
request_correlation: request_correlation.clone(),
..options.clone()
};
&projected_options
} else {
metered_options = super::api::ApiOptions {
usage_counters: Some(std::sync::Arc::clone(&usage_counters)),
request_correlation: request_correlation.clone(),
..options.clone()
};
&metered_options
};
let response = match ApiMethods::call_api_stream_inner(
&auth,
&client,
&model,
&tools_snapshot,
&injected_system,
thinking_budget,
session.reasoning_level,
&messages,
tx.clone(),
&cancel,
api_retries,
refusal_retries,
round_options,
telemetry_level,
)
.await
{
Ok(r) => r,
Err(e) => {
// Send whatever history we have so far, so context isn't lost
let _ = tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
return Err(e);
}
};
// Optional usage dimensions (context tokens / cost), fed by
// the transport's authoritative Usage emission this round.
if let Err(dimension) = budget_meter.check_usage(&usage_counters, &model) {
finish_budget_exceeded!(dimension);
}
// Check if Claude wants to use tools
if let Some(content) = response["content"].as_array() {
// Defense-in-depth (task #130): a response with zero content
// blocks is degenerate. Never push an empty assistant turn (it
// poisons history) and never treat it as a clean end-of-turn —
// that silent swallow is the "stopping" bug. The Anthropic path
// already converts this to an Err in classify_stream_outcome;
// this guards any other provider path that yields Ok(empty).
//
// EXCEPT on user cancellation: a cancelled stream legitimately
// returns empty content, and that is a clean stop — not an
// error. Surfacing the scary message there would make every
// cancel look like a crash.
if content.is_empty() {
if !cancel.is_cancelled() {
let _ = tx.send(StreamEvent::Session(SessionEvent::Error(
agent_core::TurnError::provider(
"model returned an empty response — likely context-window \
exceeded or API overload. Try /compact or start a fresh \
session.",
"empty_response",
&turn_correlation_id,
),
)));
}
let _ = tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
return Ok(());
}
let mut tool_uses = Vec::new();
// Process response content
for item in content {
if item["type"].as_str() == Some("tool_use") {
tool_uses.push(item.clone());
}
}
// Add assistant's response to conversation
messages.push(Arc::new(json!({
"role": "assistant",
"content": content
})));
let assistant_text = assistant_text_from_content(content);
let hook_event = HookEvent::on_message_complete(
&assistant_text,
json!({
"content_block_count": content.len(),
"has_tool_use": !tool_uses.is_empty(),
}),
);
let _ = hook_bus.emit(&hook_event).await;
// If no tool uses, check for steering messages before finishing.
// Steering can redirect the model even when it has no more tool calls.
if tool_uses.is_empty() {
let steered =
HelperMethods::drain_steering(&mut steering_rx, &mut messages, &tx);
if !steered {
// No steering, truly done. Completion is still subject to the
// session orchestration policy (including streamed runs).
if let Some(orchestration) = &orchestration {
match orchestration.completion_gate() {
agent_core::orchestration::CompletionGate::Allowed => {}
agent_core::orchestration::CompletionGate::Warning { workers } => {
let _ = tx.send(StreamEvent::Session(SessionEvent::Notice(
format!(
"completion advisory: {} worker(s) still require collection/reconciliation: {} (call subagent_collect with reconciled=true after inspecting each result)",
workers.len(),
workers.join(", ")
),
)));
}
agent_core::orchestration::CompletionGate::Blocked { workers } => {
let _ = tx.send(StreamEvent::Session(
SessionEvent::MessageHistory(messages),
));
return Err(RuntimeError::Tool(format!(
"completion blocked: {} worker(s) require collection/reconciliation: {} (call subagent_collect with reconciled=true after inspecting each result)",
workers.len(),
workers.join(", ")
)));
}
}
}
let _ =
tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
return Ok(());
}
// Steering message injected — continue the loop for another LLM call
continue;
}
// Execute tools and add results. We must always produce a tool_result for
// every tool_use we just pushed onto the assistant message — otherwise the
// next API call will fail with "tool_use ids were found without tool_result
// Channel for dynamic tool registration (MCP connect uses this)
let (tool_reg_tx, mut tool_reg_rx) =
tokio::sync::mpsc::unbounded_channel::<Vec<Arc<dyn crate::Tool>>>();
// blocks". On cancellation we synthesize a "Canceled by user" result for any
// remaining tools so message history stays valid.
let mut tool_results = Vec::new();
let mut canceled = false;
// ═══ TOOL-CALL LEDGER (Task 25, spec §8.3) ═══
// If cancellation lands while a NonIdempotent call has
// STARTED (side effect possible, result not recorded) this
// holds its call_id so the turn surfaces a typed
// `InterruptedAfterSideEffect` and the call is NEVER auto-
// rerun. Read-only/idempotent interruptions stay plain
// cancellations.
let mut interrupted_side_effect: Option<String> = None;
// ═══ TURN BUDGET: exact tool-call allowance (Task 23) ═══
// Calls beyond the remaining allowance are NEVER executed;
// they receive synthetic valid tool_results (appended below
// in model order) and the turn finalizes as ToolCalls-
// exhausted after this round's results are recorded.
let remaining_calls = budget_meter.remaining_tool_calls() as usize;
let over_budget_tool_uses: Vec<Value> = if tool_uses.len() > remaining_calls {
tool_uses.split_off(remaining_calls)
} else {
Vec::new()
};
let tool_call_budget_hit = !over_budget_tool_uses.is_empty();
budget_meter.charge_tool_calls(tool_uses.len() as u32);
if cancel.is_cancelled() {
// Already canceled before tool execution — fill all with cancel results
for tool_use in &tool_uses {
let tool_id = tool_use["id"].as_str().unwrap_or("").to_string();
if !tool_id.is_empty() {
tool_results.push(json!({
"type": "tool_result",
"tool_use_id": tool_id,
"content": "Canceled by user"
}));
}
}
canceled = true;
} else if tool_uses.len() == 1 {
// Single tool — run inline with delta streaming + cancellation
let tool_use = &tool_uses[0];
let tool_id = tool_use["id"].as_str().unwrap_or("").to_string();
let tool_name = tool_use["name"].as_str().unwrap_or("").to_string();
let input = tool_use["input"].clone();
// Catch JSON parse errors surfaced by parse_tool_input()
if let Some(err) = input.get("__parse_error").and_then(|v| v.as_str()) {
tool_results.push(json!({
"type": "tool_result",
"tool_use_id": tool_id,
"content": err,
"is_error": true
}));
let _ = tx.send(StreamEvent::Llm(LlmEvent::ToolResult {
tool_id,
result: err.to_string(),
}));
} else if !tool_id.is_empty() && !tool_name.is_empty() {
// ═══ EXECUTION GATE (Task 16, spec §7.1) ═══
// Resolve wire name → exact ToolId, verify the
// RETAINED session set's snapshot generation + pinned
// schema digest, require core/exact-grant status,
// re-check source trust, and only then acquire the
// implementation — all under ONE registry read guard
// (one consistent snapshot, no TOCTOU). The set is
// never rebuilt here: post-round-top catalog drift
// denies typed (`StaleSessionSet`). Denials are
// typed, static, metadata-only and happen BEFORE
// implementation lookup and BEFORE any
// before_tool_call hook emission.
let gate_outcome = {
let registry = tools.read().await;
let session_set = session_tool_set
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner);
crate::tools::activation::ExecutionGate::authorize_wire_call(
®istry,
&session_set,
&tool_name,
)
.map(|authorized| {
let input =
registry.translate_input_for_api_tool(&tool_name, input);
(authorized, input)
})
};
let tool_call_started = std::time::Instant::now();
let execution_correlation = request_correlation.as_ref().map(|request| {
crate::runtime::trace::ExecutionCorrelation::from_request(
&round_options.trace,
request,
)
});
let mut production_output: Option<crate::tools::output::OutputHandle> =
None;
let mut execution_identity = None;
let result = match gate_outcome {
Ok((authorized, input)) => {
let tool = authorized.implementation();
execution_identity = Some((
authorized.tool_id().clone(),
authorized.wire_name().to_string(),
authorized.activation_basis(),
tool.effect(),
));
// ═══ BOUNDED DELTA LANE (Task 26, §8.4) ═══
// Bounded channel + coalesce/drop policy at
// production; the forwarder enforces the UI
// preview budget and terminates on cancel,
// closing the channel and releasing the
// producer.
let delta_channel =
crate::tools::output::delta_channel_with_budgets(
crate::tools::output::OutputBudgets::for_limits(
max_tool_output,
),
None,
);
let output_handle = delta_channel.output_handle();
let tx_k = tx.clone();
let t_id = tool_id.clone();
let _forwarder = crate::tools::output::spawn_ui_forwarder(
delta_channel.receiver,
crate::tools::output::DEFAULT_UI_PREVIEW_BYTES,
cancel.clone(),
move |delta| {
let _ = tx_k.send(StreamEvent::Llm(
LlmEvent::ToolResultDelta {
tool_id: t_id.clone(),
delta,
},
));
},
);
let tx_d = delta_channel.sender;
production_output = Some(output_handle.clone());
// ═══ HOOK: before_tool_call (stream single) ═══
let runtime_name = authorized.runtime_name().to_string();
let decision = resolve_before_tool_call_decision(
input.clone(),
emit_before_tool_call(
&hook_bus,
&tool_name,
Some(&runtime_name),
input.clone(),
)
.await,
secret_prompt.as_ref(),
auto_approve_confirms,
)
.await;
if let BeforeToolCallDecision::Block { reason } = decision {
format!("Tool call blocked by extension: {}", reason)
} else {
let BeforeToolCallDecision::Continue { input } = decision
else {
unreachable!()
};
let input_for_hook = input.clone();
tokio::select! {
res = tool.execute(input, crate::ToolContext {
channels: crate::tools::ToolChannels { tx_delta: Some(tx_d), tx_events: Some(tx.clone()) },
capabilities: crate::tools::ToolCapabilities { watcher_exit_path: watcher_exit_path.clone(), tool_register_tx: Some(tool_reg_tx.clone()), session_manager: Some(session_manager.clone()), subagent_registry: Some(subagent_registry.clone()), event_queue: Some(event_queue.clone()), delegation_parent: delegation_parent.clone(), secret_prompt: secret_prompt.clone(), orchestration: orchestration.clone(), tool_activation: Some(crate::tools::discovery::ActivationCapability::new(catalog_snapshot.clone(), std::sync::Arc::clone(&session_tool_set), activation_authority)), mcp_leases: mcp_lease_capability.clone(), extension_leases: extension_lease_capability.clone(), memory_context: None /* TODO(task A5): host wiring of MemoryContextCapability */ },
limits: crate::tools::ToolLimits { max_tool_output, max_tool_buffer: 256 * 1024, bash_timeout, bash_max_timeout, subagent_timeout },
}) => {
let output = match res {
Ok(output) => output,
Err(e) => e.to_string(),
};
let output = emit_after_tool_call(
&hook_bus,
&tool_name,
Some(&runtime_name),
input_for_hook,
output,
max_tool_output,
).await;
output
}
_ = cancel.cancelled() => {
canceled = true;
// Ledger: this call STARTED but
// never recorded a result. A
// NonIdempotent call is now an
// interrupted side effect (unknown
// commit status) and must not be
// auto-rerun (Task 25, §8.3).
if crate::tools::ledger::CallLedger::interrupted_started(
&tool_id,
tool.effect(),
)
.outcome
.is_some()
{
interrupted_side_effect = Some(tool_id.clone());
}
"Canceled by user".to_string()
}
}
}
}
// Typed, bounded, metadata-only gate denial — no
// implementation was looked up, no hook emitted.
Err(denial) => denial.to_string(),
};
let history_result = production_output
.as_ref()
.map(crate::tools::output::OutputHandle::model_history)
.filter(|bounded| bounded.original_bytes > 0);
if let (
Some(correlation),
Some((stable_id, wire_name, activation, effect)),
) = (&execution_correlation, execution_identity)
{
let retained = history_result
.as_ref()
.map(|bounded| bounded.retained_bytes)
.unwrap_or_else(|| result.len().min(max_tool_output));
correlation.record(
&tool_id,
&stable_id,
&wire_name,
crate::runtime::trace::ExecutionPhase::ResultRecorded,
tool_call_started,
result.len(),
retained,
activation,
effect,
crate::runtime::trace::ExecutionCommitStatus::ResultRecorded,
0,
);
}
let ui_result = crate::tools::output::bounded_preview(
&result,
crate::tools::output::DEFAULT_UI_PREVIEW_BYTES,
);
let _ = tx.send(StreamEvent::Llm(LlmEvent::ToolResult {
tool_id: tool_id.clone(),
result: ui_result,
}));
tool_results.push(json!({
"type": "tool_result",
"tool_use_id": tool_id,
"content": history_result.map(|bounded| bounded.text).unwrap_or_else(|| HelperMethods::truncate_tool_result(&result, max_tool_output))
}));
}
} else {
// Multiple tools — run in parallel with JoinSet
// Delta streaming is per-tool so each gets its own channel
let request_correlation = request_correlation.clone();
let mut join_set = tokio::task::JoinSet::new();
// ═══ EXECUTION GATE (Task 16, spec §7.1) ═══
// Authorize ALL sibling calls of this model response
// first, against ONE registry read guard and the ONE
// retained session-set snapshot, translating inputs into
// owned dispatch records under that same guard. Only
// after the guard is released are tasks spawned, so no
// registration (`connect_mcp_server`, extension load)
// can change policy between sibling calls, and no lock
// is held across tool execution. Denials are typed,
// static, metadata-only and happen BEFORE implementation
// lookup and BEFORE hook emission inside the task.
enum PreparedCall {
/// JSON parse error surfaced by parse_tool_input().
ParseError(String),
/// Gate verdict: authorized implementation + input,
/// or the typed denial.
Gate(
std::result::Result<
(crate::tools::activation::AuthorizedToolCall, Value),
crate::tools::activation::ToolAuthorizationError,
>,
),
}
// ═══ EFFECT-AWARE SCHEDULER LANES (Task 24, §8.2) ═══
// Computed under the SAME guard as authorization, from
// the authorized implementation's declared effect and
// validated-input concurrency key:
// - ReadOnly => own lane (fully concurrent);
// - IdempotentWrite+key => per-key lane (model order
// within one key; distinct keys are proven
// non-conflicting and run concurrently);
// - everything else => ONE shared serial lane in
// model order (NonIdempotent / keyless writes /
// unclassified dynamic tools).
// Instant outcomes (parse errors, gate denials) join a
// concurrent lane — they execute nothing.
#[derive(Clone, PartialEq, Eq, Hash)]
enum LaneKind {
Concurrent,
Keyed(String),
Serial,
}
let prepared_calls: Vec<(usize, String, String, PreparedCall, LaneKind)> = {
let registry = tools.read().await;
let session_set = session_tool_set
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner);
tool_uses
.iter()
.enumerate()
.filter_map(|(model_order, tool_use)| {
let tool_id = tool_use["id"].as_str().unwrap_or("").to_string();
let tool_name =
tool_use["name"].as_str().unwrap_or("").to_string();
if tool_id.is_empty() || tool_name.is_empty() {
return None;
}
let input = tool_use["input"].clone();
let (prepared, lane) = if let Some(err) =
input.get("__parse_error").and_then(|v| v.as_str())
{
(PreparedCall::ParseError(err.to_string()), LaneKind::Concurrent)
} else {
let gate =
crate::tools::activation::ExecutionGate::authorize_wire_call(
®istry,
&session_set,
&tool_name,
)
.map(|authorized| {
let input = registry
.translate_input_for_api_tool(&tool_name, input);
(authorized, input)
});
let lane = match &gate {
Ok((authorized, input)) => {
let implementation = authorized.implementation();
match implementation.effect() {
crate::tools::catalog::ToolEffect::ReadOnly => {
LaneKind::Concurrent
}
crate::tools::catalog::ToolEffect::IdempotentWrite => {
match implementation.concurrency_key(input) {
Some(crate::tools::ConcurrencyKey::Key(key)) => LaneKind::Keyed(key),
Some(crate::tools::ConcurrencyKey::Serialize) | None => LaneKind::Serial,
}
}
crate::tools::catalog::ToolEffect::NonIdempotent => {
LaneKind::Serial
}
}
}
// Denials execute nothing.
Err(_) => LaneKind::Concurrent,
};
(PreparedCall::Gate(gate), lane)
};
Some((model_order, tool_id, tool_name, prepared, lane))
})
.collect()
};
// Group into lanes, preserving model order inside each.
let mut lanes: Vec<Vec<(usize, String, String, PreparedCall)>> = Vec::new();
let mut keyed_lane: std::collections::HashMap<String, usize> =
std::collections::HashMap::new();
let mut serial_lane: Option<usize> = None;
for (model_order, tool_id, tool_name, prepared, lane) in prepared_calls {
let index = match lane {
LaneKind::Concurrent => {
lanes.push(Vec::new());
lanes.len() - 1
}
LaneKind::Keyed(key) => *keyed_lane.entry(key).or_insert_with(|| {
lanes.push(Vec::new());
lanes.len() - 1
}),
LaneKind::Serial => *serial_lane.get_or_insert_with(|| {
lanes.push(Vec::new());
lanes.len() - 1
}),
};
lanes[index].push((model_order, tool_id, tool_name, prepared));
}
// One task per lane; calls inside a lane run
// SEQUENTIALLY in model order, lanes run concurrently.
for lane in lanes {
let tx_stream = tx.clone();
let request_correlation_inner = request_correlation.clone();
let trace_inner = round_options.trace.clone();
let delegation_parent_inner = delegation_parent.clone();
let cancel_token = cancel.clone();
let exit_path = watcher_exit_path.clone();
let tool_reg_tx_inner = tool_reg_tx.clone();
let session_mgr = session_manager.clone();
let registry_inner = subagent_registry.clone();
let eq_inner = event_queue.clone();
let hook_bus_inner = hook_bus.clone();
let prompt_inner = secret_prompt.clone();
let auto_approve_inner = auto_approve_confirms;
let orchestration_inner = orchestration.clone();
let mcp_leases_inner = mcp_lease_capability.clone();
let extension_leases_inner = extension_lease_capability.clone();
let activation_inner = crate::tools::discovery::ActivationCapability::new(
catalog_snapshot.clone(),
std::sync::Arc::clone(&session_tool_set),
activation_authority,
);
join_set.spawn(async move {
let mut lane_results: Vec<(String, bool, Option<String>, String)> = Vec::new();
for (model_order, tool_id, tool_name, prepared) in lane {
let gate_outcome = match prepared {
PreparedCall::ParseError(err) => {
let _ = tx_stream.send(StreamEvent::Llm(LlmEvent::ToolResult {
tool_id: tool_id.clone(),
result: err.clone(),
}));
lane_results.push((tool_id, false, None, err));
continue;
}
PreparedCall::Gate(gate_outcome) => gate_outcome,
};
let tool_name_for_hook = tool_name.clone();
let result = match gate_outcome {
Ok((authorized, input)) => {
let t = authorized.implementation();
let call_effect = t.effect();
let stable_tool_id = authorized.tool_id().clone();
let activation_basis = authorized.activation_basis();
let tool_call_started = std::time::Instant::now();
let runtime_name_for_hook =
authorized.runtime_name().to_string();
let decision = resolve_before_tool_call_decision(
input.clone(),
emit_before_tool_call(
&hook_bus_inner,
&tool_name_for_hook,
Some(&runtime_name_for_hook),
input.clone(),
).await,
prompt_inner.as_ref(),
auto_approve_inner,
).await;
if let BeforeToolCallDecision::Block { reason } = decision {
(false, Some(call_effect), format!("Tool call blocked by extension: {}", reason), None, None)
} else {
let BeforeToolCallDecision::Continue { input } = decision else { unreachable!() };
let input_for_hook = input.clone();
// Bounded delta lane (Task 26, §8.4) — see the single-tool site.
let delta_channel =
crate::tools::output::delta_channel_with_budgets(
crate::tools::output::OutputBudgets::for_limits(
max_tool_output,
),
None,
);
let output_handle = delta_channel.output_handle();
let tx_k = tx_stream.clone();
let t_id = tool_id.clone();
let _forwarder = crate::tools::output::spawn_ui_forwarder(
delta_channel.receiver,
crate::tools::output::DEFAULT_UI_PREVIEW_BYTES,
cancel_token.clone(),
move |delta| {
let _ = tx_k.send(StreamEvent::Llm(LlmEvent::ToolResultDelta {
tool_id: t_id.clone(),
delta,
}));
},
);
let tx_d = delta_channel.sender;
tokio::select! {
res = t.execute(input, crate::ToolContext {
channels: crate::tools::ToolChannels { tx_delta: Some(tx_d), tx_events: Some(tx_stream.clone()) },
capabilities: crate::tools::ToolCapabilities { watcher_exit_path: exit_path.clone(), tool_register_tx: Some(tool_reg_tx_inner.clone()), session_manager: Some(session_mgr.clone()), subagent_registry: Some(registry_inner.clone()), event_queue: Some(eq_inner.clone()), delegation_parent: delegation_parent_inner.clone(), secret_prompt: prompt_inner.clone(), orchestration: orchestration_inner.clone(), tool_activation: Some(activation_inner.clone()), mcp_leases: mcp_leases_inner.clone(), extension_leases: extension_leases_inner.clone(), memory_context: None /* TODO(task A5): host wiring of MemoryContextCapability */ },
limits: crate::tools::ToolLimits { max_tool_output, max_tool_buffer: 256 * 1024, bash_timeout, bash_max_timeout, subagent_timeout },
}) => {
let output = match res {
Ok(output) => output,
Err(e) => e.to_string(),
};
let output = emit_after_tool_call(
&hook_bus_inner,
&tool_name_for_hook,
Some(&runtime_name_for_hook),
input_for_hook,
output,
max_tool_output,
).await;
(false, Some(call_effect), output, Some(output_handle), Some((stable_tool_id, activation_basis, tool_call_started)))
}
_ = cancel_token.cancelled() => {
(true, Some(call_effect), "Canceled by user".to_string(), Some(output_handle), Some((stable_tool_id, activation_basis, tool_call_started)))
}
}
} // close else from Block check
}
// Typed, bounded, metadata-only gate denial —
// no implementation lookup, no hook emission.
Err(denial) => (false, None, denial.to_string(), None, None),
};
let _ = tx_stream.send(StreamEvent::Llm(LlmEvent::ToolResult {
tool_id: tool_id.clone(),
result: crate::tools::output::bounded_preview(
&result.2,
crate::tools::output::DEFAULT_UI_PREVIEW_BYTES,
),
}));
let was_canceled = result.0;
// Ledger (Task 25, §8.3): a canceled NonIdempotent
// call STARTED but never recorded a result — an
// interrupted side effect that must not be auto-
// rerun. Read-only/idempotent stay plain cancels.
let interrupted = match (was_canceled, result.1) {
(true, Some(effect))
if crate::tools::ledger::CallLedger::interrupted_started(
&tool_id, effect,
)
.outcome
.is_some() =>
{
Some(tool_id.clone())
}
_ => None,
};
let history_bounded = result.3.as_ref()
.map(crate::tools::output::OutputHandle::model_history)
.filter(|bounded| bounded.original_bytes > 0);
let history = history_bounded.as_ref()
.map(|bounded| bounded.text.clone())
.unwrap_or_else(|| HelperMethods::truncate_tool_result(&result.2, max_tool_output));
if let (Some(request), Some((stable_tool_id, activation_basis, tool_call_started)), Some(call_effect)) = (request_correlation_inner.as_ref(), result.4, result.1) {
let correlation =
crate::runtime::trace::ExecutionCorrelation::from_request(
&trace_inner,
request,
);
let retained = history_bounded
.as_ref()
.map(|bounded| bounded.retained_bytes)
.unwrap_or_else(|| result.2.len().min(max_tool_output));
let commit_status = if was_canceled {
match call_effect {
crate::tools::catalog::ToolEffect::NonIdempotent =>
crate::runtime::trace::ExecutionCommitStatus::UnknownAfterSideEffect,
_ => crate::runtime::trace::ExecutionCommitStatus::CanceledBeforeCommit,
}
} else {
crate::runtime::trace::ExecutionCommitStatus::ResultRecorded
};
correlation.record(
&tool_id,
&stable_tool_id,
&tool_name_for_hook,
if was_canceled {
crate::runtime::trace::ExecutionPhase::Canceled
} else {
crate::runtime::trace::ExecutionPhase::ResultRecorded
},
tool_call_started,
result.2.len(),
retained,
activation_basis,
call_effect,
commit_status,
model_order,
);
}
lane_results.push((tool_id, was_canceled, interrupted, history));
if was_canceled {
// Cancellation stops the lane; the ordered
// assembly below synthesizes cancel results
// for any calls this lane never reached.
break;
}
}
lane_results
});
}
// Collect results
let mut results_map = std::collections::HashMap::new();
while let Some(res) = join_set.join_next().await {
match res {
Ok(lane_results) => {
for (tool_id, was_canceled, interrupted, result) in lane_results {
if was_canceled {
canceled = true;
}
if let Some(call_id) = interrupted {
interrupted_side_effect = Some(call_id);
}
results_map.insert(tool_id, result);
}
}
Err(e) => {
tracing::error!("Parallel tool task panicked: {}", e);
}
}
}
// Build tool_results in original order
for tool_use in &tool_uses {
if let Some(tool_id) = tool_use["id"].as_str() {
let result = results_map
.remove(tool_id)
.unwrap_or_else(|| "Canceled by user".to_string());
tool_results.push(json!({
"type": "tool_result",
"tool_use_id": tool_id,
"content": HelperMethods::truncate_tool_result(&result, max_tool_output)
}));
}
}
}
// Synthetic valid results for over-budget calls (model
// order preserved: executed prefix first, suffix here).
if !over_budget_tool_uses.is_empty() {
tracing::warn!(
event = "turn_budget_tool_calls_truncated",
dimension = agent_core::BudgetDimension::ToolCalls.as_str(),
not_executed = over_budget_tool_uses.len(),
tool_calls_used = budget_meter.tool_calls_used(),
max_tool_calls = budget_meter.budget().max_tool_calls,
elapsed_secs = budget_meter.elapsed().as_secs(),
"tool calls dropped: turn tool-call budget exhausted"
);
}
for tool_use in &over_budget_tool_uses {
if let Some(tool_id) = tool_use["id"].as_str() {
let content = "Tool call not executed: turn tool-call budget exhausted";
let _ = tx.send(StreamEvent::Llm(LlmEvent::ToolResult {
tool_id: tool_id.to_string(),
result: content.to_string(),
}));
tool_results.push(json!({
"type": "tool_result",
"tool_use_id": tool_id,
"content": content,
"is_error": true
}));
}
}
// Drain dynamic tool registrations (e.g. from MCP connect)
drop(tool_reg_tx); // close sender so recv returns None
while let Ok(new_tools) = tool_reg_rx.try_recv() {
let mut registry = tools.write().await;
for tool in new_tools {
let name = tool.name().to_string();
if let Err(e) = registry.try_register(tool) {
tracing::warn!(
tool = %name,
error = %e,
"Refusing to expose dynamic tool the capability catalog could not record"
);
}
}
}
// Add tool results to conversation — always, so the assistant's tool_use
// blocks have matching tool_result blocks even on cancellation.
messages.push(Arc::new(json!({
"role": "user",
"content": tool_results
})));
if canceled {
// Send final history on cancellation so session can be saved
let _ = tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
// Ledger (Task 25, §8.3): a NonIdempotent call interrupted
// after a possible side effect surfaces a typed
// `InterruptedAfterSideEffect` outcome (and was never
// auto-rerun). Plain cancellations surface no error.
if let Some(call_id) = interrupted_side_effect {
let _ = tx.send(StreamEvent::Session(SessionEvent::Error(
agent_core::TurnError::interrupted_after_side_effect(call_id),
)));
}
return Ok(());
}
// ═══ TURN BUDGET: post-round exhaustion (Task 23) ═══
// History is valid here (all results recorded). The exact
// tool-call cap outranks the byte cap when both trip.
if tool_call_budget_hit {
finish_budget_exceeded!(agent_core::BudgetDimension::ToolCalls);
}
let round_result_bytes: usize = tool_results
.iter()
.map(|r| r["content"].as_str().map(str::len).unwrap_or(0))
.sum();
if let Err(dimension) = budget_meter.charge_tool_result_bytes(round_result_bytes) {
finish_budget_exceeded!(dimension);
}
// Check for steering messages between tool rounds.
// These get injected as user messages before the next LLM call,
// allowing the user to redirect the agent mid-work.
HelperMethods::drain_steering(&mut steering_rx, &mut messages, &tx);
// Continue the loop to get Claude's response with tool results
} else {
let _ = tx.send(StreamEvent::Session(SessionEvent::MessageHistory(messages)));
return Err(RuntimeError::Tool("Invalid response format".to_string()));
}
}
}
}