1use std::{path::PathBuf, sync::Arc};
8
9use derive_more::{Display, From};
10use serde::{Deserialize, Serialize};
11use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
12
13use crate::IntoOption;
14
15#[cfg(feature = "unstable_subagents")]
16use super::SessionId;
17use super::{ContentBlock, Error, Meta, TerminalId};
18
19#[serde_as]
26#[skip_serializing_none]
27#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29#[serde(rename_all = "camelCase")]
30#[non_exhaustive]
31pub struct ToolCall {
32 pub tool_call_id: ToolCallId,
34 pub title: String,
36 #[serde_as(deserialize_as = "DefaultOnError")]
41 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
42 #[serde(default)]
43 pub name: Option<String>,
44 #[serde_as(deserialize_as = "DefaultOnError")]
47 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
48 #[serde(default, skip_serializing_if = "ToolKind::is_default")]
49 pub kind: ToolKind,
50 #[serde_as(deserialize_as = "DefaultOnError")]
52 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
53 #[serde(default, skip_serializing_if = "ToolCallStatus::is_default")]
54 pub status: ToolCallStatus,
55 #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
57 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
58 #[serde(default, skip_serializing_if = "Vec::is_empty")]
59 pub content: Vec<ToolCallContent>,
60 #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
63 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
64 #[serde(default, skip_serializing_if = "Vec::is_empty")]
65 pub locations: Vec<ToolCallLocation>,
66 #[serde_as(deserialize_as = "DefaultOnError")]
68 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
69 #[serde(default)]
70 pub raw_input: Option<serde_json::Value>,
71 #[serde_as(deserialize_as = "DefaultOnError")]
73 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
74 #[serde(default)]
75 pub raw_output: Option<serde_json::Value>,
76 #[serde_as(deserialize_as = "DefaultOnError")]
82 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
83 #[serde(default)]
84 #[serde(rename = "_meta")]
85 pub meta: Option<Meta>,
86}
87
88impl ToolCall {
89 #[must_use]
91 pub fn new(tool_call_id: impl Into<ToolCallId>, title: impl Into<String>) -> Self {
92 Self {
93 tool_call_id: tool_call_id.into(),
94 title: title.into(),
95 name: None,
96 kind: ToolKind::default(),
97 status: ToolCallStatus::default(),
98 content: Vec::default(),
99 locations: Vec::default(),
100 raw_input: None,
101 raw_output: None,
102 meta: None,
103 }
104 }
105
106 #[must_use]
108 pub fn name(mut self, name: impl IntoOption<String>) -> Self {
109 self.name = name.into_option();
110 self
111 }
112
113 #[must_use]
116 pub fn kind(mut self, kind: ToolKind) -> Self {
117 self.kind = kind;
118 self
119 }
120
121 #[must_use]
123 pub fn status(mut self, status: ToolCallStatus) -> Self {
124 self.status = status;
125 self
126 }
127
128 #[must_use]
130 pub fn content(mut self, content: Vec<ToolCallContent>) -> Self {
131 self.content = content;
132 self
133 }
134
135 #[must_use]
138 pub fn locations(mut self, locations: Vec<ToolCallLocation>) -> Self {
139 self.locations = locations;
140 self
141 }
142
143 #[must_use]
145 pub fn raw_input(mut self, raw_input: impl IntoOption<serde_json::Value>) -> Self {
146 self.raw_input = raw_input.into_option();
147 self
148 }
149
150 #[must_use]
152 pub fn raw_output(mut self, raw_output: impl IntoOption<serde_json::Value>) -> Self {
153 self.raw_output = raw_output.into_option();
154 self
155 }
156
157 #[must_use]
163 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
164 self.meta = meta.into_option();
165 self
166 }
167
168 pub fn update(&mut self, fields: ToolCallUpdateFields) {
171 if let Some(title) = fields.title {
172 self.title = title;
173 }
174 if let Some(name) = fields.name {
175 self.name = Some(name);
176 }
177 if let Some(kind) = fields.kind {
178 self.kind = kind;
179 }
180 if let Some(status) = fields.status {
181 self.status = status;
182 }
183 if let Some(content) = fields.content {
184 self.content = content;
185 }
186 if let Some(locations) = fields.locations {
187 self.locations = locations;
188 }
189 if let Some(raw_input) = fields.raw_input {
190 self.raw_input = Some(raw_input);
191 }
192 if let Some(raw_output) = fields.raw_output {
193 self.raw_output = Some(raw_output);
194 }
195 }
196}
197
198#[serde_as]
205#[skip_serializing_none]
206#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
207#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
208#[serde(rename_all = "camelCase")]
209#[non_exhaustive]
210pub struct ToolCallUpdate {
211 pub tool_call_id: ToolCallId,
213 #[serde(flatten)]
215 pub fields: ToolCallUpdateFields,
216 #[serde_as(deserialize_as = "DefaultOnError")]
222 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
223 #[serde(default)]
224 #[serde(rename = "_meta")]
225 pub meta: Option<Meta>,
226}
227
228impl ToolCallUpdate {
229 #[must_use]
231 pub fn new(tool_call_id: impl Into<ToolCallId>, fields: ToolCallUpdateFields) -> Self {
232 Self {
233 tool_call_id: tool_call_id.into(),
234 fields,
235 meta: None,
236 }
237 }
238
239 #[must_use]
245 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
246 self.meta = meta.into_option();
247 self
248 }
249}
250
251#[serde_as]
258#[skip_serializing_none]
259#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
260#[derive(Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
261#[serde(rename_all = "camelCase")]
262#[non_exhaustive]
263pub struct ToolCallUpdateFields {
264 #[serde_as(deserialize_as = "DefaultOnError")]
266 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
267 #[serde(default)]
268 pub kind: Option<ToolKind>,
269 #[serde_as(deserialize_as = "DefaultOnError")]
271 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
272 #[serde(default)]
273 pub status: Option<ToolCallStatus>,
274 #[serde_as(deserialize_as = "DefaultOnError")]
276 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
277 #[serde(default)]
278 pub title: Option<String>,
279 #[serde_as(deserialize_as = "DefaultOnError")]
284 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
285 #[serde(default)]
286 pub name: Option<String>,
287 #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
289 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
290 #[serde(default)]
291 pub content: Option<Vec<ToolCallContent>>,
292 #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
294 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
295 #[serde(default)]
296 pub locations: Option<Vec<ToolCallLocation>>,
297 #[serde_as(deserialize_as = "DefaultOnError")]
299 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
300 #[serde(default)]
301 pub raw_input: Option<serde_json::Value>,
302 #[serde_as(deserialize_as = "DefaultOnError")]
304 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
305 #[serde(default)]
306 pub raw_output: Option<serde_json::Value>,
307}
308
309impl ToolCallUpdateFields {
310 #[must_use]
312 pub fn new() -> Self {
313 Self::default()
314 }
315
316 #[must_use]
318 pub fn kind(mut self, kind: impl IntoOption<ToolKind>) -> Self {
319 self.kind = kind.into_option();
320 self
321 }
322
323 #[must_use]
325 pub fn status(mut self, status: impl IntoOption<ToolCallStatus>) -> Self {
326 self.status = status.into_option();
327 self
328 }
329
330 #[must_use]
332 pub fn title(mut self, title: impl IntoOption<String>) -> Self {
333 self.title = title.into_option();
334 self
335 }
336
337 #[must_use]
339 pub fn name(mut self, name: impl IntoOption<String>) -> Self {
340 self.name = name.into_option();
341 self
342 }
343
344 #[must_use]
346 pub fn content(mut self, content: impl IntoOption<Vec<ToolCallContent>>) -> Self {
347 self.content = content.into_option();
348 self
349 }
350
351 #[must_use]
353 pub fn locations(mut self, locations: impl IntoOption<Vec<ToolCallLocation>>) -> Self {
354 self.locations = locations.into_option();
355 self
356 }
357
358 #[must_use]
360 pub fn raw_input(mut self, raw_input: impl IntoOption<serde_json::Value>) -> Self {
361 self.raw_input = raw_input.into_option();
362 self
363 }
364
365 #[must_use]
367 pub fn raw_output(mut self, raw_output: impl IntoOption<serde_json::Value>) -> Self {
368 self.raw_output = raw_output.into_option();
369 self
370 }
371}
372
373impl TryFrom<ToolCallUpdate> for ToolCall {
376 type Error = Error;
377
378 fn try_from(update: ToolCallUpdate) -> Result<Self, Self::Error> {
379 let ToolCallUpdate {
380 tool_call_id,
381 fields:
382 ToolCallUpdateFields {
383 kind,
384 status,
385 title,
386 name,
387 content,
388 locations,
389 raw_input,
390 raw_output,
391 },
392 meta,
393 } = update;
394
395 Ok(Self {
396 tool_call_id,
397 title: title.ok_or_else(|| {
398 Error::invalid_params().data(serde_json::json!("title is required for a tool call"))
399 })?,
400 name,
401 kind: kind.unwrap_or_default(),
402 status: status.unwrap_or_default(),
403 content: content.unwrap_or_default(),
404 locations: locations.unwrap_or_default(),
405 raw_input,
406 raw_output,
407 meta,
408 })
409 }
410}
411
412impl From<ToolCall> for ToolCallUpdate {
413 fn from(value: ToolCall) -> Self {
414 let ToolCall {
415 tool_call_id,
416 title,
417 name,
418 kind,
419 status,
420 content,
421 locations,
422 raw_input,
423 raw_output,
424 meta,
425 } = value;
426 Self {
427 tool_call_id,
428 fields: ToolCallUpdateFields {
429 kind: Some(kind),
430 status: Some(status),
431 title: Some(title),
432 name,
433 content: Some(content),
434 locations: Some(locations),
435 raw_input,
436 raw_output,
437 },
438 meta,
439 }
440 }
441}
442
443#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
445#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
446#[serde(transparent)]
447#[from(Arc<str>, String, &'static str)]
448#[non_exhaustive]
449pub struct ToolCallId(pub Arc<str>);
450
451impl ToolCallId {
452 #[must_use]
454 pub fn new(id: impl Into<Arc<str>>) -> Self {
455 Self(id.into())
456 }
457}
458
459impl IntoOption<ToolCallId> for &str {
460 fn into_option(self) -> Option<ToolCallId> {
461 Some(ToolCallId::new(self))
462 }
463}
464
465#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
472#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
473#[serde(rename_all = "snake_case")]
474#[non_exhaustive]
475pub enum ToolKind {
476 Read,
478 Edit,
480 Delete,
482 Move,
484 Search,
486 Execute,
488 Think,
490 Fetch,
492 SwitchMode,
494 #[default]
496 #[serde(other)]
497 Other,
498}
499
500impl ToolKind {
501 #[expect(clippy::trivially_copy_pass_by_ref, reason = "Required by serde")]
502 fn is_default(&self) -> bool {
503 matches!(self, ToolKind::Other)
504 }
505}
506
507#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
513#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
514#[serde(rename_all = "snake_case")]
515#[non_exhaustive]
516pub enum ToolCallStatus {
517 #[default]
520 Pending,
521 InProgress,
523 Completed,
525 Failed,
527}
528
529impl ToolCallStatus {
530 #[expect(clippy::trivially_copy_pass_by_ref, reason = "Required by serde")]
531 fn is_default(&self) -> bool {
532 matches!(self, ToolCallStatus::Pending)
533 }
534}
535
536#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
543#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
544#[serde(tag = "type", rename_all = "snake_case")]
545#[cfg_attr(feature = "schemars", schemars(extend("discriminator" = {"propertyName": "type"})))]
546#[non_exhaustive]
547#[expect(clippy::large_enum_variant)]
548pub enum ToolCallContent {
549 Content(Content),
551 Diff(Diff),
553 Terminal(Terminal),
559 #[cfg(feature = "unstable_subagents")]
565 Session(SessionReference),
566}
567
568impl<T: Into<ContentBlock>> From<T> for ToolCallContent {
569 fn from(content: T) -> Self {
570 ToolCallContent::Content(Content::new(content))
571 }
572}
573
574impl From<Diff> for ToolCallContent {
575 fn from(diff: Diff) -> Self {
576 ToolCallContent::Diff(diff)
577 }
578}
579
580#[cfg(feature = "unstable_subagents")]
592#[serde_as]
593#[skip_serializing_none]
594#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
595#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
596#[serde(rename_all = "camelCase")]
597#[non_exhaustive]
598pub struct SessionReference {
599 pub session_id: SessionId,
601 #[serde_as(deserialize_as = "DefaultOnError")]
607 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
608 #[serde(default)]
609 #[serde(rename = "_meta")]
610 pub meta: Option<Meta>,
611}
612
613#[cfg(feature = "unstable_subagents")]
614impl SessionReference {
615 #[must_use]
617 pub fn new(session_id: impl Into<SessionId>) -> Self {
618 Self {
619 session_id: session_id.into(),
620 meta: None,
621 }
622 }
623
624 #[must_use]
627 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
628 self.meta = meta.into_option();
629 self
630 }
631}
632
633#[cfg(feature = "unstable_subagents")]
634impl From<SessionReference> for ToolCallContent {
635 fn from(session: SessionReference) -> Self {
636 ToolCallContent::Session(session)
637 }
638}
639
640#[serde_as]
642#[skip_serializing_none]
643#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
644#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
645#[serde(rename_all = "camelCase")]
646#[non_exhaustive]
647pub struct Content {
648 pub content: ContentBlock,
650 #[serde_as(deserialize_as = "DefaultOnError")]
656 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
657 #[serde(default)]
658 #[serde(rename = "_meta")]
659 pub meta: Option<Meta>,
660}
661
662impl Content {
663 #[must_use]
665 pub fn new(content: impl Into<ContentBlock>) -> Self {
666 Self {
667 content: content.into(),
668 meta: None,
669 }
670 }
671
672 #[must_use]
678 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
679 self.meta = meta.into_option();
680 self
681 }
682}
683
684#[serde_as]
690#[skip_serializing_none]
691#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
692#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
693#[serde(rename_all = "camelCase")]
694#[non_exhaustive]
695pub struct Terminal {
696 pub terminal_id: TerminalId,
698 #[serde_as(deserialize_as = "DefaultOnError")]
704 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
705 #[serde(default)]
706 #[serde(rename = "_meta")]
707 pub meta: Option<Meta>,
708}
709
710impl Terminal {
711 #[must_use]
713 pub fn new(terminal_id: impl Into<TerminalId>) -> Self {
714 Self {
715 terminal_id: terminal_id.into(),
716 meta: None,
717 }
718 }
719
720 #[must_use]
726 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
727 self.meta = meta.into_option();
728 self
729 }
730}
731
732#[serde_as]
738#[skip_serializing_none]
739#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
740#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
741#[serde(rename_all = "camelCase")]
742#[non_exhaustive]
743pub struct Diff {
744 pub path: PathBuf,
746 #[serde_as(deserialize_as = "DefaultOnError")]
748 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
749 #[serde(default)]
750 pub old_text: Option<String>,
751 pub new_text: String,
753 #[serde_as(deserialize_as = "DefaultOnError")]
759 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
760 #[serde(default)]
761 #[serde(rename = "_meta")]
762 pub meta: Option<Meta>,
763}
764
765impl Diff {
766 #[must_use]
768 pub fn new(path: impl Into<PathBuf>, new_text: impl Into<String>) -> Self {
769 Self {
770 path: path.into(),
771 old_text: None,
772 new_text: new_text.into(),
773 meta: None,
774 }
775 }
776
777 #[must_use]
779 pub fn old_text(mut self, old_text: impl IntoOption<String>) -> Self {
780 self.old_text = old_text.into_option();
781 self
782 }
783
784 #[must_use]
790 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
791 self.meta = meta.into_option();
792 self
793 }
794}
795
796#[serde_as]
803#[skip_serializing_none]
804#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
805#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
806#[serde(rename_all = "camelCase")]
807#[non_exhaustive]
808pub struct ToolCallLocation {
809 pub path: PathBuf,
811 #[serde_as(deserialize_as = "DefaultOnError")]
813 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
814 #[serde(default)]
815 pub line: Option<u32>,
816 #[serde_as(deserialize_as = "DefaultOnError")]
822 #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
823 #[serde(default)]
824 #[serde(rename = "_meta")]
825 pub meta: Option<Meta>,
826}
827
828impl ToolCallLocation {
829 #[must_use]
831 pub fn new(path: impl Into<PathBuf>) -> Self {
832 Self {
833 path: path.into(),
834 line: None,
835 meta: None,
836 }
837 }
838
839 #[must_use]
841 pub fn line(mut self, line: impl IntoOption<u32>) -> Self {
842 self.line = line.into_option();
843 self
844 }
845
846 #[must_use]
852 pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
853 self.meta = meta.into_option();
854 self
855 }
856}
857
858#[cfg(test)]
859mod tests {
860
861 #[cfg(feature = "unstable_subagents")]
862 #[test]
863 fn session_reference_tool_call_content_round_trips() {
864 use serde_json::json;
865 let content = ToolCallContent::from(SessionReference::new("sess_child_1"));
866 let value = serde_json::to_value(&content).unwrap();
867 assert_eq!(
868 value,
869 json!({ "type": "session", "sessionId": "sess_child_1" })
870 );
871 assert_eq!(
872 serde_json::from_value::<ToolCallContent>(value).unwrap(),
873 content
874 );
875 }
876 use super::*;
877
878 #[test]
879 fn tool_call_name_is_optional_and_null_is_equivalent_to_omission() {
880 let named = ToolCall::new("tc_1", "Reading configuration").name("read_file");
881 assert_eq!(
882 serde_json::to_value(named).unwrap(),
883 serde_json::json!({
884 "toolCallId": "tc_1",
885 "title": "Reading configuration",
886 "name": "read_file"
887 })
888 );
889
890 let unnamed = ToolCall::new("tc_1", "Reading configuration");
891 assert_eq!(unnamed.name, None);
892 assert_eq!(
893 serde_json::to_value(unnamed).unwrap(),
894 serde_json::json!({
895 "toolCallId": "tc_1",
896 "title": "Reading configuration"
897 })
898 );
899
900 let from_null: ToolCall = serde_json::from_value(serde_json::json!({
901 "toolCallId": "tc_1",
902 "title": "Reading configuration",
903 "name": null
904 }))
905 .unwrap();
906 assert_eq!(from_null.name, None);
907 }
908
909 #[test]
910 fn tool_call_name_update_replaces_a_name_but_cannot_clear_it() {
911 let mut stored = ToolCall::new("tc_1", "Reading configuration").name("read_file");
912
913 stored.update(ToolCallUpdateFields::new());
914 assert_eq!(stored.name.as_deref(), Some("read_file"));
915
916 let null_update: ToolCallUpdateFields =
917 serde_json::from_value(serde_json::json!({"name": null})).unwrap();
918 stored.update(null_update);
919 assert_eq!(stored.name.as_deref(), Some("read_file"));
920
921 stored.update(ToolCallUpdateFields::new().name("read_many_files"));
922 assert_eq!(stored.name.as_deref(), Some("read_many_files"));
923 }
924
925 #[test]
926 fn tool_call_name_survives_v1_upsert_conversion() {
927 let tool_call = ToolCall::new("tc_1", "Reading configuration").name("read_file");
928
929 let update = ToolCallUpdate::from(tool_call.clone());
930 assert_eq!(update.fields.name.as_deref(), Some("read_file"));
931
932 let rebuilt = ToolCall::try_from(update).unwrap();
933 assert_eq!(rebuilt, tool_call);
934 }
935}