1use serde::{Deserialize, Serialize};
5use std::collections::HashMap;
6
7#[derive(Debug, Clone, Serialize)]
17pub struct OutboundControlRequest<'a, B: Serialize> {
18 #[serde(rename = "type")]
20 pub kind: &'static str, pub request_id: &'a str,
23 pub request: &'a B,
25}
26
27#[derive(Debug, Clone, Serialize, Default)]
35#[serde(rename_all = "camelCase")]
36pub struct Initialize {
37 #[serde(skip_serializing_if = "Option::is_none")]
39 pub hooks: Option<HashMap<HookEventKind, Vec<HookMatcherConfig>>>,
40 #[serde(skip_serializing_if = "Option::is_none")]
42 pub system_prompt: Option<String>,
43 #[serde(skip_serializing_if = "Option::is_none")]
45 pub append_system_prompt: Option<String>,
46 #[serde(skip_serializing_if = "Option::is_none")]
48 pub agents: Option<serde_json::Value>,
49 #[serde(skip_serializing_if = "Option::is_none")]
52 pub json_schema: Option<serde_json::Value>,
53 #[serde(skip_serializing_if = "Option::is_none")]
55 pub title: Option<String>,
56 #[serde(skip_serializing_if = "Option::is_none")]
58 pub skills: Option<Vec<String>>,
59 #[serde(skip_serializing_if = "Option::is_none")]
61 pub plugins: Option<Vec<serde_json::Value>>,
62 #[serde(skip_serializing_if = "Option::is_none")]
66 pub mcp_servers: Option<serde_json::Map<String, serde_json::Value>>,
67 #[serde(skip_serializing_if = "Option::is_none")]
69 pub plan_mode_instructions: Option<String>,
70 #[serde(skip_serializing_if = "Option::is_none")]
73 pub exclude_dynamic_sections: Option<bool>,
74 #[serde(skip_serializing_if = "Option::is_none")]
76 pub system_prompt_snapshot: Option<bool>,
77 #[serde(skip_serializing_if = "Option::is_none")]
79 pub prompt_suggestions: Option<bool>,
80 #[serde(skip_serializing_if = "Option::is_none")]
82 pub agent_progress_summaries: Option<bool>,
83 #[serde(skip_serializing_if = "Option::is_none")]
85 pub forward_subagent_text: Option<bool>,
86 #[serde(skip_serializing_if = "Option::is_none")]
88 pub tool_aliases: Option<HashMap<String, String>>,
89 #[serde(skip_serializing_if = "Option::is_none")]
92 pub supported_dialog_kinds: Option<Vec<String>>,
93 #[serde(skip_serializing_if = "Option::is_none")]
95 pub per_task_stop_affordance: Option<bool>,
96 #[serde(skip_serializing_if = "Option::is_none")]
98 pub workspace_trust: Option<WorkspaceTrust>,
99}
100
101#[derive(Debug, Clone, Serialize)]
104pub struct WorkspaceTrust {
105 pub accepted: bool,
107 pub directory: String,
109}
110
111#[derive(Debug, Clone, Serialize)]
114#[serde(rename_all = "camelCase")]
115pub struct HookMatcherConfig {
116 pub matcher: Option<String>,
118 pub hook_callback_ids: Vec<String>,
120 #[serde(skip_serializing_if = "Option::is_none")]
122 pub timeout: Option<u32>,
123}
124
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
128#[serde(rename_all = "camelCase")]
129pub enum PermissionMode {
130 Default,
132 AcceptEdits,
134 BypassPermissions,
136 Plan,
138 DontAsk,
140 Auto,
142}
143
144impl PermissionMode {
145 #[must_use]
147 pub fn as_str(self) -> &'static str {
148 match self {
149 Self::Default => "default",
150 Self::AcceptEdits => "acceptEdits",
151 Self::BypassPermissions => "bypassPermissions",
152 Self::Plan => "plan",
153 Self::DontAsk => "dontAsk",
154 Self::Auto => "auto",
155 }
156 }
157}
158
159#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
162#[serde(rename_all = "lowercase")]
163pub enum Effort {
164 Low,
166 Medium,
168 High,
170 Xhigh,
172 Max,
174}
175
176impl Effort {
177 #[must_use]
179 pub fn as_str(self) -> &'static str {
180 match self {
181 Self::Low => "low",
182 Self::Medium => "medium",
183 Self::High => "high",
184 Self::Xhigh => "xhigh",
185 Self::Max => "max",
186 }
187 }
188}
189
190#[derive(Debug, Clone, Copy, PartialEq, Eq)]
192pub enum Thinking {
193 Enabled,
195 Adaptive,
197 Disabled,
199}
200
201impl Thinking {
202 #[must_use]
204 pub fn as_str(self) -> &'static str {
205 match self {
206 Self::Enabled => "enabled",
207 Self::Adaptive => "adaptive",
208 Self::Disabled => "disabled",
209 }
210 }
211}
212
213#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
216#[serde(rename_all = "lowercase")]
217pub enum ThinkingDisplay {
218 Summarized,
220 Omitted,
222 Highlights,
224}
225
226impl ThinkingDisplay {
227 #[must_use]
229 pub fn as_str(self) -> &'static str {
230 match self {
231 Self::Summarized => "summarized",
232 Self::Omitted => "omitted",
233 Self::Highlights => "highlights",
234 }
235 }
236}
237
238#[derive(Debug, Clone, Copy, PartialEq, Eq)]
240pub enum Autocompact {
241 Auto,
243 Tokens(u64),
245}
246
247impl Autocompact {
248 #[must_use]
250 pub fn to_arg(self) -> String {
251 match self {
252 Self::Auto => "auto".into(),
253 Self::Tokens(n) => n.to_string(),
254 }
255 }
256}
257
258#[derive(Debug, Clone, Copy, PartialEq, Eq)]
260pub enum PermissionPrompts {
261 Host,
263 None,
265}
266
267impl PermissionPrompts {
268 #[must_use]
270 pub fn as_str(self) -> &'static str {
271 match self {
272 Self::Host => "host",
273 Self::None => "none",
274 }
275 }
276}
277
278#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
281#[serde(rename_all = "lowercase")]
282pub enum Priority {
283 Now,
286 Next,
288 Later,
290}
291
292#[derive(Debug, Clone, Serialize, Deserialize)]
295pub struct UserMessage {
296 #[serde(rename = "type")]
298 pub kind: String, pub message: UserMessageBody,
301 pub parent_tool_use_id: Option<String>,
303 pub uuid: String,
306 #[serde(default, skip_serializing_if = "Option::is_none")]
308 pub priority: Option<Priority>,
309 #[serde(default, rename = "shouldQuery", skip_serializing_if = "Option::is_none")]
311 pub should_query: Option<bool>,
312 #[serde(default, skip_serializing_if = "Option::is_none")]
315 pub timestamp: Option<String>,
316 #[serde(default, skip_serializing_if = "Option::is_none")]
320 pub client_composed: Option<bool>,
321}
322
323impl UserMessage {
324 pub fn text(content: impl Into<String>) -> Self {
326 Self::blocks(vec![ContentBlock::Text { text: content.into() }])
327 }
328
329 #[must_use]
331 pub fn blocks(content: Vec<ContentBlock>) -> Self {
332 Self {
333 kind: "user".into(),
334 message: UserMessageBody { role: "user".into(), content },
335 parent_tool_use_id: None,
336 uuid: uuid::Uuid::new_v4().to_string(),
337 priority: None,
338 should_query: None,
339 timestamp: None,
340 client_composed: None,
341 }
342 }
343
344 #[must_use]
346 pub fn with_timestamp(mut self, timestamp: impl Into<String>) -> Self {
347 self.timestamp = Some(timestamp.into());
348 self
349 }
350
351 #[must_use]
354 pub fn client_composed(mut self) -> Self {
355 self.client_composed = Some(true);
356 self
357 }
358
359 #[must_use]
361 pub fn with_priority(mut self, priority: Priority) -> Self {
362 self.priority = Some(priority);
363 self
364 }
365
366 #[must_use]
369 pub fn context_only(mut self) -> Self {
370 self.should_query = Some(false);
371 self
372 }
373}
374
375#[derive(Debug, Clone, Serialize, Deserialize)]
377pub struct UserMessageBody {
378 pub role: String,
380 pub content: Vec<ContentBlock>,
382}
383
384#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
386#[serde(tag = "type")]
387pub enum ContentBlock {
388 #[serde(rename = "text")]
390 Text {
391 text: String,
393 },
394 #[serde(rename = "image")]
396 Image {
397 source: ImageSource,
399 },
400 #[serde(rename = "document")]
402 Document {
403 source: DocumentSource,
405 #[serde(default, skip_serializing_if = "Option::is_none")]
407 title: Option<String>,
408 },
409 #[serde(rename = "tool_result")]
411 ToolResult {
412 tool_use_id: String,
414 content: Vec<ContentBlock>,
416 #[serde(default, skip_serializing_if = "Option::is_none")]
418 is_error: Option<bool>,
419 },
420}
421
422impl ContentBlock {
423 pub fn image_base64(media_type: impl Into<String>, data: impl Into<String>) -> Self {
425 Self::Image {
426 source: ImageSource::Base64 { media_type: media_type.into(), data: data.into() },
427 }
428 }
429
430 pub fn pdf_base64(data: impl Into<String>) -> Self {
432 Self::Document {
433 source: DocumentSource::Base64 { media_type: "application/pdf".into(), data: data.into() },
434 title: None,
435 }
436 }
437}
438
439#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
441#[serde(tag = "type", rename_all = "lowercase")]
442pub enum DocumentSource {
443 Base64 {
445 media_type: String,
447 data: String,
449 },
450 Text {
452 media_type: String,
454 data: String,
456 },
457 Url {
459 url: String,
461 },
462}
463
464#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
466#[serde(tag = "type", rename_all = "lowercase")]
467pub enum ImageSource {
468 Base64 {
470 media_type: String,
472 data: String,
474 },
475 Url {
477 url: String,
479 },
480}
481
482#[derive(Debug, Clone, Serialize)]
485pub struct ControlResponse {
486 #[serde(rename = "type")]
488 pub kind: &'static str, pub response: ControlResponseBody,
491}
492
493#[derive(Debug, Clone, Serialize)]
495#[serde(tag = "subtype", rename_all = "lowercase")]
496pub enum ControlResponseBody {
497 Success {
499 request_id: String,
501 response: serde_json::Value,
503 },
504 Error {
506 request_id: String,
508 error: String,
510 },
511}
512
513impl ControlResponse {
514 pub fn success(request_id: impl Into<String>, response: serde_json::Value) -> Self {
516 Self {
517 kind: "control_response",
518 response: ControlResponseBody::Success { request_id: request_id.into(), response },
519 }
520 }
521 pub fn error(request_id: impl Into<String>, error: impl Into<String>) -> Self {
523 Self {
524 kind: "control_response",
525 response: ControlResponseBody::Error { request_id: request_id.into(), error: error.into() },
526 }
527 }
528}
529
530#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
534#[serde(tag = "behavior", rename_all = "camelCase")]
535pub enum ToolDecision {
536 #[serde(rename = "allow")]
540 Allow {
541 #[serde(rename = "updatedInput", skip_serializing_if = "Option::is_none")]
543 updated_input: Option<serde_json::Value>,
544 #[serde(rename = "updatedPermissions", default, skip_serializing_if = "Option::is_none")]
546 updated_permissions: Option<Vec<serde_json::Value>>,
547 },
548 #[serde(rename = "deny")]
550 Deny {
551 message: String,
553 #[serde(skip_serializing_if = "Option::is_none")]
555 interrupt: Option<bool>,
556 },
557}
558
559impl ToolDecision {
560 #[must_use]
562 pub fn allow() -> Self { Self::Allow { updated_input: None, updated_permissions: None } }
563 #[must_use]
565 pub fn allow_with_input(input: serde_json::Value) -> Self {
566 Self::Allow { updated_input: Some(input), updated_permissions: None }
567 }
568 #[must_use]
571 pub fn allow_and_remember(updates: Vec<serde_json::Value>) -> Self {
572 Self::Allow { updated_input: None, updated_permissions: Some(updates) }
573 }
574 pub fn deny(message: impl Into<String>) -> Self {
576 Self::Deny { message: message.into(), interrupt: None }
577 }
578}
579
580#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
584#[serde(rename_all = "camelCase")]
585pub struct HookOutput {
586 #[serde(rename = "continue", skip_serializing_if = "Option::is_none")]
588 pub continue_: Option<bool>,
589 #[serde(skip_serializing_if = "Option::is_none")]
591 pub suppress_output: Option<bool>,
592 #[serde(skip_serializing_if = "Option::is_none")]
594 pub stop_reason: Option<String>,
595 #[serde(skip_serializing_if = "Option::is_none")]
597 pub decision: Option<HookDecision>,
598 #[serde(skip_serializing_if = "Option::is_none")]
600 pub system_message: Option<String>,
601 #[serde(skip_serializing_if = "Option::is_none")]
603 pub reason: Option<String>,
604 #[serde(skip_serializing_if = "Option::is_none")]
606 pub hook_specific_output: Option<serde_json::Value>,
607}
608
609#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
611#[serde(rename_all = "lowercase")]
612pub enum HookDecision {
613 Approve,
615 Block,
617}
618
619impl HookOutput {
620 #[must_use]
622 pub fn allow() -> Self { Self::default() }
623
624 pub fn block(reason: impl Into<String>) -> Self {
626 Self { decision: Some(HookDecision::Block), reason: Some(reason.into()), ..Self::default() }
627 }
628
629 pub fn with_context(event: HookEventKind, context: impl Into<String>) -> Self {
633 if !event.accepts_additional_context() {
634 tracing::warn!(?event, "the CLI ignores additionalContext for this hook event");
635 }
636 Self {
637 hook_specific_output: Some(serde_json::json!({
638 "hookEventName": event,
639 "additionalContext": context.into(),
640 })),
641 ..Self::default()
642 }
643 }
644
645 #[must_use]
647 pub fn watch_paths(event: HookEventKind, paths: impl IntoIterator<Item = impl Into<String>>) -> Self {
648 let paths: Vec<String> = paths.into_iter().map(Into::into).collect();
649 Self {
650 hook_specific_output: Some(serde_json::json!({
651 "hookEventName": event,
652 "watchPaths": paths,
653 })),
654 ..Self::default()
655 }
656 }
657
658 #[must_use]
660 pub fn is_block(&self) -> bool { self.decision == Some(HookDecision::Block) }
661}
662
663#[derive(Debug, Clone, Serialize)]
667pub struct BackgroundTasksRequest {
668 pub subtype: &'static str, #[serde(skip_serializing_if = "Option::is_none")]
672 pub tool_use_id: Option<String>,
673}
674
675impl BackgroundTasksRequest {
676 #[must_use]
678 pub fn all() -> Self {
679 Self { subtype: "background_tasks", tool_use_id: None }
680 }
681 pub fn one(tool_use_id: impl Into<String>) -> Self {
683 Self { subtype: "background_tasks", tool_use_id: Some(tool_use_id.into()) }
684 }
685}
686
687#[derive(Debug, Clone, Deserialize)]
692#[serde(tag = "type")]
693#[non_exhaustive]
694pub enum InboundMessage {
695 #[serde(rename = "system")]
697 System(SystemMessage),
698 #[serde(rename = "user")]
700 User(InboundUserMessage),
701 #[serde(rename = "assistant")]
703 Assistant(AssistantMessage),
704 #[serde(rename = "stream_event")]
706 StreamEvent(StreamEventMessage),
707 #[serde(rename = "result")]
709 Result(ResultMessage),
710 #[serde(rename = "control_request")]
713 ControlRequest(ControlRequest),
714 #[serde(rename = "control_response")]
717 ControlResponse(InboundControlResponse),
718 #[serde(rename = "keep_alive")]
721 KeepAlive(KeepAliveMessage),
722 #[serde(rename = "control_cancel_request")]
725 ControlCancelRequest(ControlCancelRequest),
726 #[serde(skip_deserializing)]
729 Other(serde_json::Value),
730 #[doc(hidden)]
733 #[serde(other)]
734 Unknown,
735}
736
737#[derive(Debug, Clone, Deserialize)]
739#[non_exhaustive]
740pub struct ControlCancelRequest {
741 pub request_id: String,
743}
744
745#[derive(Debug, Clone, Serialize, Deserialize)]
753#[non_exhaustive]
754pub struct SystemMessage {
755 pub subtype: String, pub session_id: String,
759 #[serde(default)]
761 pub cwd: String,
762 #[serde(default)]
764 pub model: String,
765 #[serde(default)]
767 pub claude_code_version: String,
768 #[serde(default, rename = "permissionMode")]
770 pub permission_mode: String,
771 #[serde(default)]
773 pub tools: Vec<String>,
774 #[serde(default)]
776 pub betas: Vec<String>,
777 #[serde(default)]
779 pub capabilities: Vec<String>,
780 #[serde(default)]
782 pub skills: Vec<serde_json::Value>,
783 #[serde(default)]
785 pub plugins: Vec<serde_json::Value>,
786 #[serde(flatten)]
788 pub extra: HashMap<String, serde_json::Value>,
789}
790
791impl SystemMessage {
792 #[must_use]
794 pub fn code_mode_active(&self) -> bool {
795 self.tools.iter().any(|t| t == "REPL" || t == "Eval")
796 }
797}
798
799#[derive(Debug, Clone, Deserialize)]
801#[non_exhaustive]
802pub struct AssistantMessage {
803 pub message: AssistantMessageBody,
805 #[serde(default)]
807 pub session_id: Option<String>,
808 #[serde(default)]
810 pub parent_tool_use_id: Option<String>,
811}
812
813#[derive(Debug, Clone, Deserialize)]
815#[non_exhaustive]
816pub struct AssistantMessageBody {
817 pub role: String,
819 pub content: Vec<AssistantBlock>,
821 #[serde(default)]
823 pub stop_reason: Option<String>,
824}
825
826#[derive(Debug, Clone, Deserialize)]
828#[serde(tag = "type")]
829#[non_exhaustive]
830pub enum AssistantBlock {
831 #[serde(rename = "text")]
833 Text {
834 text: String,
836 },
837 #[serde(rename = "tool_use")]
839 ToolUse {
840 id: String,
842 name: String,
844 input: serde_json::Value,
846 },
847 #[serde(rename = "thinking")]
849 Thinking {
850 thinking: String,
852 },
853 #[serde(rename = "redacted_thinking")]
855 RedactedThinking {
856 data: String,
858 },
859 #[serde(rename = "server_tool_use")]
861 ServerToolUse {
862 id: String,
864 name: String,
866 input: serde_json::Value,
868 },
869 #[serde(rename = "web_search_tool_result")]
871 WebSearchToolResult {
872 tool_use_id: String,
874 content: serde_json::Value,
876 },
877 #[serde(other)]
879 Unknown,
880}
881
882#[derive(Debug, Clone, Deserialize)]
885#[non_exhaustive]
886pub struct InboundUserMessage {
887 #[serde(default)]
889 pub uuid: Option<String>,
890 #[serde(default, rename = "isReplay")]
892 pub is_replay: Option<bool>,
893 #[serde(default, rename = "isSynthetic")]
895 pub is_synthetic: Option<bool>,
896 #[serde(default)]
898 pub parent_tool_use_id: Option<String>,
899 #[serde(default)]
901 pub agent_id: Option<String>,
902 #[serde(default)]
904 pub message: Option<InboundUserBody>,
905 #[serde(default)]
908 pub tool_use_result: Option<serde_json::Value>,
909}
910
911#[derive(Debug, Clone, Deserialize)]
913#[non_exhaustive]
914pub struct InboundUserBody {
915 #[serde(default)]
917 pub content: serde_json::Value,
918}
919
920#[derive(Debug, Clone, Deserialize)]
922#[non_exhaustive]
923pub struct InboundToolResult {
924 pub tool_use_id: String,
926 #[serde(default)]
928 pub content: serde_json::Value,
929 #[serde(default)]
931 pub is_error: bool,
932}
933
934impl InboundUserMessage {
935 #[must_use]
937 pub fn tool_results(&self) -> Vec<InboundToolResult> {
938 let Some(blocks) = self.message.as_ref().and_then(|m| m.content.as_array()) else {
939 return vec![];
940 };
941 blocks
942 .iter()
943 .filter(|b| b.get("type").and_then(|t| t.as_str()) == Some("tool_result"))
944 .filter_map(|b| InboundToolResult::deserialize(b).ok())
945 .collect()
946 }
947}
948
949#[derive(Debug, Clone, Deserialize)]
952#[non_exhaustive]
953pub struct StreamEventMessage {
954 pub event: serde_json::Value,
956 #[serde(default)]
958 pub session_id: Option<String>,
959 #[serde(default)]
961 pub ttft_ms: Option<u64>,
962 #[serde(default)]
964 pub parent_tool_use_id: Option<String>,
965}
966
967#[derive(Debug, Clone, Default, Deserialize)]
970#[non_exhaustive]
971pub struct ResultMessage {
972 #[serde(default)]
975 pub subtype: String,
976 #[serde(default)]
978 pub is_error: bool,
979 #[serde(default)]
981 pub result: Option<String>,
982 #[serde(default)]
984 pub errors: Option<Vec<serde_json::Value>>,
985 #[serde(default)]
987 pub session_id: Option<String>,
988 #[serde(default)]
990 pub total_cost_usd: Option<f64>,
991 #[serde(default)]
993 pub ttft_ms: Option<u64>,
994 #[serde(default)]
996 pub duration_ms: Option<u64>,
997 #[serde(default)]
999 pub usage: Option<UsageSummary>,
1000 #[serde(default)]
1002 pub stop_reason: Option<String>,
1003 #[serde(default)]
1005 pub duration_api_ms: Option<u64>,
1006 #[serde(default)]
1008 pub num_turns: Option<u64>,
1009 #[serde(default)]
1011 pub terminal_reason: Option<String>,
1012 #[serde(default)]
1014 pub structured_output: Option<serde_json::Value>,
1015 #[serde(default)]
1017 pub permission_denials: Vec<serde_json::Value>,
1018 #[serde(default, rename = "modelUsage")]
1020 pub model_usage: Option<serde_json::Value>,
1021 #[serde(default)]
1023 pub user_message_uuids: Vec<String>,
1024 #[serde(default)]
1027 pub origin: Option<serde_json::Value>,
1028 #[serde(flatten)]
1030 pub extra: HashMap<String, serde_json::Value>,
1031}
1032
1033impl ResultMessage {
1034 #[must_use]
1036 pub fn is_success(&self) -> bool {
1037 self.subtype == "success" && !self.is_error
1038 }
1039
1040 #[must_use]
1043 pub fn answers(&self, uuid: &str) -> bool {
1044 self.user_message_uuids.iter().any(|u| u.eq_ignore_ascii_case(uuid))
1045 }
1046
1047 #[must_use]
1049 pub fn error_kind(&self) -> TurnErrorKind {
1050 match self.subtype.as_str() {
1051 "error_during_execution" => TurnErrorKind::Execution,
1052 "error_max_turns" => TurnErrorKind::MaxTurns,
1053 "error_max_budget_usd" => TurnErrorKind::MaxBudget,
1054 "error_max_structured_output_retries" => TurnErrorKind::StructuredOutputRetries,
1055 "success" => TurnErrorKind::Api,
1056 other => TurnErrorKind::Other(other.to_string()),
1057 }
1058 }
1059
1060 #[must_use]
1063 pub fn error_message(&self) -> String {
1064 if let Some(r) = self.result.as_ref().filter(|r| self.is_error && !r.is_empty()) {
1065 return r.clone();
1066 }
1067 let details: Vec<String> = self.errors.iter().flatten()
1068 .map(|v| v.as_str().map_or_else(|| v.to_string(), str::to_owned))
1069 .collect();
1070 if details.is_empty() { self.subtype.clone() } else { format!("{}: {}", self.subtype, details.join("; ")) }
1071 }
1072}
1073
1074#[derive(Debug, Clone, PartialEq, Eq)]
1076#[non_exhaustive]
1077pub enum TurnErrorKind {
1078 Execution,
1080 MaxTurns,
1082 MaxBudget,
1084 StructuredOutputRetries,
1086 Api,
1088 SessionClosed,
1090 Cancelled,
1093 Other(String),
1095}
1096
1097#[derive(Debug, Clone, Deserialize, Default)]
1100#[non_exhaustive]
1101pub struct UsageSummary {
1102 #[serde(default)]
1104 pub input_tokens: u64,
1105 #[serde(default)]
1107 pub output_tokens: u64,
1108 #[serde(default)]
1110 pub cache_read_input_tokens: Option<u64>,
1111 #[serde(default)]
1113 pub cache_creation_input_tokens: Option<u64>,
1114 #[serde(default)]
1116 pub cache_creation: Option<serde_json::Value>,
1117}
1118
1119#[derive(Debug, Clone, Deserialize)]
1123#[non_exhaustive]
1124pub struct ControlRequest {
1125 pub request_id: String,
1127 pub request: ControlRequestBody,
1129}
1130
1131#[derive(Debug, Clone, Deserialize)]
1133#[serde(tag = "subtype")]
1134#[non_exhaustive]
1135pub enum ControlRequestBody {
1136 #[serde(rename = "can_use_tool")]
1138 CanUseTool(CanUseToolRequest),
1139 #[serde(rename = "hook_callback")]
1141 HookCallback(HookCallbackRequest),
1142 #[serde(rename = "mcp_message")]
1144 McpMessage(McpMessageRequest),
1145 #[serde(rename = "elicitation")]
1147 Elicitation(ElicitationRequest),
1148 #[serde(rename = "request_user_dialog")]
1151 RequestUserDialog(UserDialogRequest),
1152 #[serde(other)]
1154 Unsupported,
1155}
1156
1157#[derive(Debug, Clone, Deserialize)]
1159#[non_exhaustive]
1160pub struct CanUseToolRequest {
1161 pub tool_name: String,
1163 pub input: serde_json::Value,
1165 #[serde(default)]
1167 pub tool_use_id: Option<String>,
1168 #[serde(default)]
1171 pub permission_suggestions: Option<Vec<serde_json::Value>>,
1172 #[serde(default)]
1174 pub decision_reason: Option<String>,
1175 #[serde(default)]
1177 pub decision_reason_type: Option<String>,
1178 #[serde(default)]
1180 pub mcp_server: Option<serde_json::Value>,
1181 #[serde(default)]
1183 pub blocked_path: Option<String>,
1184 #[serde(default)]
1186 pub classifier_approvable: Option<bool>,
1187 #[serde(default)]
1189 pub suppress_always_allow_rule: Option<bool>,
1190 #[serde(default)]
1192 pub default_to_no: Option<bool>,
1193 #[serde(default)]
1195 pub matched_ask_rule: Option<serde_json::Value>,
1196 #[serde(default)]
1198 pub title: Option<String>,
1199 #[serde(default)]
1201 pub display_name: Option<String>,
1202 #[serde(default)]
1204 pub description: Option<String>,
1205 #[serde(default)]
1207 pub agent_id: Option<String>,
1208 #[serde(default)]
1210 pub requires_user_interaction: Option<bool>,
1211 #[serde(flatten)]
1213 pub extra: HashMap<String, serde_json::Value>,
1214}
1215
1216#[derive(Debug, Clone, Deserialize)]
1218#[non_exhaustive]
1219pub struct ElicitationRequest {
1220 pub mcp_server_name: String,
1222 pub message: String,
1224 #[serde(default)]
1226 pub mode: Option<String>,
1227 #[serde(default)]
1229 pub url: Option<String>,
1230 #[serde(default)]
1232 pub elicitation_id: Option<String>,
1233 #[serde(default)]
1235 pub requested_schema: Option<serde_json::Value>,
1236 #[serde(default)]
1238 pub property_order: Option<Vec<String>>,
1239 #[serde(default)]
1241 pub title: Option<String>,
1242 #[serde(default)]
1244 pub display_name: Option<String>,
1245 #[serde(default)]
1247 pub description: Option<String>,
1248 #[serde(flatten)]
1250 pub extra: HashMap<String, serde_json::Value>,
1251}
1252
1253#[derive(Debug, Clone, Serialize)]
1255pub struct ElicitationResponse {
1256 pub action: ElicitationAction,
1258 #[serde(skip_serializing_if = "Option::is_none")]
1260 pub content: Option<serde_json::Map<String, serde_json::Value>>,
1261}
1262
1263#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
1265#[serde(rename_all = "lowercase")]
1266pub enum ElicitationAction {
1267 Accept,
1269 Decline,
1271 Cancel,
1273}
1274
1275impl ElicitationResponse {
1276 #[must_use]
1278 pub fn accept(content: serde_json::Map<String, serde_json::Value>) -> Self {
1279 Self { action: ElicitationAction::Accept, content: Some(content) }
1280 }
1281 #[must_use]
1283 pub fn decline() -> Self {
1284 Self { action: ElicitationAction::Decline, content: None }
1285 }
1286 #[must_use]
1288 pub fn cancel() -> Self {
1289 Self { action: ElicitationAction::Cancel, content: None }
1290 }
1291}
1292
1293#[derive(Debug, Clone, Deserialize)]
1295#[non_exhaustive]
1296pub struct UserDialogRequest {
1297 pub dialog_kind: String,
1299 #[serde(default)]
1301 pub payload: serde_json::Value,
1302 #[serde(default)]
1304 pub tool_use_id: Option<String>,
1305}
1306
1307#[derive(Debug, Clone, Serialize, PartialEq)]
1310pub struct UserDialogResponse {
1311 pub behavior: UserDialogBehavior,
1313 #[serde(skip_serializing_if = "Option::is_none")]
1316 pub result: Option<serde_json::Value>,
1317}
1318
1319#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
1321#[serde(rename_all = "lowercase")]
1322pub enum UserDialogBehavior {
1323 Completed,
1325 Cancelled,
1327}
1328
1329impl UserDialogResponse {
1330 pub fn completed(result: impl Into<serde_json::Value>) -> Self {
1332 Self { behavior: UserDialogBehavior::Completed, result: Some(result.into()) }
1333 }
1334 #[must_use]
1336 pub fn cancelled() -> Self {
1337 Self { behavior: UserDialogBehavior::Cancelled, result: None }
1338 }
1339}
1340
1341#[derive(Debug, Clone, Deserialize)]
1343#[non_exhaustive]
1344pub struct McpMessageRequest {
1345 pub server_name: String,
1347 pub message: serde_json::Value,
1349}
1350
1351#[derive(Debug, Clone, Deserialize)]
1353#[non_exhaustive]
1354pub struct HookCallbackRequest {
1355 pub callback_id: String,
1357 pub input: HookEventPayload,
1359 #[serde(default)]
1361 pub tool_use_id: Option<String>,
1362 #[serde(default)]
1364 pub issued_at: Option<u64>,
1365}
1366
1367#[derive(Debug, Clone, Deserialize)]
1370#[non_exhaustive]
1371pub struct InboundControlResponse {
1372 pub response: InboundControlResponseBody,
1374}
1375
1376#[derive(Debug, Clone, Deserialize)]
1378#[non_exhaustive]
1379pub struct InboundControlResponseBody {
1380 pub subtype: String, pub request_id: String,
1384 #[serde(default)]
1386 pub response: Option<serde_json::Value>,
1387 #[serde(default)]
1389 pub error: Option<String>,
1390}
1391
1392#[derive(Debug, Clone, Deserialize)]
1395#[non_exhaustive]
1396pub struct HookEventPayload {
1397 pub hook_event_name: HookEventKind,
1399 #[serde(default)]
1401 pub tool_name: Option<String>,
1402 #[serde(default)]
1404 pub tool_input: Option<serde_json::Value>,
1405 #[serde(default)]
1407 pub tool_use_id: Option<String>,
1408 #[serde(default)]
1410 pub error: Option<String>,
1411 #[serde(default)]
1413 pub is_interrupt: Option<bool>,
1414 #[serde(default)]
1416 pub session_id: Option<String>,
1417 #[serde(default)]
1419 pub cwd: Option<String>,
1420 #[serde(default)]
1422 pub file_path: Option<String>,
1423 #[serde(default)]
1425 pub event: Option<String>, #[serde(flatten)]
1428 pub extra: HashMap<String, serde_json::Value>,
1429}
1430
1431#[derive(Debug, Clone, Deserialize)]
1434#[non_exhaustive]
1435pub struct BackgroundTask {
1436 pub task_id: String,
1438 #[serde(default)]
1440 pub run_id: Option<String>,
1441 #[serde(default)]
1443 pub task_type: String,
1444 #[serde(default)]
1446 pub subagent_type: Option<String>,
1447 #[serde(default)]
1449 pub description: String,
1450 #[serde(default)]
1452 pub parent_task_id: Option<String>,
1453 #[serde(default)]
1455 pub ambient: Option<bool>,
1456 #[serde(default)]
1458 pub awaited: Option<bool>,
1459 #[serde(default)]
1461 pub off_host: Option<bool>,
1462}
1463
1464#[derive(Debug, Clone, Deserialize)]
1467#[non_exhaustive]
1468pub struct KeepAliveMessage {
1469 #[serde(flatten)]
1471 pub extra: HashMap<String, serde_json::Value>,
1472}
1473
1474#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
1478pub struct ToolDef {
1479 pub name: String,
1481 pub description: String,
1483 #[serde(skip_serializing_if = "Option::is_none")]
1485 pub input_schema: Option<serde_json::Value>,
1486 #[serde(default, skip_serializing_if = "Option::is_none")]
1488 pub title: Option<String>,
1489 #[serde(default, skip_serializing_if = "Option::is_none")]
1491 pub output_schema: Option<serde_json::Value>,
1492 #[serde(default, skip_serializing_if = "Option::is_none")]
1494 pub annotations: Option<ToolAnnotations>,
1495}
1496
1497#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
1499#[serde(rename_all = "camelCase")]
1500pub struct ToolAnnotations {
1501 #[serde(default, skip_serializing_if = "Option::is_none")]
1503 pub read_only_hint: Option<bool>,
1504 #[serde(default, skip_serializing_if = "Option::is_none")]
1506 pub destructive_hint: Option<bool>,
1507 #[serde(default, skip_serializing_if = "Option::is_none")]
1509 pub idempotent_hint: Option<bool>,
1510 #[serde(default, skip_serializing_if = "Option::is_none")]
1512 pub open_world_hint: Option<bool>,
1513}
1514
1515#[derive(Debug, Clone, Serialize, Deserialize)]
1517pub struct McpManifest {
1518 pub name: String,
1520 pub tools: Vec<ToolDef>,
1522 #[serde(default)]
1524 pub server_info: Option<serde_json::Value>,
1525}
1526
1527#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
1530#[serde(rename_all = "PascalCase")]
1531#[non_exhaustive]
1532pub enum HookEventKind {
1533 PreToolUse,
1535 PostToolUse,
1537 PostToolUseFailure,
1539 PostToolBatch,
1541 Notification,
1543 UserPromptSubmit,
1545 UserPromptExpansion,
1547 SessionStart,
1549 SessionEnd,
1551 Stop,
1553 StopFailure,
1555 SubagentStart,
1557 SubagentStop,
1559 PreCompact,
1561 PostCompact,
1563 PreModelSwitch,
1565 PostModelSwitch,
1567 PermissionRequest,
1569 PermissionDenied,
1571 Setup,
1573 TeammateIdle,
1575 TaskCreated,
1577 TaskCompleted,
1579 Elicitation,
1581 ElicitationResult,
1583 ConfigChange,
1585 WorktreeCreate,
1587 WorktreeRemove,
1589 InstructionsLoaded,
1591 CwdChanged,
1593 FileChanged,
1595 DirectoryAdded,
1597 MessageDisplay,
1599}
1600
1601impl HookEventKind {
1602 #[must_use]
1606 pub fn accepts_additional_context(self) -> bool {
1607 matches!(
1608 self,
1609 Self::PreToolUse
1610 | Self::PostToolUse
1611 | Self::PostToolUseFailure
1612 | Self::PostToolBatch
1613 | Self::UserPromptSubmit
1614 | Self::UserPromptExpansion
1615 | Self::SessionStart
1616 | Self::Setup
1617 | Self::PostModelSwitch
1618 | Self::SubagentStart
1619 | Self::Stop
1620 | Self::SubagentStop
1621 | Self::Notification
1622 )
1623 }
1624}
1625