Skip to main content

claude_code_agent/
agent.rs

1//! Agent layer — sends a turn and returns a streaming event iterator.
2//!
3//! Control requests (hook callbacks, `can_use_tool`) are answered by the
4//! `Session` itself; this layer only turns frames into `AgentEvent`s.
5//! `prompt` yields the events of one turn; `watch` yields every turn's,
6//! including the turns the CLI starts on its own.
7use std::pin::Pin;
8use std::sync::Arc;
9
10use crate::protocol::{
11    AssistantBlock, BackgroundTask, InboundMessage, InboundUserMessage, ResultMessage, TurnErrorKind,
12    UserMessage,
13};
14use crate::session::{Session, SessionError};
15
16// ─── Event stream ─────────────────────────────────────────────────────────────
17
18/// One event of a turn, translated from the CLI's stdout frames.
19#[derive(Debug, Clone)]
20#[non_exhaustive]
21pub enum AgentEvent {
22    /// A text delta (requires --include-partial-messages OR full assistant message).
23    Text(String),
24    /// A complete thinking block.
25    Thinking(String),
26    /// Encrypted thinking, opaque to the host.
27    RedactedThinking(String),
28    /// A tool call: one the CLI runs, or one the API runs itself
29    /// (`server: true`, e.g. web search).
30    ToolUse {
31        /// Tool call id; matches `ToolResult::tool_use_id`.
32        id: String,
33        /// Tool name.
34        name: String,
35        /// Tool input, as the model wrote it.
36        input: serde_json::Value,
37        /// `true` for a server tool call (`server_tool_use` block).
38        server: bool,
39    },
40    /// The result of a tool call. `content` is a string or content blocks,
41    /// as sent to the model; `structured` is the tool's full output when
42    /// the CLI reports one (e.g. Bash `{stdout, stderr, interrupted, …}`).
43    ToolResult {
44        /// Id of the `ToolUse` this result answers.
45        tool_use_id: String,
46        /// Result sent to the model: a string or content blocks.
47        content: serde_json::Value,
48        /// The tool call failed.
49        is_error: bool,
50        /// The tool's full output (`tool_use_result`), when reported.
51        structured: Option<serde_json::Value>,
52    },
53    /// An event of a subagent, started by the `Agent`/`Task` tool call
54    /// `parent_tool_use_id`.
55    Subagent {
56        /// Id of the `Agent`/`Task` tool call that started the subagent.
57        parent_tool_use_id: String,
58        /// The subagent's event.
59        event: Box<AgentEvent>,
60    },
61    /// Background task tree updated (replace semantics).
62    BackgroundTasks(Vec<BackgroundTask>),
63    /// Model was switched during the turn.
64    ModelFallback {
65        /// Model before the switch (`original_model`).
66        from: String,
67        /// Model after the switch (`fallback_model`).
68        to: String,
69        /// The frame's `trigger` field.
70        trigger: String,
71    },
72    /// Context was compacted (`trigger`: "manual" for /compact, "auto").
73    Compacted {
74        /// "manual" or "auto".
75        trigger: String,
76        /// Context tokens before compaction.
77        pre_tokens: Option<u64>,
78        /// Context tokens after compaction.
79        post_tokens: Option<u64>,
80    },
81    /// Any other `system` frame (`init`, `api_retry`, `task_started`,
82    /// `hook_response`, `permission_denied`, `status`, …), verbatim.
83    System {
84        /// The frame's `subtype`.
85        subtype: String,
86        /// The whole frame.
87        data: serde_json::Value,
88    },
89    /// Any other frame (`rate_limit_event`, `tool_progress`,
90    /// `prompt_suggestion`, `command_lifecycle`, …), verbatim.
91    Other {
92        /// The frame's `type`.
93        kind: String,
94        /// The whole frame.
95        data: serde_json::Value,
96    },
97    /// Turn completed successfully.
98    Done(TurnResult),
99    /// Turn failed.
100    Error(TurnError),
101}
102
103/// Outcome of a finished turn, from its `result` frame.
104#[derive(Debug, Clone, PartialEq)]
105#[non_exhaustive]
106pub struct TurnResult {
107    /// Session id the CLI reported.
108    pub session_id: Option<String>,
109    /// Final text of the turn.
110    pub result: Option<String>,
111    /// Output matching `Initialize::json_schema`.
112    pub structured_output: Option<serde_json::Value>,
113    /// Cost in USD (`total_cost_usd`).
114    pub total_cost_usd: Option<f64>,
115    /// Time to first token, in milliseconds (`ttft_ms`).
116    pub ttft_ms: Option<u64>,
117    /// Wall-clock duration of the turn, in milliseconds (`duration_ms`).
118    pub duration_ms: Option<u64>,
119    /// Time spent in API calls, in milliseconds (`duration_api_ms`).
120    pub duration_api_ms: Option<u64>,
121    /// Agentic turns (model calls) the turn took.
122    pub num_turns: Option<u64>,
123    /// `usage.input_tokens`.
124    pub input_tokens: Option<u64>,
125    /// `usage.output_tokens`.
126    pub output_tokens: Option<u64>,
127    /// `usage.cache_read_input_tokens`.
128    pub cache_read_input_tokens: Option<u64>,
129    /// `usage.cache_creation_input_tokens`.
130    pub cache_creation_input_tokens: Option<u64>,
131    /// Per-model token and cost breakdown.
132    pub model_usage: Option<serde_json::Value>,
133    /// `stop_reason` of the `result` frame.
134    pub stop_reason: Option<String>,
135    /// Why the agent loop ended (`terminal_reason`, e.g. "completed").
136    pub terminal_reason: Option<String>,
137    /// Tool calls the permission system denied.
138    pub permission_denials: Vec<serde_json::Value>,
139    /// Set when the CLI started the turn itself (e.g. after a background
140    /// task finished); `None` for prompted turns.
141    pub origin: Option<serde_json::Value>,
142}
143
144impl From<&ResultMessage> for TurnResult {
145    fn from(r: &ResultMessage) -> Self {
146        let usage = r.usage.as_ref();
147        TurnResult {
148            session_id: r.session_id.clone(),
149            result: r.result.clone(),
150            structured_output: r.structured_output.clone(),
151            total_cost_usd: r.total_cost_usd,
152            ttft_ms: r.ttft_ms,
153            duration_ms: r.duration_ms,
154            duration_api_ms: r.duration_api_ms,
155            num_turns: r.num_turns,
156            input_tokens: usage.map(|u| u.input_tokens),
157            output_tokens: usage.map(|u| u.output_tokens),
158            cache_read_input_tokens: usage.and_then(|u| u.cache_read_input_tokens),
159            cache_creation_input_tokens: usage.and_then(|u| u.cache_creation_input_tokens),
160            model_usage: r.model_usage.clone(),
161            stop_reason: r.stop_reason.clone(),
162            terminal_reason: r.terminal_reason.clone(),
163            permission_denials: r.permission_denials.clone(),
164            origin: r.origin.clone(),
165        }
166    }
167}
168
169/// Why a turn failed. `result` carries cost and usage up to the failure.
170#[derive(Debug, Clone, PartialEq, thiserror::Error)]
171#[error("{message}")]
172#[non_exhaustive]
173pub struct TurnError {
174    /// Failure category.
175    pub kind: TurnErrorKind,
176    /// Human-readable error message.
177    pub message: String,
178    /// Usage up to the failure; `None` when the turn never ran or the
179    /// session closed.
180    pub result: Option<TurnResult>,
181}
182
183impl From<&ResultMessage> for TurnError {
184    fn from(r: &ResultMessage) -> Self {
185        TurnError { kind: r.error_kind(), message: r.error_message(), result: Some(TurnResult::from(r)) }
186    }
187}
188
189impl TurnError {
190    fn cancelled() -> Self {
191        TurnError { kind: TurnErrorKind::Cancelled, message: "prompt cancelled before it ran".into(), result: None }
192    }
193
194    fn session_closed() -> Self {
195        TurnError {
196            kind: TurnErrorKind::SessionClosed,
197            message: "session closed before the turn finished".into(),
198            result: None,
199        }
200    }
201}
202
203/// Error starting a turn.
204#[derive(Debug, thiserror::Error)]
205#[non_exhaustive]
206pub enum AgentError {
207    /// The session failed to send the prompt.
208    #[error("session error: {0}")]
209    Session(#[from] SessionError),
210    /// The CLI does not offer this slash command, e.g. with
211    /// `SessionOptions::disable_slash_commands`.
212    #[error("the CLI does not offer /{0}")]
213    CommandUnavailable(String),
214}
215
216/// Events of one turn; ends after `Done` or `Error`. Dropping it before
217/// then cancels the turn (see `Agent::prompt_message`).
218pub type AgentStream = Pin<Box<dyn tokio_stream::Stream<Item = AgentEvent> + Send + 'static>>;
219
220// ─── Agent ────────────────────────────────────────────────────────────────────
221
222/// Runs turns on a Session.
223pub struct Agent {
224    session: Session,
225}
226
227impl Agent {
228    /// Wrap `session`.
229    #[must_use]
230    pub fn new(session: Session) -> Self {
231        Self { session }
232    }
233
234    /// The underlying session.
235    #[must_use]
236    pub fn session(&self) -> &Session {
237        &self.session
238    }
239
240    /// Run a text prompt and return a streaming iterator of `AgentEvents`.
241    ///
242    /// The stream ends after a `Done` or `Error` event.
243    pub async fn prompt(&self, text: impl Into<String>) -> Result<AgentStream, AgentError> {
244        self.prompt_message(UserMessage::text(text.into())).await
245    }
246
247    /// Run a prompt built from content blocks (text, images, …).
248    ///
249    /// Dropping the stream before its `Done`/`Error` cancels the prompt:
250    /// still queued, it is withdrawn; running, its turn is interrupted.
251    /// Drain the stream to let the turn finish.
252    pub async fn prompt_message(&self, message: UserMessage) -> Result<AgentStream, AgentError> {
253        // Subscribe before sending so no frame of this turn is missed.
254        let mut rx = self.session.subscribe();
255        let uuid = message.uuid.clone();
256        self.session.send_prompt(&message).await?;
257        // With partial messages on, text already streamed as deltas; the
258        // complete assistant message would repeat it.
259        let partial = self.session.include_partial();
260        // Lives as long as the stream: its duration is the turn's duration.
261        let span = tracing::info_span!(
262            "claude.turn",
263            session_id = self.session.session_id().unwrap_or_default(),
264            cost_usd = tracing::field::Empty,
265            input_tokens = tracing::field::Empty,
266            output_tokens = tracing::field::Empty,
267            ttft_ms = tracing::field::Empty,
268            error = tracing::field::Empty,
269        );
270
271        // Created outside the generator: a stream dropped before its first
272        // poll still cancels. It also keeps the session alive until the turn
273        // ends, even when the Agent and every other handle are dropped first.
274        let mut guard = CancelOnDrop { session: self.session.clone(), uuid: uuid.clone(), armed: true };
275        let stream = async_stream::stream! {
276            // Turns run one after another and each ends with a `result`. Our
277            // prompt's echo falls inside our turn: first for a normal prompt,
278            // last for a slash command (after e.g. compact_boundary). So frames
279            // since the previous `result` are held until the echo shows whose
280            // turn they are. A `result` before our echo closes someone else's
281            // turn (a queued prompt, or one the CLI started itself) unless it
282            // names our prompt (a prompt refused up front is never echoed).
283            let mut started = false;
284            let mut held: Vec<Arc<InboundMessage>> = vec![];
285            loop {
286                let Some(msg) = rx.recv().await else {
287                    guard.disarm();
288                    yield AgentEvent::Error(TurnError::session_closed());
289                    break;
290                };
291                // Withdrawn before it ran (`cancel_prompt`, `interrupt_all`):
292                // no `result` will come.
293                if let InboundMessage::Other(frame) = msg.as_ref()
294                    && is_cancelled(frame, &uuid)
295                {
296                    guard.disarm();
297                    yield AgentEvent::Error(TurnError::cancelled());
298                    break;
299                }
300
301                if !started {
302                    match msg.as_ref() {
303                        InboundMessage::User(u) if u.uuid.as_deref().is_some_and(|u| u.eq_ignore_ascii_case(&uuid)) => {
304                            started = true;
305                            for m in held.drain(..) {
306                                for ev in to_events(&m, partial) {
307                                    yield ev;
308                                }
309                            }
310                        }
311                        // Refused before it started: no echo, but the
312                        // result names our prompt. The held frames are ours.
313                        InboundMessage::Result(r) if r.answers(&uuid) => {
314                            started = true;
315                            for m in held.drain(..) {
316                                for ev in to_events(&m, partial) {
317                                    yield ev;
318                                }
319                            }
320                        }
321                        InboundMessage::Result(_) => {
322                            held.clear();
323                            continue;
324                        }
325                        _ => {
326                            held.push(msg);
327                            continue;
328                        }
329                    }
330                    if !matches!(msg.as_ref(), InboundMessage::Result(_)) {
331                        continue;
332                    }
333                }
334
335                if let InboundMessage::Result(r) = msg.as_ref() {
336                    guard.disarm();
337                    let t = TurnResult::from(r);
338                    if let Some(v) = t.total_cost_usd { span.record("cost_usd", v); }
339                    if let Some(v) = t.input_tokens { span.record("input_tokens", v); }
340                    if let Some(v) = t.output_tokens { span.record("output_tokens", v); }
341                    if let Some(v) = t.ttft_ms { span.record("ttft_ms", v); }
342                    if !r.is_success() { span.record("error", r.subtype.as_str()); }
343                }
344                let done = matches!(msg.as_ref(), InboundMessage::Result(_));
345                for ev in to_events(&msg, partial) {
346                    yield ev;
347                }
348                if done {
349                    break;
350                }
351            }
352        };
353
354        Ok(Box::pin(stream))
355    }
356
357    /// Every event of every turn from now on — prompted turns and the turns
358    /// the CLI starts itself (`TurnResult::origin` set), each ending with
359    /// `Done` or `Error`. Ends when the session closes. Dropping it cancels
360    /// nothing. Lossless like `Session::subscribe`: events buffer until
361    /// polled, so poll it or drop it.
362    pub fn watch(&self) -> AgentStream {
363        let mut rx = self.session.subscribe();
364        let partial = self.session.include_partial();
365        Box::pin(async_stream::stream! {
366            while let Some(msg) = rx.recv().await {
367                for ev in to_events(&msg, partial) {
368                    yield ev;
369                }
370            }
371        })
372    }
373}
374
375/// Cancels the prompt `uuid` unless disarmed (its turn ended).
376struct CancelOnDrop {
377    session: Session,
378    uuid: String,
379    armed: bool,
380}
381
382impl CancelOnDrop {
383    fn disarm(&mut self) {
384        self.armed = false;
385    }
386}
387
388impl Drop for CancelOnDrop {
389    fn drop(&mut self) {
390        if !self.armed || !self.session.is_alive() {
391            return;
392        }
393        let Ok(rt) = tokio::runtime::Handle::try_current() else {
394            tracing::warn!("turn stream dropped outside a Tokio runtime; the turn keeps running");
395            return;
396        };
397        let session = self.session.clone();
398        let uuid = std::mem::take(&mut self.uuid);
399        rt.spawn(async move {
400            if let Err(e) = session.cancel_prompt(&uuid).await {
401                tracing::debug!(error = %e, "cancelling a dropped turn failed");
402            }
403        });
404    }
405}
406
407/// The `AgentEvents` one frame produces. `partial`: text arrives as stream
408/// deltas, so complete main-thread text is skipped. Frames of subagents
409/// (`parent_tool_use_id` set) are wrapped in `AgentEvent::Subagent`; their
410/// text comes from complete messages only.
411fn to_events(msg: &InboundMessage, partial: bool) -> Vec<AgentEvent> {
412    match msg {
413        InboundMessage::Assistant(a) => {
414            let sub = a.parent_tool_use_id.is_some();
415            let events = a.message.content.iter().filter_map(|block| match block {
416                AssistantBlock::Text { text } if sub || !partial => Some(AgentEvent::Text(text.clone())),
417                AssistantBlock::Thinking { thinking } if sub || !partial => {
418                    Some(AgentEvent::Thinking(thinking.clone()))
419                }
420                AssistantBlock::RedactedThinking { data } => Some(AgentEvent::RedactedThinking(data.clone())),
421                AssistantBlock::ToolUse { id, name, input } => Some(AgentEvent::ToolUse {
422                    id: id.clone(),
423                    name: name.clone(),
424                    input: input.clone(),
425                    server: false,
426                }),
427                AssistantBlock::ServerToolUse { id, name, input } => Some(AgentEvent::ToolUse {
428                    id: id.clone(),
429                    name: name.clone(),
430                    input: input.clone(),
431                    server: true,
432                }),
433                AssistantBlock::WebSearchToolResult { tool_use_id, content } => Some(AgentEvent::ToolResult {
434                    tool_use_id: tool_use_id.clone(),
435                    content: content.clone(),
436                    is_error: false,
437                    structured: None,
438                }),
439                _ => None,
440            });
441            in_thread(a.parent_tool_use_id.as_deref(), events.collect())
442        }
443
444        InboundMessage::User(u) => in_thread(u.parent_tool_use_id.as_deref(), tool_results(u)),
445
446        InboundMessage::StreamEvent(se) if se.parent_tool_use_id.is_none() => {
447            let delta = se.event.get("delta");
448            let text = delta.and_then(|d| d.get("text")).and_then(|t| t.as_str());
449            let thinking = delta.and_then(|d| d.get("thinking")).and_then(|t| t.as_str());
450            text.map(|t| AgentEvent::Text(t.to_string()))
451                .into_iter()
452                .chain(thinking.map(|t| AgentEvent::Thinking(t.to_string())))
453                .collect()
454        }
455
456        InboundMessage::System(s) => match s.subtype.as_str() {
457            "background_tasks_changed" => {
458                let tasks = s.extra.get("tasks").cloned().unwrap_or_default();
459                match serde_json::from_value::<Vec<BackgroundTask>>(tasks) {
460                    Ok(tasks) => vec![AgentEvent::BackgroundTasks(tasks)],
461                    Err(e) => {
462                        tracing::debug!(error = %e, "undecodable background_tasks_changed");
463                        vec![]
464                    }
465                }
466            }
467            "model_fallback" => {
468                let field = |k: &str| s.extra.get(k).and_then(|v| v.as_str()).unwrap_or("").to_string();
469                vec![AgentEvent::ModelFallback {
470                    from: field("original_model"),
471                    to: field("fallback_model"),
472                    trigger: field("trigger"),
473                }]
474            }
475            "compact_boundary" => {
476                let meta = s.extra.get("compact_metadata");
477                let num = |k: &str| meta.and_then(|m| m.get(k)).and_then(serde_json::Value::as_u64);
478                vec![AgentEvent::Compacted {
479                    trigger: meta.and_then(|m| m.get("trigger")).and_then(|v| v.as_str()).unwrap_or("").to_string(),
480                    pre_tokens: num("pre_tokens"),
481                    post_tokens: num("post_tokens"),
482                }]
483            }
484            other => vec![AgentEvent::System {
485                subtype: other.to_string(),
486                data: serde_json::to_value(s).unwrap_or_else(|e| {
487                    tracing::warn!(error = %e, "could not serialize a system frame");
488                    serde_json::Value::Null
489                }),
490            }],
491        },
492
493        InboundMessage::Other(data) => vec![AgentEvent::Other {
494            kind: data.get("type").and_then(|t| t.as_str()).unwrap_or("").to_string(),
495            data: data.clone(),
496        }],
497
498        InboundMessage::Result(r) if r.is_success() => vec![AgentEvent::Done(TurnResult::from(r))],
499        InboundMessage::Result(r) => vec![AgentEvent::Error(TurnError::from(r))],
500
501        _ => vec![],
502    }
503}
504
505/// The `ToolResult` events of a `user` frame. The frame's
506/// `tool_use_result` is the structured output of its (single) tool result.
507fn tool_results(u: &InboundUserMessage) -> Vec<AgentEvent> {
508    let results = u.tool_results();
509    let structured = if results.len() == 1 { u.tool_use_result.clone() } else { None };
510    results
511        .into_iter()
512        .map(|r| AgentEvent::ToolResult {
513            tool_use_id: r.tool_use_id,
514            content: r.content,
515            is_error: r.is_error,
516            structured: structured.clone(),
517        })
518        .collect()
519}
520
521/// Whether `frame` is the CLI's `command_lifecycle` "cancelled" for prompt `uuid`.
522fn is_cancelled(frame: &serde_json::Value, uuid: &str) -> bool {
523    crate::session::cancelled_prompt(frame).is_some_and(|u| u.eq_ignore_ascii_case(uuid))
524}
525
526/// Wrap `events` as subagent events when `parent` is set.
527fn in_thread(parent: Option<&str>, events: Vec<AgentEvent>) -> Vec<AgentEvent> {
528    match parent {
529        None => events,
530        Some(p) => events
531            .into_iter()
532            .map(|event| AgentEvent::Subagent { parent_tool_use_id: p.to_string(), event: Box::new(event) })
533            .collect(),
534    }
535}