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}
211
212/// Events of one turn; ends after `Done` or `Error`. Dropping it before
213/// then cancels the turn (see `Agent::prompt_message`).
214pub type AgentStream = Pin<Box<dyn tokio_stream::Stream<Item = AgentEvent> + Send + 'static>>;
215
216// ─── Agent ────────────────────────────────────────────────────────────────────
217
218/// Runs turns on a Session.
219pub struct Agent {
220    session: Session,
221}
222
223impl Agent {
224    /// Wrap `session`.
225    #[must_use]
226    pub fn new(session: Session) -> Self {
227        Self { session }
228    }
229
230    /// The underlying session.
231    #[must_use]
232    pub fn session(&self) -> &Session {
233        &self.session
234    }
235
236    /// Run a text prompt and return a streaming iterator of `AgentEvents`.
237    ///
238    /// The stream ends after a `Done` or `Error` event.
239    pub async fn prompt(&self, text: impl Into<String>) -> Result<AgentStream, AgentError> {
240        self.prompt_message(UserMessage::text(text.into())).await
241    }
242
243    /// Run a prompt built from content blocks (text, images, …).
244    ///
245    /// Dropping the stream before its `Done`/`Error` cancels the prompt:
246    /// still queued, it is withdrawn; running, its turn is interrupted.
247    /// Drain the stream to let the turn finish.
248    pub async fn prompt_message(&self, message: UserMessage) -> Result<AgentStream, AgentError> {
249        // Subscribe before sending so no frame of this turn is missed.
250        let mut rx = self.session.subscribe();
251        let uuid = message.uuid.clone();
252        self.session.send_prompt(&message).await?;
253        // With partial messages on, text already streamed as deltas; the
254        // complete assistant message would repeat it.
255        let partial = self.session.include_partial();
256        // Lives as long as the stream: its duration is the turn's duration.
257        let span = tracing::info_span!(
258            "claude.turn",
259            session_id = self.session.session_id().unwrap_or_default(),
260            cost_usd = tracing::field::Empty,
261            input_tokens = tracing::field::Empty,
262            output_tokens = tracing::field::Empty,
263            ttft_ms = tracing::field::Empty,
264            error = tracing::field::Empty,
265        );
266
267        // Created outside the generator: a stream dropped before its first
268        // poll still cancels. It also keeps the session alive until the turn
269        // ends, even when the Agent and every other handle are dropped first.
270        let mut guard = CancelOnDrop { session: self.session.clone(), uuid: uuid.clone(), armed: true };
271        let stream = async_stream::stream! {
272            // Turns run one after another and each ends with a `result`. Our
273            // prompt's echo falls inside our turn: first for a normal prompt,
274            // last for a slash command (after e.g. compact_boundary). So frames
275            // since the previous `result` are held until the echo shows whose
276            // turn they are. A `result` before our echo closes someone else's
277            // turn (a queued prompt, or one the CLI started itself) unless it
278            // names our prompt (a prompt refused up front is never echoed).
279            let mut started = false;
280            let mut held: Vec<Arc<InboundMessage>> = vec![];
281            loop {
282                let Some(msg) = rx.recv().await else {
283                    guard.disarm();
284                    yield AgentEvent::Error(TurnError::session_closed());
285                    break;
286                };
287                // Withdrawn before it ran (`cancel_prompt`, `interrupt_all`):
288                // no `result` will come.
289                if let InboundMessage::Other(frame) = msg.as_ref()
290                    && is_cancelled(frame, &uuid)
291                {
292                    guard.disarm();
293                    yield AgentEvent::Error(TurnError::cancelled());
294                    break;
295                }
296
297                if !started {
298                    match msg.as_ref() {
299                        InboundMessage::User(u) if u.uuid.as_deref().is_some_and(|u| u.eq_ignore_ascii_case(&uuid)) => {
300                            started = true;
301                            for m in held.drain(..) {
302                                for ev in to_events(&m, partial) {
303                                    yield ev;
304                                }
305                            }
306                        }
307                        // Refused before it started: no echo, but the
308                        // result names our prompt. The held frames are ours.
309                        InboundMessage::Result(r) if r.answers(&uuid) => {
310                            started = true;
311                            for m in held.drain(..) {
312                                for ev in to_events(&m, partial) {
313                                    yield ev;
314                                }
315                            }
316                        }
317                        InboundMessage::Result(_) => {
318                            held.clear();
319                            continue;
320                        }
321                        _ => {
322                            held.push(msg);
323                            continue;
324                        }
325                    }
326                    if !matches!(msg.as_ref(), InboundMessage::Result(_)) {
327                        continue;
328                    }
329                }
330
331                if let InboundMessage::Result(r) = msg.as_ref() {
332                    guard.disarm();
333                    let t = TurnResult::from(r);
334                    if let Some(v) = t.total_cost_usd { span.record("cost_usd", v); }
335                    if let Some(v) = t.input_tokens { span.record("input_tokens", v); }
336                    if let Some(v) = t.output_tokens { span.record("output_tokens", v); }
337                    if let Some(v) = t.ttft_ms { span.record("ttft_ms", v); }
338                    if !r.is_success() { span.record("error", r.subtype.as_str()); }
339                }
340                let done = matches!(msg.as_ref(), InboundMessage::Result(_));
341                for ev in to_events(&msg, partial) {
342                    yield ev;
343                }
344                if done {
345                    break;
346                }
347            }
348        };
349
350        Ok(Box::pin(stream))
351    }
352
353    /// Every event of every turn from now on — prompted turns and the turns
354    /// the CLI starts itself (`TurnResult::origin` set), each ending with
355    /// `Done` or `Error`. Ends when the session closes. Dropping it cancels
356    /// nothing. Lossless like `Session::subscribe`: events buffer until
357    /// polled, so poll it or drop it.
358    pub fn watch(&self) -> AgentStream {
359        let mut rx = self.session.subscribe();
360        let partial = self.session.include_partial();
361        Box::pin(async_stream::stream! {
362            while let Some(msg) = rx.recv().await {
363                for ev in to_events(&msg, partial) {
364                    yield ev;
365                }
366            }
367        })
368    }
369}
370
371/// Cancels the prompt `uuid` unless disarmed (its turn ended).
372struct CancelOnDrop {
373    session: Session,
374    uuid: String,
375    armed: bool,
376}
377
378impl CancelOnDrop {
379    fn disarm(&mut self) {
380        self.armed = false;
381    }
382}
383
384impl Drop for CancelOnDrop {
385    fn drop(&mut self) {
386        if !self.armed || !self.session.is_alive() {
387            return;
388        }
389        let Ok(rt) = tokio::runtime::Handle::try_current() else {
390            tracing::warn!("turn stream dropped outside a Tokio runtime; the turn keeps running");
391            return;
392        };
393        let session = self.session.clone();
394        let uuid = std::mem::take(&mut self.uuid);
395        rt.spawn(async move {
396            if let Err(e) = session.cancel_prompt(&uuid).await {
397                tracing::debug!(error = %e, "cancelling a dropped turn failed");
398            }
399        });
400    }
401}
402
403/// The `AgentEvents` one frame produces. `partial`: text arrives as stream
404/// deltas, so complete main-thread text is skipped. Frames of subagents
405/// (`parent_tool_use_id` set) are wrapped in `AgentEvent::Subagent`; their
406/// text comes from complete messages only.
407fn to_events(msg: &InboundMessage, partial: bool) -> Vec<AgentEvent> {
408    match msg {
409        InboundMessage::Assistant(a) => {
410            let sub = a.parent_tool_use_id.is_some();
411            let events = a.message.content.iter().filter_map(|block| match block {
412                AssistantBlock::Text { text } if sub || !partial => Some(AgentEvent::Text(text.clone())),
413                AssistantBlock::Thinking { thinking } if sub || !partial => {
414                    Some(AgentEvent::Thinking(thinking.clone()))
415                }
416                AssistantBlock::RedactedThinking { data } => Some(AgentEvent::RedactedThinking(data.clone())),
417                AssistantBlock::ToolUse { id, name, input } => Some(AgentEvent::ToolUse {
418                    id: id.clone(),
419                    name: name.clone(),
420                    input: input.clone(),
421                    server: false,
422                }),
423                AssistantBlock::ServerToolUse { id, name, input } => Some(AgentEvent::ToolUse {
424                    id: id.clone(),
425                    name: name.clone(),
426                    input: input.clone(),
427                    server: true,
428                }),
429                AssistantBlock::WebSearchToolResult { tool_use_id, content } => Some(AgentEvent::ToolResult {
430                    tool_use_id: tool_use_id.clone(),
431                    content: content.clone(),
432                    is_error: false,
433                    structured: None,
434                }),
435                _ => None,
436            });
437            in_thread(a.parent_tool_use_id.as_deref(), events.collect())
438        }
439
440        InboundMessage::User(u) => in_thread(u.parent_tool_use_id.as_deref(), tool_results(u)),
441
442        InboundMessage::StreamEvent(se) if se.parent_tool_use_id.is_none() => {
443            let delta = se.event.get("delta");
444            let text = delta.and_then(|d| d.get("text")).and_then(|t| t.as_str());
445            let thinking = delta.and_then(|d| d.get("thinking")).and_then(|t| t.as_str());
446            text.map(|t| AgentEvent::Text(t.to_string()))
447                .into_iter()
448                .chain(thinking.map(|t| AgentEvent::Thinking(t.to_string())))
449                .collect()
450        }
451
452        InboundMessage::System(s) => match s.subtype.as_str() {
453            "background_tasks_changed" => {
454                let tasks = s.extra.get("tasks").cloned().unwrap_or_default();
455                match serde_json::from_value::<Vec<BackgroundTask>>(tasks) {
456                    Ok(tasks) => vec![AgentEvent::BackgroundTasks(tasks)],
457                    Err(e) => {
458                        tracing::debug!(error = %e, "undecodable background_tasks_changed");
459                        vec![]
460                    }
461                }
462            }
463            "model_fallback" => {
464                let field = |k: &str| s.extra.get(k).and_then(|v| v.as_str()).unwrap_or("").to_string();
465                vec![AgentEvent::ModelFallback {
466                    from: field("original_model"),
467                    to: field("fallback_model"),
468                    trigger: field("trigger"),
469                }]
470            }
471            "compact_boundary" => {
472                let meta = s.extra.get("compact_metadata");
473                let num = |k: &str| meta.and_then(|m| m.get(k)).and_then(serde_json::Value::as_u64);
474                vec![AgentEvent::Compacted {
475                    trigger: meta.and_then(|m| m.get("trigger")).and_then(|v| v.as_str()).unwrap_or("").to_string(),
476                    pre_tokens: num("pre_tokens"),
477                    post_tokens: num("post_tokens"),
478                }]
479            }
480            other => vec![AgentEvent::System {
481                subtype: other.to_string(),
482                data: serde_json::to_value(s).unwrap_or_else(|e| {
483                    tracing::warn!(error = %e, "could not serialize a system frame");
484                    serde_json::Value::Null
485                }),
486            }],
487        },
488
489        InboundMessage::Other(data) => vec![AgentEvent::Other {
490            kind: data.get("type").and_then(|t| t.as_str()).unwrap_or("").to_string(),
491            data: data.clone(),
492        }],
493
494        InboundMessage::Result(r) if r.is_success() => vec![AgentEvent::Done(TurnResult::from(r))],
495        InboundMessage::Result(r) => vec![AgentEvent::Error(TurnError::from(r))],
496
497        _ => vec![],
498    }
499}
500
501/// The `ToolResult` events of a `user` frame. The frame's
502/// `tool_use_result` is the structured output of its (single) tool result.
503fn tool_results(u: &InboundUserMessage) -> Vec<AgentEvent> {
504    let results = u.tool_results();
505    let structured = if results.len() == 1 { u.tool_use_result.clone() } else { None };
506    results
507        .into_iter()
508        .map(|r| AgentEvent::ToolResult {
509            tool_use_id: r.tool_use_id,
510            content: r.content,
511            is_error: r.is_error,
512            structured: structured.clone(),
513        })
514        .collect()
515}
516
517/// Whether `frame` is the CLI's `command_lifecycle` "cancelled" for prompt `uuid`.
518fn is_cancelled(frame: &serde_json::Value, uuid: &str) -> bool {
519    let field = |k: &str| frame.get(k).and_then(|v| v.as_str());
520    field("type") == Some("command_lifecycle")
521        && field("state") == Some("cancelled")
522        && field("command_uuid").is_some_and(|u| u.eq_ignore_ascii_case(uuid))
523}
524
525/// Wrap `events` as subagent events when `parent` is set.
526fn in_thread(parent: Option<&str>, events: Vec<AgentEvent>) -> Vec<AgentEvent> {
527    match parent {
528        None => events,
529        Some(p) => events
530            .into_iter()
531            .map(|event| AgentEvent::Subagent { parent_tool_use_id: p.to_string(), event: Box::new(event) })
532            .collect(),
533    }
534}