agent_client_protocol_schema/v2/

client.rs

//! Methods and notifications the client handles/receives.
//!
//! This module defines the Client trait and all associated types for implementing
//! a client that interacts with AI coding agents via the Agent Client Protocol (ACP).

use std::{collections::BTreeMap, sync::Arc};

use derive_more::{Display, From};
#[cfg(feature = "schemars")]
use schemars::Schema;
use serde::{Deserialize, Serialize};
use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};

#[cfg(feature = "unstable_plan_operations")]
use super::PlanRemoved;
#[cfg(feature = "unstable_end_turn_token_usage")]
use super::Usage;
use super::{
    AbsolutePath, ContentBlock, ExtNotification, ExtRequest, ExtResponse, Meta, PlanUpdate,
    SessionConfigOption, SessionId, StopReason, TerminalId, TerminalOutputChunk, TerminalUpdate,
    ToolCallContentChunk, ToolCallId, ToolCallUpdate,
};
use super::{
    CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse,
    ElicitationCapabilities,
};
use crate::{IntoMaybeUndefined, IntoOption, MaybeUndefined};

#[cfg(feature = "unstable_mcp_over_acp")]
use super::mcp::{MCP_MESSAGE_METHOD_NAME, MessageMcpRequest, MessageMcpResponse};

// Session updates

/// Notification containing a session update from the agent.
///
/// Agents can send session updates at any point while the session exists.
///
/// See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#3-agent-reports-output)
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "client", "x-method" = SESSION_UPDATE_NOTIFICATION)))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct UpdateSessionNotification {
    /// The ID of the session this update pertains to.
    pub session_id: SessionId,
    /// The actual update content.
    pub update: SessionUpdate,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl UpdateSessionNotification {
    /// Builds [`UpdateSessionNotification`] with the required notification fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(session_id: impl Into<SessionId>, update: SessionUpdate) -> Self {
        Self {
            session_id: session_id.into(),
            update,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Different types of updates that can be sent while a session exists.
///
/// These updates report messages, progress, and other session activity.
///
/// See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#3-agent-reports-output)
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(tag = "sessionUpdate", rename_all = "snake_case")]
#[non_exhaustive]
pub enum SessionUpdate {
    /// A chunk of the user's message being streamed.
    UserMessageChunk(ContentChunk),
    /// A user message has been created or updated.
    ///
    /// Agents can send this when they accept or replay a user message. When a
    /// client receives another `user_message` update with the same `messageId`,
    /// fields in the new update patch the previous fields for that message.
    UserMessage(UserMessage),
    /// A chunk of the agent's response being streamed.
    AgentMessageChunk(ContentChunk),
    /// An agent message has been created or updated.
    ///
    /// Agents can send this in addition to streamed chunks. When a client
    /// receives another `agent_message` update with the same `messageId`,
    /// fields in the new update patch the previous fields for that message.
    AgentMessage(AgentMessage),
    /// A chunk of the agent's internal reasoning being streamed.
    AgentThoughtChunk(ContentChunk),
    /// An agent thought or reasoning message has been created or updated.
    ///
    /// Agents can send this in addition to streamed chunks. When a client
    /// receives another `agent_thought` update with the same `messageId`,
    /// fields in the new update patch the previous fields for that message.
    AgentThought(AgentThought),
    /// A snapshot of the session's aggregate foreground activity.
    StateUpdate(StateUpdate),
    /// A chunk of tool-call content being streamed.
    ToolCallContentChunk(ToolCallContentChunk),
    /// A tool call has been created or updated.
    ToolCallUpdate(ToolCallUpdate),
    /// An agent-owned terminal has been created or updated.
    TerminalUpdate(TerminalUpdate),
    /// A chunk of bytes appended to an agent-owned terminal's output.
    TerminalOutputChunk(TerminalOutputChunk),
    /// A content update for a plan identified by ID.
    /// See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v2/agent-plan)
    PlanUpdate(PlanUpdate),
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// Removal notice for a plan identified by ID.
    #[cfg(feature = "unstable_plan_operations")]
    PlanRemoved(PlanRemoved),
    /// Available commands are ready or have changed
    AvailableCommandsUpdate(AvailableCommandsUpdate),
    /// Session configuration options have been updated.
    ConfigOptionUpdate(ConfigOptionUpdate),
    /// Session metadata has been updated (title, timestamps, custom metadata)
    SessionInfoUpdate(SessionInfoUpdate),
    /// Context window and cost update for the session.
    UsageUpdate(UsageUpdate),
    /// Information for the user that is not part of session history.
    ///
    /// No Client capability is required. Clients that do not understand or
    /// present notices may ignore them.
    Notice(Notice),
    /// A context compaction has been created or updated.
    CompactionUpdate(CompactionUpdate),
    /// A content block appended to a context compaction's retained summary.
    CompactionSummaryChunk(CompactionSummaryChunk),
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// Announces a child session created and owned by this session, or updates
    /// that ownership association's metadata.
    #[cfg(feature = "unstable_subagents")]
    SubagentUpdate(SubagentUpdate),
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// A message upsert observed in this session's transcript, sent to or
    /// received from another session.
    #[cfg(feature = "unstable_subagents")]
    SessionMessage(SessionMessage),
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// One content block appended to a sent or received session message.
    #[cfg(feature = "unstable_subagents")]
    SessionMessageChunk(SessionMessageChunk),
    /// Custom or future session update.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    ///
    /// Receivers that do not understand this update type should preserve the
    /// raw payload when storing, replaying, proxying, or forwarding session
    /// history, and otherwise ignore it or display it generically.
    #[serde(untagged)]
    Other(OtherSessionUpdate),
}

/// **UNSTABLE**
///
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// A streamed content block of an inter-session message.
///
/// A chunk carries only content. The message's participants and references come from
/// `session_message` upserts, which can arrive before, between, or after its chunks.
#[cfg(feature = "unstable_subagents")]
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct SessionMessageChunk {
    /// Identifier of this message within the enclosing session's transcript.
    pub message_id: MessageId,
    /// A single content block appended to the message.
    pub content: ContentBlock,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    /// This metadata is scoped to the chunk and does not patch stored metadata.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, rename = "_meta")]
    pub meta: Option<Meta>,
}

#[cfg(feature = "unstable_subagents")]
impl SessionMessageChunk {
    /// Builds a single streamed content block without chunk metadata.
    #[must_use]
    pub fn new(message_id: impl Into<MessageId>, content: ContentBlock) -> Self {
        Self {
            message_id: message_id.into(),
            content,
            meta: None,
        }
    }

    /// Sets optional chunk-scoped metadata.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// **UNSTABLE**
///
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// An upsert for an inter-session message.
#[cfg(feature = "unstable_subagents")]
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct SessionMessage {
    /// Identifier of this message within the enclosing session's transcript.
    pub message_id: MessageId,
    /// The sending session.
    ///
    /// Omitted leaves the stored value unchanged; `null` clears it; a value replaces it.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub sender_session_id: MaybeUndefined<SessionId>,
    /// The receiving session.
    ///
    /// Omitted leaves the stored value unchanged; `null` clears it; a value replaces it.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub recipient_session_id: MaybeUndefined<SessionId>,
    /// On an incoming view, the `messageId` of the same message's outgoing view in the
    /// sender's transcript.
    ///
    /// Omitted leaves the stored value unchanged; `null` clears it; a value replaces it. It can arrive
    /// after the message starts streaming.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub sender_message_id: MaybeUndefined<MessageId>,
    /// On an outgoing view, the `messageId` of the same message's incoming view in the
    /// recipient's transcript.
    ///
    /// Omitted leaves the stored value unchanged; `null` clears it; a value replaces it. It can arrive
    /// after the message starts streaming.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub recipient_message_id: MaybeUndefined<MessageId>,
    /// Omitted leaves content unchanged; `null` clears it; a concrete array
    /// replaces the whole content collection.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<VecSkipError<_>>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub content: MaybeUndefined<Vec<ContentBlock>>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        default,
        rename = "_meta",
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

#[cfg(feature = "unstable_subagents")]
impl SessionMessage {
    /// Builds a message upsert with its transcript-local ID.
    #[must_use]
    pub fn new(message_id: impl Into<MessageId>) -> Self {
        Self {
            message_id: message_id.into(),
            sender_session_id: MaybeUndefined::Undefined,
            recipient_session_id: MaybeUndefined::Undefined,
            sender_message_id: MaybeUndefined::Undefined,
            recipient_message_id: MaybeUndefined::Undefined,
            content: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Sets, clears, or leaves unchanged the sending session.
    #[must_use]
    pub fn sender_session_id(
        mut self,
        sender_session_id: impl IntoMaybeUndefined<SessionId>,
    ) -> Self {
        self.sender_session_id = sender_session_id.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the receiving session.
    #[must_use]
    pub fn recipient_session_id(
        mut self,
        recipient_session_id: impl IntoMaybeUndefined<SessionId>,
    ) -> Self {
        self.recipient_session_id = recipient_session_id.into_maybe_undefined();
        self
    }

    /// Links an incoming view to the outgoing view's message ID in the sender's transcript.
    #[must_use]
    pub fn sender_message_id(
        mut self,
        sender_message_id: impl IntoMaybeUndefined<MessageId>,
    ) -> Self {
        self.sender_message_id = sender_message_id.into_maybe_undefined();
        self
    }

    /// Links an outgoing view to the incoming view's message ID in the recipient's transcript.
    #[must_use]
    pub fn recipient_message_id(
        mut self,
        recipient_message_id: impl IntoMaybeUndefined<MessageId>,
    ) -> Self {
        self.recipient_message_id = recipient_message_id.into_maybe_undefined();
        self
    }

    /// Replaces, clears, or leaves unchanged the message content.
    #[must_use]
    pub fn content(mut self, content: impl IntoMaybeUndefined<Vec<ContentBlock>>) -> Self {
        self.content = content.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged message metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

#[cfg(all(test, feature = "unstable_subagents"))]
mod session_message_tests {
    use super::*;
    use serde_json::{Value, json};

    #[test]
    fn transcript_envelopes_and_multimodal_content() {
        for (transcript, sender, recipient, id) in [
            ("parent", "parent", "child", "sent-1"),
            ("child", "parent", "child", "received-9"),
            ("child", "child", "parent", "sent-2"),
        ] {
            let wire = json!({"sessionId": transcript, "update": {
                "sessionUpdate": "session_message", "messageId": id,
                "senderSessionId": sender, "recipientSessionId": recipient, "content": [
                    {"type": "text", "text": "hello"},
                    {"type": "image", "data": "aGVsbG8=", "mimeType": "image/png"}
                ]
            }});
            let decoded: UpdateSessionNotification = serde_json::from_value(wire.clone()).unwrap();
            assert_eq!(serde_json::to_value(decoded).unwrap(), wire);
        }
    }

    #[test]
    fn chunks_and_upserts_share_transcript_local_identity() {
        for (transcript, id) in [("parent", "sent-1"), ("child", "received-9")] {
            let wire = json!({"sessionId": transcript, "update": {
                "sessionUpdate": "session_message_chunk", "messageId": id,
                "content": {"type": "text", "text": "hello"}
            }});
            let decoded: UpdateSessionNotification = serde_json::from_value(wire.clone()).unwrap();
            assert_eq!(serde_json::to_value(decoded).unwrap(), wire);
            let upsert = SessionMessage::new(id)
                .sender_session_id(SessionId::new("parent"))
                .recipient_session_id(SessionId::new("child"))
                .content(vec![]);
            let chunk = SessionMessageChunk::new(
                id,
                ContentBlock::Text(crate::v2::TextContent::new("hello")),
            );
            assert_eq!(chunk.message_id, upsert.message_id);
            assert_eq!(
                serde_json::to_value(SessionUpdate::SessionMessageChunk(chunk)).unwrap(),
                wire["update"]
            );
            assert_eq!(serde_json::to_value(upsert).unwrap()["content"], json!([]));
        }
        // A chunk carries only content, so identity fields on one are not part of it.
        let with_identity = json!({"sessionUpdate": "session_message_chunk", "messageId": "m1",
            "senderSessionId": "parent", "recipientSessionId": "child",
            "senderMessageId": "sent-1", "recipientMessageId": "received-1",
            "content": {"type": "text", "text": "hello"}});
        let decoded: SessionUpdate = serde_json::from_value(with_identity).unwrap();
        assert_eq!(
            serde_json::to_value(decoded).unwrap(),
            json!({"sessionUpdate": "session_message_chunk", "messageId": "m1",
                "content": {"type": "text", "text": "hello"}})
        );
    }

    #[test]
    fn required_ids_and_chunk_content_with_upsert_patch_semantics() {
        for (kind, content) in [
            ("session_message", json!([])),
            (
                "session_message_chunk",
                json!({"type": "text", "text": "hello"}),
            ),
        ] {
            let mut base = json!({"sessionUpdate": kind, "messageId": "m1", "content": content});
            if kind == "session_message" {
                base["senderSessionId"] = json!("parent");
                base["recipientSessionId"] = json!("child");
            }
            {
                let key = "messageId";
                let mut missing = base.clone();
                missing.as_object_mut().unwrap().remove(key);
                assert!(
                    serde_json::from_value::<SessionUpdate>(missing).is_err(),
                    "{kind} {key}"
                );
                let mut null = base.clone();
                null[key] = Value::Null;
                assert!(
                    serde_json::from_value::<SessionUpdate>(null).is_err(),
                    "{kind} {key}"
                );
                let mut non_string = base.clone();
                non_string[key] = json!(42);
                assert!(
                    serde_json::from_value::<SessionUpdate>(non_string).is_err(),
                    "{kind} {key}"
                );
            }
            if kind == "session_message_chunk" {
                for content in [None, Some(Value::Null), Some(json!([]))] {
                    let mut invalid = base.clone();
                    invalid.as_object_mut().unwrap().remove("content");
                    if let Some(content) = content {
                        invalid["content"] = content;
                    }
                    assert!(serde_json::from_value::<SessionUpdate>(invalid).is_err());
                }
            } else {
                for content in [None, Some(Value::Null), Some(json!([])), Some(json!({}))] {
                    let mut wire = base.clone();
                    wire.as_object_mut().unwrap().remove("content");
                    if let Some(content) = content {
                        wire["content"] = content;
                    }
                    let decoded: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
                    let encoded = serde_json::to_value(decoded).unwrap();
                    if wire["content"].is_object() {
                        wire.as_object_mut().unwrap().remove("content");
                    }
                    assert_eq!(encoded, wire);
                }
            }
            for meta in [None, Some(Value::Null), Some(json!({"tag": "value"}))] {
                let mut wire = base.clone();
                if let Some(meta) = meta {
                    wire["_meta"] = meta;
                }
                let decoded: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
                let encoded = serde_json::to_value(decoded).unwrap();
                if kind == "session_message" {
                    assert_eq!(encoded, wire);
                } else if wire["_meta"].is_null() {
                    assert_eq!(encoded, base);
                } else {
                    assert_eq!(encoded, wire);
                }
            }
        }
        let metadata_only = json!({"sessionUpdate": "session_message",
            "messageId": "m1", "senderSessionId": "parent",
            "recipientSessionId": "child", "_meta": {"tag": "value"}});
        let decoded: SessionUpdate = serde_json::from_value(metadata_only.clone()).unwrap();
        assert_eq!(serde_json::to_value(decoded).unwrap(), metadata_only);
        let cleared = SessionMessage::new("m1")
            .sender_session_id(SessionId::new("parent"))
            .recipient_session_id(SessionId::new("child"))
            .content(None)
            .meta(None);
        assert_eq!(
            serde_json::to_value(cleared).unwrap(),
            json!({"messageId": "m1", "senderSessionId": "parent",
                "recipientSessionId": "child", "content": null, "_meta": null})
        );
    }

    #[cfg(feature = "schemars")]
    #[test]
    fn schemas_require_ids_and_chunk_content_but_not_upsert_content() {
        let upsert = serde_json::to_value(schemars::schema_for!(SessionMessage)).unwrap();
        let required = upsert["required"].as_array().unwrap();
        assert_eq!(required, &vec![json!("messageId")]);
        let chunk = serde_json::to_value(schemars::schema_for!(SessionMessageChunk)).unwrap();
        let required = chunk["required"].as_array().unwrap();
        assert_eq!(required.len(), 2);
        assert!(required.contains(&json!("messageId")));
        assert!(required.contains(&json!("content")));
    }

    #[test]
    fn endpoints_can_arrive_late_or_be_omitted_from_later_events() {
        let block = ContentBlock::Text(crate::v2::TextContent::new("hello"));
        let minimal = SessionMessage::new("m1");
        let first = SessionMessageChunk::new("m1", block.clone());
        assert_eq!(
            serde_json::to_value(&minimal).unwrap(),
            json!({"messageId": "m1"})
        );
        assert_eq!(
            serde_json::to_value(&first).unwrap(),
            json!({"messageId": "m1", "content": {"type": "text", "text": "hello"}})
        );
        let enriched = SessionMessage::new("m1")
            .sender_session_id(SessionId::new("parent"))
            .recipient_session_id(SessionId::new("child"));
        assert_eq!(
            enriched.sender_session_id,
            MaybeUndefined::Value(SessionId::new("parent"))
        );
        assert_eq!(
            enriched.recipient_session_id,
            MaybeUndefined::Value(SessionId::new("child"))
        );
        let later = SessionMessage::new("m1").sender_session_id(SessionId::new("parent"));
        assert_eq!(
            later.sender_session_id,
            MaybeUndefined::Value(SessionId::new("parent"))
        );
        assert_eq!(later.recipient_session_id, MaybeUndefined::Undefined);
        let more = SessionMessageChunk::new("m1", block);
        for update in [
            SessionUpdate::SessionMessage(minimal),
            SessionUpdate::SessionMessageChunk(first),
            SessionUpdate::SessionMessage(enriched),
            SessionUpdate::SessionMessage(later),
            SessionUpdate::SessionMessageChunk(more),
        ] {
            let wire = serde_json::to_value(&update).unwrap();
            let decoded: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
            assert_eq!(serde_json::to_value(decoded).unwrap(), wire);
        }
    }

    #[test]
    fn null_endpoints_clear_invalid_are_absent_but_message_id_is_required() {
        let mut base = json!({"sessionUpdate": "session_message", "messageId": "m1",
            "senderSessionId": null, "recipientSessionId": 42});
        let decoded: SessionUpdate = serde_json::from_value(base.clone()).unwrap();
        let encoded = serde_json::to_value(decoded).unwrap();
        base.as_object_mut().unwrap().remove("recipientSessionId");
        assert_eq!(encoded, base);
        for bad in [Value::Null, json!(42)] {
            let mut invalid = base.clone();
            invalid["messageId"] = bad;
            assert!(serde_json::from_value::<SessionUpdate>(invalid).is_err());
        }
    }

    #[test]
    fn message_references_link_views_and_can_arrive_late() {
        let block = ContentBlock::Text(crate::v2::TextContent::new("hello"));
        let incoming = SessionMessage::new("received-1")
            .sender_session_id(SessionId::new("parent"))
            .recipient_session_id(SessionId::new("child"))
            .sender_message_id(MessageId::new("sent-1"))
            .content(vec![block]);
        // The outgoing view gets its reference after it started, with a metadata-only upsert.
        let outgoing =
            SessionMessage::new("sent-1").recipient_message_id(MessageId::new("received-1"));
        for (update, wire) in [
            (
                SessionUpdate::SessionMessage(incoming),
                json!({"sessionUpdate": "session_message", "messageId": "received-1",
                    "senderSessionId": "parent", "recipientSessionId": "child",
                    "senderMessageId": "sent-1", "content": [{"type": "text", "text": "hello"}]}),
            ),
            (
                SessionUpdate::SessionMessage(outgoing),
                json!({"sessionUpdate": "session_message", "messageId": "sent-1",
                    "recipientMessageId": "received-1"}),
            ),
        ] {
            assert_eq!(serde_json::to_value(&update).unwrap(), wire);
            let decoded: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
            assert_eq!(decoded, update);
        }

        let mut wire = json!({"sessionUpdate": "session_message", "messageId": "m1",
            "senderMessageId": null, "recipientMessageId": 42});
        let decoded: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
        wire.as_object_mut().unwrap().remove("recipientMessageId");
        assert_eq!(
            serde_json::to_value(decoded).unwrap(),
            wire,
            "null clears a reference and a malformed one is not supplied"
        );
    }
}

#[cfg(all(test, not(feature = "unstable_subagents")))]
mod disabled_session_message_tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn preserves_both_unknown_message_discriminators() {
        for (kind, content) in [
            ("session_message", json!([])),
            (
                "session_message_chunk",
                json!({"type": "text", "text": "hello"}),
            ),
        ] {
            let wire = json!({"sessionUpdate": kind, "messageId": "m1",
                "senderSessionId": "parent", "recipientSessionId": "child", "content": content});
            let decoded: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
            assert!(matches!(decoded, SessionUpdate::Other(_)));
            assert_eq!(serde_json::to_value(decoded).unwrap(), wire);
        }
    }
}

/// Severity hint for a session notice.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum NoticeSeverity {
    /// Informational notice.
    Info,
    /// Warning notice.
    Warning,
    /// Error notice.
    Error,
    /// Custom or future notice severity.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Other unknown values are reserved for future ACP severities.
    #[serde(untagged)]
    Other(String),
}

/// Fire-and-forget information for the user.
///
/// Notices are live events rather than session history. Agents must not rely on
/// a notice being received, displayed, or seen by the user.
/// No Client capability is required, and unsupported Clients may ignore notices.
///
/// See protocol docs: [Session Notices](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#session-notices)
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Notice {
    /// Presentation severity hint.
    pub severity: NoticeSeverity,
    /// Required non-empty plain-text title that can stand alone.
    #[cfg_attr(feature = "schemars", schemars(length(min = 1)))]
    pub title: String,
    /// Optional plain-text detail or guidance.
    ///
    /// Omitted and `null` are equivalent and mean no description was supplied.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub description: Option<String>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, rename = "_meta")]
    pub meta: Option<Meta>,
}

impl Notice {
    /// Builds a notice with the required fields set and optional fields omitted.
    #[must_use]
    pub fn new(severity: NoticeSeverity, title: impl Into<String>) -> Self {
        Self {
            severity,
            title: title.into(),
            description: None,
            meta: None,
        }
    }

    /// Sets or clears the optional description.
    #[must_use]
    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
        self.description = description.into_option();
        self
    }

    /// Sets or clears notice-scoped metadata.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Unique identifier for a context compaction within a session.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
#[serde(transparent)]
#[from(forward)]
#[non_exhaustive]
pub struct CompactionId(pub Arc<str>);

impl CompactionId {
    /// Wraps a protocol string as a typed [`CompactionId`].
    #[must_use]
    pub fn new(id: impl Into<Self>) -> Self {
        id.into()
    }
}

/// Lifecycle state of a context compaction.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum CompactionStatus {
    /// Compaction has started and has not finished.
    #[default]
    InProgress,
    /// Compaction finished successfully.
    Completed,
    /// Compaction finished unsuccessfully.
    Failed,
    /// Compaction was cancelled before it finished.
    Cancelled,
    /// Custom or future compaction status.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Other unknown values are reserved for future ACP statuses.
    #[serde(untagged)]
    Other(String),
}

/// A context compaction upsert. The first notification fixes the compaction's
/// timeline position. Later updates with the same ID patch that entity in place.
///
/// `summary`, `error`, and `_meta` have patch semantics: omission leaves the
/// stored value unchanged, `null` clears it, and a concrete value replaces it.
/// `summary: []` also clears the summary. A concrete `_meta` object patches the
/// stored metadata by top-level key instead of replacing it.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CompactionUpdate {
    /// The Agent-owned ID of this compaction, unique within the session.
    pub compaction_id: CompactionId,
    /// Current lifecycle status.
    pub status: CompactionStatus,
    /// Complete replacement user-displayable summary content for the compaction.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<VecSkipError<_>>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub summary: MaybeUndefined<Vec<ContentBlock>>,
    /// Human-readable error details for the compaction.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub error: MaybeUndefined<String>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

impl CompactionUpdate {
    /// Builds a compaction update with optional patch fields omitted.
    #[must_use]
    pub fn new(compaction_id: impl Into<CompactionId>, status: CompactionStatus) -> Self {
        Self {
            compaction_id: compaction_id.into(),
            status,
            summary: MaybeUndefined::Undefined,
            error: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Sets, clears, or omits the complete retained summary patch.
    #[must_use]
    pub fn summary(mut self, summary: impl IntoMaybeUndefined<Vec<ContentBlock>>) -> Self {
        self.summary = summary.into_maybe_undefined();
        self
    }

    /// Sets, clears, or omits the error details patch.
    #[must_use]
    pub fn error(mut self, error: impl IntoMaybeUndefined<String>) -> Self {
        self.error = error.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged compaction metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

/// A content block appended to a compaction's summary. A first-seen ID creates
/// an in-progress compaction. Chunks append in receive order.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CompactionSummaryChunk {
    /// ID of the compaction whose summary receives this content.
    pub compaction_id: CompactionId,
    /// One content block to append.
    pub content: ContentBlock,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    /// This metadata is scoped to the chunk and does not patch stored metadata.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, rename = "_meta")]
    pub meta: Option<Meta>,
}

impl CompactionSummaryChunk {
    /// Builds a summary chunk without metadata.
    #[must_use]
    pub fn new(compaction_id: impl Into<CompactionId>, content: ContentBlock) -> Self {
        Self {
            compaction_id: compaction_id.into(),
            content,
            meta: None,
        }
    }

    /// Sets or clears chunk-scoped metadata.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// **UNSTABLE**
///
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// Notification that the enclosing parent session created and owns a child session.
///
/// Later updates modify the existing association's metadata, not its ownership.
///
/// Sent on the immediate parent session. The first update for an unknown
/// `sessionId` announces the child and MUST be sent
/// before any live request or notification bearing the child's session ID,
/// including messages naming it as sender or recipient. Child events are
/// delivered automatically; no separate child load, resume, or subscription is needed.
/// Understanding this update, registering child sessions, and applying their
/// operation restrictions are baseline v2 requirements; no Client capability
/// is required.
///
/// Only `sessionId` is required. Other fields have
/// patch semantics: omitted fields leave the stored value unchanged, `null`
/// clears or unsets the value, and concrete values replace it. A concrete
/// `_meta` object instead patches the stored metadata by top-level key. For
/// `state`, `null` removes the current state report and leaves activity
/// unconfirmed; it does not report idle or cancellation. A child whose capabilities are
/// unset permits no Client-initiated session mutations.
///
/// `cwd` and `additionalDirectories` report where the Agent placed the child;
/// while unset, each inherits the immediate parent's effective value.
/// The title and description provide the parent's display metadata for the
/// child. Agents SHOULD mirror known child state changes in the parent's
/// `state` using the same `StateUpdate` snapshot as the
/// ordinary `state_update` notification on the child session. This reports
/// child state, not a separate parent-owned lifecycle. Consumers should
/// treat duplicate reports idempotently.
/// Completing or cancelling work does not end the association: the parent may
/// message the same child again. Individual messages and their outcomes do not
/// change this association.
#[cfg(feature = "unstable_subagents")]
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct SubagentUpdate {
    /// The opaque session ID identifying the child in all ACP messages.
    pub session_id: SessionId,
    /// The parent's human-readable display title for this child. It need not be unique.
    ///
    /// Optional and nullable. Omitted means unchanged; `null` clears it. If no
    /// title is set, the Client chooses a fallback presentation.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub title: MaybeUndefined<String>,
    /// The parent's human-readable description of the child's role or purpose.
    ///
    /// Optional and nullable. Omitted means unchanged; `null` clears it. This is
    /// current display metadata, not the history of instructions sent to the child.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub description: MaybeUndefined<String>,
    /// Client-initiated session mutations permitted for this subagent session.
    ///
    /// Read-only operations retain their normal protocol semantics and
    /// capability requirements.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub capabilities: MaybeUndefined<SubagentSessionCapabilities>,
    /// The child's current foreground state, mirrored onto its parent association.
    ///
    /// Optional and nullable. Omitted means unchanged; `null` removes the
    /// current report and leaves activity unconfirmed (not idle or cancelled).
    /// A concrete `StateUpdate` replaces the entire previous snapshot.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub state: MaybeUndefined<StateUpdate>,
    /// The child's working directory. Must be an absolute path.
    ///
    /// Optional and nullable. Omitted means unchanged; `null` clears the
    /// reported value. While unset, the child inherits its immediate parent's
    /// effective working directory.
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub cwd: MaybeUndefined<AbsolutePath>,
    /// Additional workspace roots for the child. Each path must be absolute.
    ///
    /// Optional and nullable. Omitted means unchanged; `null` clears the
    /// reported value. While unset, the child inherits its immediate parent's
    /// effective additional directories, independently of `cwd`. A concrete
    /// array replaces the whole list; `[]` reports no additional directories.
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub additional_directories: MaybeUndefined<Vec<AbsolutePath>>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

#[cfg(feature = "unstable_subagents")]
impl SubagentUpdate {
    /// Builds a subagent upsert with only its required session ID set.
    #[must_use]
    pub fn new(session_id: impl Into<SessionId>) -> Self {
        Self {
            session_id: session_id.into(),
            title: MaybeUndefined::Undefined,
            description: MaybeUndefined::Undefined,
            capabilities: MaybeUndefined::Undefined,
            state: MaybeUndefined::Undefined,
            cwd: MaybeUndefined::Undefined,
            additional_directories: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Sets, clears, or leaves unchanged the parent's display title for the child.
    #[must_use]
    pub fn title(mut self, title: impl IntoMaybeUndefined<String>) -> Self {
        self.title = title.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the parent's description of the child.
    #[must_use]
    pub fn description(mut self, description: impl IntoMaybeUndefined<String>) -> Self {
        self.description = description.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the permitted client-initiated session mutations.
    #[must_use]
    pub fn capabilities(
        mut self,
        capabilities: impl IntoMaybeUndefined<SubagentSessionCapabilities>,
    ) -> Self {
        self.capabilities = capabilities.into_maybe_undefined();
        self
    }

    /// Replaces, clears, or leaves unchanged the child's mirrored state snapshot.
    #[must_use]
    pub fn state(mut self, state: impl IntoMaybeUndefined<StateUpdate>) -> Self {
        self.state = state.into_maybe_undefined();
        self
    }

    /// Sets, clears, or leaves unchanged the child's working directory.
    ///
    /// While unset, the child inherits its parent's working directory.
    #[must_use]
    pub fn cwd(mut self, cwd: impl IntoMaybeUndefined<AbsolutePath>) -> Self {
        self.cwd = cwd.into_maybe_undefined();
        self
    }

    /// Replaces, clears, or leaves unchanged the child's additional directories.
    ///
    /// While unset, the child inherits its parent's additional directories.
    #[must_use]
    pub fn additional_directories(
        mut self,
        additional_directories: impl IntoMaybeUndefined<Vec<AbsolutePath>>,
    ) -> Self {
        self.additional_directories = additional_directories.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged subagent metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

/// **UNSTABLE**
///
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// Client-initiated session mutations permitted for a specific subagent session.
///
/// A mutation requires an explicit per-child capability; support for the method
/// on ordinary sessions does not grant support on a child.
#[cfg(feature = "unstable_subagents")]
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct SubagentSessionCapabilities {
    /// Permits the client to cancel this child's current work without ending
    /// the session. Omitted and `null` are equivalent and mean unsupported; an object (including
    /// `{}`) means supported.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub cancel: Option<SessionCancelCapabilities>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

#[cfg(feature = "unstable_subagents")]
impl SubagentSessionCapabilities {
    /// Builds an empty capability set; cancellation is disabled.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets or removes permission to cancel this child's current work.
    #[must_use]
    pub fn cancel(mut self, cancel: impl IntoOption<SessionCancelCapabilities>) -> Self {
        self.cancel = cancel.into_option();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// **UNSTABLE**
///
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// Capability to cancel work in a subagent session without ending that session.
///
/// Supplying `{}` advertises support; an omitted or `null` `cancel` does not.
#[cfg(feature = "unstable_subagents")]
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct SessionCancelCapabilities {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

#[cfg(feature = "unstable_subagents")]
impl SessionCancelCapabilities {
    /// Builds an empty capability object advertising cancellation support.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Custom or future session update payload.
///
/// This preserves the unknown `sessionUpdate` discriminator and the rest of the
/// update object for clients that store, replay, proxy, or forward session
/// history.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[cfg_attr(feature = "schemars", schemars(transform = other_session_update_schema))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct OtherSessionUpdate {
    /// Custom or future session update type.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    #[serde(rename = "sessionUpdate")]
    pub session_update: String,
    /// Additional fields from the unknown update payload.
    #[serde(flatten)]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl OtherSessionUpdate {
    /// Builds [`OtherSessionUpdate`] from an unknown discriminator and preserves the remaining extension fields.
    #[must_use]
    pub fn new(
        session_update: impl Into<String>,
        mut fields: BTreeMap<String, serde_json::Value>,
    ) -> Self {
        fields.remove("sessionUpdate");
        Self {
            session_update: session_update.into(),
            fields,
        }
    }
}

impl<'de> Deserialize<'de> for OtherSessionUpdate {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut fields = BTreeMap::<String, serde_json::Value>::deserialize(deserializer)?;
        let session_update = fields
            .remove("sessionUpdate")
            .ok_or_else(|| serde::de::Error::missing_field("sessionUpdate"))?;
        let serde_json::Value::String(session_update) = session_update else {
            return Err(serde::de::Error::custom("`sessionUpdate` must be a string"));
        };

        if is_known_session_update(&session_update) {
            return Err(serde::de::Error::custom(format!(
                "known session update `{session_update}` did not match its schema"
            )));
        }

        Ok(Self {
            session_update,
            fields,
        })
    }
}

fn is_known_session_update(session_update: &str) -> bool {
    if session_update == "notice" {
        return true;
    }
    if matches!(
        session_update,
        "compaction_update" | "compaction_summary_chunk"
    ) {
        return true;
    }
    #[cfg(feature = "unstable_plan_operations")]
    if session_update == "plan_removed" {
        return true;
    }
    #[cfg(feature = "unstable_subagents")]
    if matches!(
        session_update,
        "subagent_update" | "session_message" | "session_message_chunk"
    ) {
        return true;
    }
    matches!(
        session_update,
        "user_message_chunk"
            | "user_message"
            | "agent_message_chunk"
            | "agent_message"
            | "agent_thought_chunk"
            | "agent_thought"
            | "state_update"
            | "tool_call_content_chunk"
            | "tool_call_update"
            | "terminal_update"
            | "terminal_output_chunk"
            | "plan_update"
            | "available_commands_update"
            | "config_option_update"
            | "session_info_update"
            | "usage_update"
    )
}

#[cfg(feature = "schemars")]
fn other_session_update_schema(schema: &mut Schema) {
    super::schema_util::reject_known_string_discriminators(
        schema,
        "sessionUpdate",
        &[
            "user_message_chunk",
            "user_message",
            "agent_message_chunk",
            "agent_message",
            "agent_thought_chunk",
            "agent_thought",
            "state_update",
            "tool_call_content_chunk",
            "tool_call_update",
            "terminal_update",
            "terminal_output_chunk",
            "plan_update",
            "available_commands_update",
            "config_option_update",
            "session_info_update",
            #[cfg(feature = "unstable_plan_operations")]
            "plan_removed",
            "usage_update",
            "notice",
            "compaction_update",
            "compaction_summary_chunk",
            #[cfg(feature = "unstable_subagents")]
            "subagent_update",
            #[cfg(feature = "unstable_subagents")]
            "session_message",
            #[cfg(feature = "unstable_subagents")]
            "session_message_chunk",
        ],
    );
}

/// Session configuration options have been updated.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ConfigOptionUpdate {
    /// The full set of configuration options and their current values.
    #[serde_as(deserialize_as = "VecSkipError<_>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-skip-invalid-items" = true)))]
    pub config_options: Vec<SessionConfigOption>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl ConfigOptionUpdate {
    /// Builds [`ConfigOptionUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(config_options: Vec<SessionConfigOption>) -> Self {
        Self {
            config_options,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Update to session metadata. All fields are optional to support partial updates.
///
/// Agents send this notification to update session information like title or custom metadata.
/// This allows clients to display dynamic session names and track session state changes.
///
/// Omitted fields leave the existing session info unchanged. `null` clears the
/// corresponding value. A concrete `_meta` object patches the stored metadata by
/// top-level key.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct SessionInfoUpdate {
    /// Human-readable title for the session. Set to null to clear.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub title: MaybeUndefined<String>,
    /// RFC 3339 timestamp of last activity. Set to null to clear.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "format" = "date-time")))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub updated_at: MaybeUndefined<String>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

impl SessionInfoUpdate {
    /// Builds [`SessionInfoUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Human-readable title for the session. Set to null to clear.
    #[must_use]
    pub fn title(mut self, title: impl IntoMaybeUndefined<String>) -> Self {
        self.title = title.into_maybe_undefined();
        self
    }

    /// RFC 3339 timestamp of last activity. Set to null to clear.
    #[must_use]
    pub fn updated_at(mut self, updated_at: impl IntoMaybeUndefined<String>) -> Self {
        self.updated_at = updated_at.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged session metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

/// Context window and cost update for a session.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct UsageUpdate {
    /// Tokens currently in context.
    pub used: u64,
    /// Total context window size in tokens.
    pub size: u64,
    /// Cumulative session cost.
    ///
    /// Omitted leaves the last reported cost unchanged; `null` clears it; a value replaces it.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub cost: MaybeUndefined<Cost>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl UsageUpdate {
    /// Builds [`UsageUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(used: u64, size: u64) -> Self {
        Self {
            used,
            size,
            cost: MaybeUndefined::Undefined,
            meta: None,
        }
    }

    /// Sets, clears, or leaves unchanged the cumulative session cost.
    #[must_use]
    pub fn cost(mut self, cost: impl IntoMaybeUndefined<Cost>) -> Self {
        self.cost = cost.into_maybe_undefined();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// A snapshot of the session's aggregate foreground activity.
///
/// Foreground work is the agent's active response or workflow in the session,
/// including model processing, tool execution, and waiting for user action needed
/// to continue that work. It can start with a prompt or be agent-initiated, for
/// example to pursue an ongoing goal or follow up on a completed background task.
/// Either way, the agent MUST report `running` when foreground work starts,
/// or `requires_action` if it starts blocked on user action, and `idle` when it
/// ends. The agent SHOULD include a stop reason on that idle update.
/// Agent-initiated work does not require a prompt request or a synthetic user
/// message.
///
/// `running` may precede user-message insertion, for example during a foreground
/// hook. It is not acknowledgment of insertion, and rejecting a prompt does not
/// itself end foreground work.
///
/// Background activity can continue and emit other `session/update` notifications
/// while `idle`. Those notifications, including a detached task's progress or
/// completion, do not by themselves change this state. A permission request only
/// warrants `requires_action` when foreground work is blocked on user action.
///
/// The agent SHOULD report `requires_action` when the foreground workflow as a
/// whole cannot progress without user action, including permissions or elicitations.
/// Once reported, it MUST report `running` when progress resumes, or `idle` when
/// work ends without resuming.
/// If other foreground work can progress, the state remains `running`. Resolving
/// one of several requests does not itself change the state. Agents SHOULD ignore
/// responses for work that has already ended rather than use them to resume it.
///
/// A new session defaults to idle until a state update reports otherwise.
/// Resume MUST send a current-state snapshot after any replay and before its
/// response. The snapshot reports foreground state after resuming.
/// The response alone does not imply idle.
/// Repeated snapshots are idempotent, not additional work, completions, or usage.
/// A repeated state may carry updated information without another state transition.
/// The agent MUST report `idle` when no foreground activity remains. Completing
/// an individual activity while other foreground work continues does not require
/// an idle boundary. Local commands use the same lifecycle even without model work.
///
/// See protocol docs: [Session States](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#session-states)
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "state", rename_all = "snake_case")]
#[non_exhaustive]
pub enum StateUpdate {
    /// Foreground work is in progress.
    Running(RunningStateUpdate),
    /// No foreground work is active. Background activity may continue.
    Idle(IdleStateUpdate),
    /// Foreground work is blocked on user action.
    RequiresAction(RequiresActionStateUpdate),
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// The Agent cannot currently determine foreground activity.
    /// This replaces previously confirmed activity without ending the work or session.
    #[cfg(feature = "unstable_subagents")]
    Unknown(UnknownStateUpdate),
    /// Custom or future session state.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    ///
    /// Unless the Client advertised support for this state, Agents MUST still
    /// report the standard states.
    /// Clients MUST NOT treat an unrecognized state as `idle` or present the
    /// previous state as confirmed, and show a generic busy state until a known
    /// state arrives.
    #[serde(untagged)]
    Other(OtherStateUpdate),
}

/// Foreground work is in progress.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct RunningStateUpdate {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl RunningStateUpdate {
    /// Builds [`RunningStateUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// No foreground work is active. Background activity may continue.
///
/// Agents SHOULD include a `stopReason` when the idle transition ends foreground
/// work. An idle update that does not end foreground work need not include one.
/// Receivers treat an omitted, `null`, or malformed `stopReason` as the agent not
/// reporting one.
/// Repeated or resume snapshots may carry the last stop reason for context.
/// They MUST NOT be counted as new completions, cancellations, or additional usage.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "schemars", schemars(transform = idle_state_update_schema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct IdleStateUpdate {
    /// Indicates why foreground work stopped, with any fields of that stop reason.
    #[serde(flatten)]
    pub stop_reason: Option<StopReason>,
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// Token usage for completed foreground work.
    ///
    /// Optional. Omitted and `null` are equivalent and mean the agent is not reporting token
    /// usage for this state update.
    #[cfg(feature = "unstable_end_turn_token_usage")]
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub usage: Option<Box<Usage>>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl IdleStateUpdate {
    /// Builds [`IdleStateUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Indicates why foreground work stopped.
    #[must_use]
    pub fn stop_reason(mut self, stop_reason: impl IntoOption<StopReason>) -> Self {
        self.stop_reason = stop_reason.into_option();
        self
    }

    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// Token usage for completed foreground work.
    #[cfg(feature = "unstable_end_turn_token_usage")]
    #[must_use]
    pub fn usage(mut self, usage: impl IntoOption<Usage>) -> Self {
        self.usage = usage.into_option().map(Box::new);
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Makes the schema check stop reasons and keeps their default-on-error hint.
///
/// Flattening `Option<StopReason>` adds an empty `{}` branch to the `anyOf`. It
/// matches any value, so the stop reason branches would check nothing; this
/// replaces it with a branch for an omitted or `null` `stopReason`. Flattening
/// also removes the `stopReason` property that carried
/// `x-deserialize-default-on-error`, which SDKs generated from the schema rely on
/// to tolerate a malformed value, so this adds it back as a shared property.
#[cfg(feature = "schemars")]
fn idle_state_update_schema(schema: &mut Schema) {
    if let Some(properties) = schema
        .get_mut("properties")
        .and_then(serde_json::Value::as_object_mut)
    {
        properties.insert(
            "stopReason".into(),
            serde_json::json!({
                "description": "Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons)",
                "type": ["string", "null"],
                "x-deserialize-default-on-error": true
            }),
        );
    }
    let Some(variants) = schema
        .get_mut("anyOf")
        .and_then(serde_json::Value::as_array_mut)
    else {
        return;
    };
    for variant in variants {
        if variant.as_object().is_some_and(serde_json::Map::is_empty) {
            *variant = serde_json::json!({
                "title": "none",
                "description": "No stop reason: `stopReason` is omitted or `null`.",
                "type": "object",
                "properties": {
                    "stopReason": { "type": "null" }
                }
            });
        }
    }
}

/// The foreground workflow as a whole is blocked on user action.
///
/// Agents SHOULD report this state when foreground work cannot progress without
/// user action. Pending permissions or elicitations alone do not imply this
/// state if other foreground work can progress, or if the requests belong only
/// to independent background activity. Once reported, agents MUST report
/// `running` when progress resumes, or `idle` if the work ends without resuming.
/// Responding to one request does not itself imply `running`.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct RequiresActionStateUpdate {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl RequiresActionStateUpdate {
    /// Builds [`RequiresActionStateUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// **UNSTABLE**
///
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// The Agent cannot currently determine foreground activity.
///
/// Report this when activity becomes unobservable, not merely because the session
/// has been quiet. The Client MUST stop presenting the previous state as confirmed
/// current activity, but may retain it as last known. A later state replaces this
/// snapshot normally.
///
/// This is not a task outcome or session closure. It does not cancel work, resolve
/// pending requests, or revoke capabilities; capabilities are updated separately.
#[cfg(feature = "unstable_subagents")]
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct UnknownStateUpdate {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default, rename = "_meta")]
    pub meta: Option<Meta>,
}

#[cfg(feature = "unstable_subagents")]
impl UnknownStateUpdate {
    /// Builds an unknown-activity state.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets optional metadata for this state snapshot.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Custom or future session state payload.
///
/// This preserves the unknown `state` discriminator and the rest of the state
/// object for clients that store, replay, proxy, or forward session history.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[cfg_attr(feature = "schemars", schemars(transform = other_state_update_schema))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct OtherStateUpdate {
    /// Custom or future session state.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    #[serde(rename = "state")]
    pub state: String,
    /// Additional fields from the unknown state payload.
    #[serde(flatten)]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl OtherStateUpdate {
    /// Builds [`OtherStateUpdate`] from an unknown discriminator and preserves the remaining extension fields.
    #[must_use]
    pub fn new(state: impl Into<String>, mut fields: BTreeMap<String, serde_json::Value>) -> Self {
        fields.remove("state");
        Self {
            state: state.into(),
            fields,
        }
    }
}

impl<'de> Deserialize<'de> for OtherStateUpdate {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut fields = BTreeMap::<String, serde_json::Value>::deserialize(deserializer)?;
        let state = fields
            .remove("state")
            .ok_or_else(|| serde::de::Error::missing_field("state"))?;
        let serde_json::Value::String(state) = state else {
            return Err(serde::de::Error::custom("`state` must be a string"));
        };

        if is_known_state_update(&state) {
            return Err(serde::de::Error::custom(format!(
                "known state update `{state}` did not match its schema"
            )));
        }

        Ok(Self { state, fields })
    }
}

const KNOWN_STATE_UPDATE_STATES: &[&str] = &[
    "running",
    "idle",
    "requires_action",
    #[cfg(feature = "unstable_subagents")]
    "unknown",
];

fn is_known_state_update(state: &str) -> bool {
    KNOWN_STATE_UPDATE_STATES.contains(&state)
}

#[cfg(feature = "schemars")]
fn other_state_update_schema(schema: &mut Schema) {
    super::schema_util::reject_known_string_discriminators(
        schema,
        "state",
        KNOWN_STATE_UPDATE_STATES,
    );
}

/// Cost information for a session.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Cost {
    /// Total cumulative cost for session.
    pub amount: f64,
    /// Unit of `amount`: an ISO 4217 currency code (e.g., "USD", "EUR") for money, or another
    /// unit such as "credits".
    pub currency: String,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl Cost {
    /// Builds [`Cost`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(amount: f64, currency: impl Into<String>) -> Self {
        Self {
            amount,
            currency: currency.into(),
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// A streamed item of message content.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ContentChunk {
    /// A unique identifier for the message this chunk belongs to.
    ///
    /// All chunks belonging to the same message share the same `messageId`.
    /// Chunks for different messages can interleave.
    pub message_id: MessageId,
    /// A single item of content
    pub content: ContentBlock,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    /// This metadata is scoped to the chunk and does not patch stored metadata.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl ContentChunk {
    /// Builds [`ContentChunk`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(content: ContentBlock, message_id: impl Into<MessageId>) -> Self {
        Self {
            content,
            message_id: message_id.into(),
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize. This field is chunk-scoped.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// A user message upsert.
///
/// Only `messageId` is required. `content` has patch semantics:
/// an omitted field leaves existing message content unchanged, `null` clears the
/// value, and a concrete array replaces the previous value. For a new
/// `messageId`, omitted `content` starts empty. `content` is replaced as a
/// whole array; send `[]` or `null` to clear it.
///
/// Message updates and chunks are applied in the order they are received. When
/// a `user_message` update includes `content`, that array replaces any content
/// previously accumulated for the message, including content from earlier
/// chunks. Later chunks with the same `messageId` append to the current
/// content.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct UserMessage {
    /// A unique identifier for the message.
    pub message_id: MessageId,
    /// Complete replacement content for this message.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<VecSkipError<_>>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub content: MaybeUndefined<Vec<ContentBlock>>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

impl UserMessage {
    /// Builds [`UserMessage`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(message_id: impl Into<MessageId>) -> Self {
        Self {
            message_id: message_id.into(),
            content: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Complete replacement content for this message.
    #[must_use]
    pub fn content(mut self, content: impl IntoMaybeUndefined<Vec<ContentBlock>>) -> Self {
        self.content = content.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged message metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

/// An agent message upsert.
///
/// Only `messageId` is required. `content` has patch semantics:
/// an omitted field leaves existing message content unchanged, `null` clears the
/// value, and a concrete array replaces the previous value. For a new
/// `messageId`, omitted `content` starts empty. `content` is replaced as a
/// whole array; send `[]` or `null` to clear it.
///
/// Message updates and chunks are applied in the order they are received. When
/// an `agent_message` update includes `content`, that array replaces any
/// content previously accumulated for the message, including content from
/// earlier chunks. Later chunks with the same `messageId` append to the current
/// content.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct AgentMessage {
    /// A unique identifier for the message.
    pub message_id: MessageId,
    /// Complete replacement content for this message.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<VecSkipError<_>>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub content: MaybeUndefined<Vec<ContentBlock>>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

impl AgentMessage {
    /// Builds [`AgentMessage`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(message_id: impl Into<MessageId>) -> Self {
        Self {
            message_id: message_id.into(),
            content: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Complete replacement content for this message.
    #[must_use]
    pub fn content(mut self, content: impl IntoMaybeUndefined<Vec<ContentBlock>>) -> Self {
        self.content = content.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged message metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

/// An agent thought or reasoning message upsert.
///
/// Only `messageId` is required. `content` has patch semantics:
/// an omitted field leaves existing thought content unchanged, `null` clears the
/// value, and a concrete array replaces the previous value. For a new
/// `messageId`, omitted `content` starts empty. `content` is replaced as a
/// whole array; send `[]` or `null` to clear it.
///
/// Message updates and chunks are applied in the order they are received. When
/// an `agent_thought` update includes `content`, that array replaces any
/// content previously accumulated for the thought, including content from
/// earlier chunks. Later chunks with the same `messageId` append to the current
/// content.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct AgentThought {
    /// A unique identifier for the thought message.
    pub message_id: MessageId,
    /// Complete replacement content for this thought message.
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<VecSkipError<_>>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
    #[serde(default, skip_serializing_if = "MaybeUndefined::is_undefined")]
    pub content: MaybeUndefined<Vec<ContentBlock>>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted leaves the stored metadata unchanged; `null`
    /// clears it. An object patches the stored metadata by top-level key: keys it omits are
    /// unchanged, a key set to `null` is removed, and any other value replaces that key's
    /// stored value without merging nested objects. Beyond this patch rule, implementations
    /// MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Metadata Patches](https://agentclientprotocol.com/protocol/v2/extensibility#metadata-patches)
    #[serde_as(deserialize_as = "DefaultOnError<MaybeUndefined<_>>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(
        rename = "_meta",
        default,
        skip_serializing_if = "MaybeUndefined::is_undefined"
    )]
    pub meta: MaybeUndefined<Meta>,
}

impl AgentThought {
    /// Builds [`AgentThought`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(message_id: impl Into<MessageId>) -> Self {
        Self {
            message_id: message_id.into(),
            content: MaybeUndefined::Undefined,
            meta: MaybeUndefined::Undefined,
        }
    }

    /// Complete replacement content for this thought message.
    #[must_use]
    pub fn content(mut self, content: impl IntoMaybeUndefined<Vec<ContentBlock>>) -> Self {
        self.content = content.into_maybe_undefined();
        self
    }

    /// Patches, clears, or leaves unchanged thought metadata.
    ///
    /// A concrete object patches stored metadata by top-level key; see
    /// [`apply_meta_update`](super::apply_meta_update).
    #[must_use]
    pub fn meta(mut self, meta: impl IntoMaybeUndefined<Meta>) -> Self {
        self.meta = meta.into_maybe_undefined();
        self
    }
}

/// Identifier for a message, unique among messages of the same type within a session.
///
/// Each message type, such as user messages, agent messages, and agent thoughts,
/// has its own ID space: messages of different types may share an ID and remain
/// distinct messages.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
#[serde(transparent)]
#[from(forward)]
#[non_exhaustive]
pub struct MessageId(pub Arc<str>);

impl MessageId {
    /// Wraps a protocol string as a typed [`MessageId`].
    #[must_use]
    pub fn new(id: impl Into<Self>) -> Self {
        id.into()
    }
}

/// Available commands are ready or have changed
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct AvailableCommandsUpdate {
    /// Commands the agent can execute.
    #[serde_as(deserialize_as = "VecSkipError<_>")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-skip-invalid-items" = true)))]
    pub available_commands: Vec<AvailableCommand>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl AvailableCommandsUpdate {
    /// Builds [`AvailableCommandsUpdate`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(available_commands: Vec<AvailableCommand>) -> Self {
        Self {
            available_commands,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// A command the agent advertises to the client.
///
/// The `type` field acts as the discriminator in the serialized JSON form.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum AvailableCommand {
    /// A slash command the user can invoke by including it in a prompt.
    Command(Command),
    /// Custom or future command kind.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    ///
    /// Clients that do not understand this command type should preserve the raw
    /// payload when storing, replaying, proxying, or forwarding command
    /// metadata, and otherwise ignore the command or display it as a plain
    /// command using its `name` and `description`.
    #[serde(untagged)]
    Other(OtherAvailableCommand),
}

impl AvailableCommand {
    /// Command name (e.g., `create_plan`, `research_codebase`).
    #[must_use]
    pub fn name(&self) -> &str {
        match self {
            Self::Command(c) => &c.name,
            Self::Other(c) => &c.name,
        }
    }

    /// Human-readable description of what the command does.
    #[must_use]
    pub fn description(&self) -> &str {
        match self {
            Self::Command(c) => &c.description,
            Self::Other(c) => &c.description,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(&self) -> Option<&Meta> {
        match self {
            Self::Command(c) => c.meta.as_ref(),
            Self::Other(c) => c.fields.get("_meta").and_then(serde_json::Value::as_object),
        }
    }
}

/// Custom or future command payload.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[cfg_attr(feature = "schemars", schemars(transform = other_available_command_schema))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct OtherAvailableCommand {
    /// Custom or future command type.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    #[serde(rename = "type")]
    pub type_: String,
    /// Command name without the leading `/`. MUST NOT contain whitespace and MUST be unique
    /// within the command list.
    pub name: String,
    /// Human-readable description of what the command does.
    pub description: String,
    /// The remaining fields of the unknown command payload, preserved verbatim, including
    /// `_meta`.
    #[serde(flatten)]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl OtherAvailableCommand {
    /// Builds [`OtherAvailableCommand`] from an unknown discriminator and preserves the remaining extension fields.
    #[must_use]
    pub fn new(
        type_: impl Into<String>,
        name: impl Into<String>,
        description: impl Into<String>,
        mut fields: BTreeMap<String, serde_json::Value>,
    ) -> Self {
        fields.remove("type");
        fields.remove("name");
        fields.remove("description");
        Self {
            type_: type_.into(),
            name: name.into(),
            description: description.into(),
            fields,
        }
    }
}

impl<'de> Deserialize<'de> for OtherAvailableCommand {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(Deserialize)]
        struct RawOtherAvailableCommand {
            #[serde(rename = "type")]
            type_: String,
            name: String,
            description: String,
            #[serde(flatten)]
            fields: BTreeMap<String, serde_json::Value>,
        }

        let raw = RawOtherAvailableCommand::deserialize(deserializer)?;
        if is_known_available_command_type(&raw.type_) {
            return Err(serde::de::Error::custom(format!(
                "known available command type `{}` did not match its schema",
                raw.type_
            )));
        }

        Ok(Self {
            type_: raw.type_,
            name: raw.name,
            description: raw.description,
            fields: raw.fields,
        })
    }
}

const KNOWN_AVAILABLE_COMMAND_TYPES: &[&str] = &["command"];

fn is_known_available_command_type(type_: &str) -> bool {
    KNOWN_AVAILABLE_COMMAND_TYPES.contains(&type_)
}

#[cfg(feature = "schemars")]
fn other_available_command_schema(schema: &mut Schema) {
    super::schema_util::reject_known_string_discriminators(
        schema,
        "type",
        KNOWN_AVAILABLE_COMMAND_TYPES,
    );
}

/// A slash command the user can invoke by including it in a prompt.
///
/// The `type` discriminator value is `command`.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Command {
    /// Command name without the leading `/` (e.g., `create_plan`, `research_codebase`).
    ///
    /// MUST NOT contain whitespace and MUST be unique within the command list.
    pub name: String,
    /// Human-readable description of what the command does.
    pub description: String,
    /// Input for the command if required
    ///
    /// Omitted and `null` are equivalent and mean the command takes no input.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub input: Option<AvailableCommandInput>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl Command {
    /// Builds [`Command`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(name: impl Into<String>, description: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            description: description.into(),
            input: None,
            meta: None,
        }
    }

    /// Input for the command if required
    #[must_use]
    pub fn input(mut self, input: impl IntoOption<AvailableCommandInput>) -> Self {
        self.input = input.into_option();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// The input specification for a command.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum AvailableCommandInput {
    /// All text after the command name and the whitespace following it is provided as input.
    #[serde(rename = "text")]
    Text(TextCommandInput),
    /// Custom or future command input specification.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    ///
    /// Clients that do not understand this input type should preserve the raw
    /// payload when storing, replaying, proxying, or forwarding command
    /// metadata, and otherwise ignore the input specification or display the
    /// command without structured input.
    #[serde(untagged)]
    Other(OtherAvailableCommandInput),
}

/// Custom or future command input specification.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[cfg_attr(feature = "schemars", schemars(transform = other_available_command_input_schema))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct OtherAvailableCommandInput {
    /// Custom or future command input type.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    #[serde(rename = "type")]
    pub type_: String,
    /// Additional fields from the unknown command input payload.
    #[serde(flatten)]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl OtherAvailableCommandInput {
    /// Builds [`OtherAvailableCommandInput`] from an unknown discriminator and preserves the remaining extension fields.
    #[must_use]
    pub fn new(type_: impl Into<String>, mut fields: BTreeMap<String, serde_json::Value>) -> Self {
        fields.remove("type");
        Self {
            type_: type_.into(),
            fields,
        }
    }
}

impl<'de> Deserialize<'de> for OtherAvailableCommandInput {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut fields = BTreeMap::<String, serde_json::Value>::deserialize(deserializer)?;
        let type_ = fields
            .remove("type")
            .ok_or_else(|| serde::de::Error::missing_field("type"))?;
        let serde_json::Value::String(type_) = type_ else {
            return Err(serde::de::Error::custom("`type` must be a string"));
        };

        if is_known_available_command_input_type(&type_) {
            return Err(serde::de::Error::custom(format!(
                "known available command input type `{type_}` did not match its schema"
            )));
        }

        Ok(Self { type_, fields })
    }
}

const KNOWN_AVAILABLE_COMMAND_INPUT_TYPES: &[&str] = &["text"];

fn is_known_available_command_input_type(type_: &str) -> bool {
    KNOWN_AVAILABLE_COMMAND_INPUT_TYPES.contains(&type_)
}

#[cfg(feature = "schemars")]
fn other_available_command_input_schema(schema: &mut Schema) {
    super::schema_util::reject_known_string_discriminators(
        schema,
        "type",
        KNOWN_AVAILABLE_COMMAND_INPUT_TYPES,
    );
}

/// All text that was typed after the command name is provided as input.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TextCommandInput {
    /// A hint to display when the input hasn't been provided yet
    pub hint: String,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TextCommandInput {
    /// Builds [`TextCommandInput`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(hint: impl Into<String>) -> Self {
        Self {
            hint: hint.into(),
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

// Permission

/// Request for user permission to proceed with an operation.
///
/// Sent when the agent needs authorization before performing a sensitive operation.
///
/// See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/tool-calls#requesting-permission)
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "client", "x-method" = SESSION_REQUEST_PERMISSION_METHOD_NAME)))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct RequestPermissionRequest {
    /// The session ID for this request.
    pub session_id: SessionId,
    /// Human-readable title for the permission prompt.
    ///
    /// This title is specific to the permission prompt and does not update any
    /// subject's displayed title.
    pub title: String,
    /// Optional human-readable explanation of why permission is needed.
    ///
    /// This text is specific to the permission prompt and does not update any
    /// subject's displayed content. Omitted and `null` are equivalent and mean no separate
    /// permission description was provided.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub description: Option<String>,
    /// Optional structured context about the operation requiring permission.
    ///
    /// Omitted and `null` are equivalent and mean no structured subject was provided.
    #[serde(default)]
    pub subject: Option<RequestPermissionSubject>,
    /// Available permission options for the user to choose from.
    /// Must contain at least one option.
    #[cfg_attr(feature = "schemars", schemars(length(min = 1)))]
    pub options: Vec<PermissionOption>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl RequestPermissionRequest {
    /// Builds [`RequestPermissionRequest`] with the required request fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(
        session_id: impl Into<SessionId>,
        title: impl Into<String>,
        options: Vec<PermissionOption>,
    ) -> Self {
        Self {
            session_id: session_id.into(),
            title: title.into(),
            description: None,
            subject: None,
            options,
            meta: None,
        }
    }

    /// Sets or clears the optional `description` field.
    #[must_use]
    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
        self.description = description.into_option();
        self
    }

    /// Sets or clears the optional `subject` field.
    #[must_use]
    pub fn subject(mut self, subject: impl IntoOption<RequestPermissionSubject>) -> Self {
        self.subject = subject.into_option();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// The operation requiring permission.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum RequestPermissionSubject {
    /// Permission is requested before executing a tool call.
    ToolCall(Box<ToolCallPermissionSubject>),
    /// Permission is requested before running a command.
    Command(CommandPermissionSubject),
    /// Custom or future permission subject.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    ///
    /// Clients that do not understand this subject type should preserve the raw
    /// payload when storing, replaying, proxying, or forwarding permission
    /// requests, and otherwise display a generic permission prompt or decline it
    /// according to policy.
    #[serde(untagged)]
    Other(OtherRequestPermissionSubject),
}

impl From<ToolCallPermissionSubject> for RequestPermissionSubject {
    fn from(subject: ToolCallPermissionSubject) -> Self {
        Self::ToolCall(Box::new(subject))
    }
}

impl From<ToolCallUpdate> for RequestPermissionSubject {
    fn from(tool_call: ToolCallUpdate) -> Self {
        ToolCallPermissionSubject::new(tool_call).into()
    }
}

impl From<CommandPermissionSubject> for RequestPermissionSubject {
    fn from(subject: CommandPermissionSubject) -> Self {
        Self::Command(subject)
    }
}

/// Permission request details for a tool call.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ToolCallPermissionSubject {
    /// Details about the tool call requiring permission.
    ///
    /// Clients apply this to their stored tool call exactly like a `tool_call_update`
    /// notification, in the order it was received, before showing the prompt. A first-seen
    /// `toolCallId` creates the tool call.
    pub tool_call: ToolCallUpdate,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl ToolCallPermissionSubject {
    /// Builds [`ToolCallPermissionSubject`] with the required fields set.
    #[must_use]
    pub fn new(tool_call: ToolCallUpdate) -> Self {
        Self {
            tool_call,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Permission request details for a command.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CommandPermissionSubject {
    /// The command that would be run if permission is granted.
    pub command: String,
    /// The absolute working directory for the command.
    pub cwd: AbsolutePath,
    /// The associated tool call, when known. Omitted and `null` are equivalent.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub tool_call_id: Option<ToolCallId>,
    /// The associated terminal, when already known. Omitted and `null` are equivalent.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub terminal_id: Option<TerminalId>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl CommandPermissionSubject {
    /// Builds command permission details with the required command and working directory.
    #[must_use]
    pub fn new(command: impl Into<String>, cwd: impl Into<AbsolutePath>) -> Self {
        Self {
            command: command.into(),
            cwd: cwd.into(),
            tool_call_id: None,
            terminal_id: None,
            meta: None,
        }
    }

    /// Sets or clears the associated tool-call ID.
    #[must_use]
    pub fn tool_call_id(mut self, tool_call_id: impl IntoOption<ToolCallId>) -> Self {
        self.tool_call_id = tool_call_id.into_option();
        self
    }

    /// Sets or clears the associated terminal ID.
    #[must_use]
    pub fn terminal_id(mut self, terminal_id: impl IntoOption<TerminalId>) -> Self {
        self.terminal_id = terminal_id.into_option();
        self
    }

    /// Sets or clears subject-scoped metadata.
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Custom or future permission subject payload.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[cfg_attr(feature = "schemars", schemars(transform = other_request_permission_subject_schema))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct OtherRequestPermissionSubject {
    /// Custom or future permission subject type.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    #[serde(rename = "type")]
    pub type_: String,
    /// Additional fields from the unknown permission subject payload.
    #[serde(flatten)]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl OtherRequestPermissionSubject {
    /// Builds [`OtherRequestPermissionSubject`] from an unknown discriminator and preserves the remaining extension fields.
    #[must_use]
    pub fn new(type_: impl Into<String>, mut fields: BTreeMap<String, serde_json::Value>) -> Self {
        fields.remove("type");
        Self {
            type_: type_.into(),
            fields,
        }
    }
}

impl<'de> Deserialize<'de> for OtherRequestPermissionSubject {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut fields = BTreeMap::<String, serde_json::Value>::deserialize(deserializer)?;
        let type_ = fields
            .remove("type")
            .ok_or_else(|| serde::de::Error::missing_field("type"))?;
        let serde_json::Value::String(type_) = type_ else {
            return Err(serde::de::Error::custom("`type` must be a string"));
        };

        if is_known_request_permission_subject_type(&type_) {
            return Err(serde::de::Error::custom(format!(
                "known request permission subject `{type_}` did not match its schema"
            )));
        }

        Ok(Self { type_, fields })
    }
}

fn is_known_request_permission_subject_type(type_: &str) -> bool {
    matches!(type_, "tool_call" | "command")
}

#[cfg(feature = "schemars")]
fn other_request_permission_subject_schema(schema: &mut Schema) {
    super::schema_util::reject_known_string_discriminators(
        schema,
        "type",
        &["tool_call", "command"],
    );
}

/// An option presented to the user when requesting permission.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct PermissionOption {
    /// Identifier for this permission option. MUST be unique within the request.
    pub option_id: PermissionOptionId,
    /// Human-readable label to display to the user.
    pub name: String,
    /// Hint about the nature of this permission option.
    pub kind: PermissionOptionKind,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl PermissionOption {
    /// Builds [`PermissionOption`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(
        option_id: impl Into<PermissionOptionId>,
        name: impl Into<String>,
        kind: PermissionOptionKind,
    ) -> Self {
        Self {
            option_id: option_id.into(),
            name: name.into(),
            kind,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Unique identifier for a permission option.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
#[serde(transparent)]
#[from(forward)]
#[non_exhaustive]
pub struct PermissionOptionId(pub Arc<str>);

impl PermissionOptionId {
    /// Wraps a protocol string as a typed [`PermissionOptionId`].
    #[must_use]
    pub fn new(id: impl Into<Self>) -> Self {
        id.into()
    }
}

/// The type of permission option being presented to the user.
///
/// Helps clients choose appropriate icons and UI treatment.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum PermissionOptionKind {
    /// Allow this operation only this time.
    AllowOnce,
    /// Allow this operation and remember the choice.
    AllowAlways,
    /// Reject this operation only this time.
    RejectOnce,
    /// Reject this operation and remember the choice.
    RejectAlways,
    /// Custom or future permission option kind.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    #[serde(untagged)]
    Other(String),
}

/// Response to a permission request.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "client", "x-method" = SESSION_REQUEST_PERMISSION_METHOD_NAME)))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct RequestPermissionResponse {
    /// The user's decision on the permission request.
    pub outcome: RequestPermissionOutcome,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl RequestPermissionResponse {
    /// Builds [`RequestPermissionResponse`] with the required response fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(outcome: RequestPermissionOutcome) -> Self {
        Self {
            outcome,
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// The outcome of a permission request.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "outcome", rename_all = "snake_case")]
#[non_exhaustive]
pub enum RequestPermissionOutcome {
    /// The request was not approved and no option was selected: the session's work was
    /// cancelled, the user dismissed the prompt, or the client declined it by policy.
    /// Agents MUST NOT proceed with the operation.
    ///
    /// When a client sends a `session/cancel` notification, it MUST respond to all
    /// pending `session/request_permission` requests in that session with this
    /// `cancelled` outcome, without answering any request twice. Requests in other
    /// sessions are unaffected.
    ///
    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#cancellation)
    Cancelled(CancelledPermissionOutcome),
    /// The user selected one of the provided options.
    ///
    /// If `optionId` doesn't match an offered option, the agent MUST treat the request as not
    /// approved.
    #[serde(rename_all = "camelCase")]
    Selected(SelectedPermissionOutcome),
    /// Custom or future permission outcome.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    ///
    /// Agents that do not understand this outcome MUST NOT treat it as approval.
    /// They should preserve the raw payload when storing, replaying, proxying, or
    /// forwarding permission responses, and otherwise fail or decline the
    /// permission request according to policy.
    #[serde(untagged)]
    Other(OtherRequestPermissionOutcome),
}

/// Custom or future permission outcome payload.
///
/// This preserves the unknown `outcome` discriminator and the rest of the
/// outcome object for agents that store, replay, proxy, or forward permission
/// responses.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[cfg_attr(feature = "schemars", schemars(transform = other_request_permission_outcome_schema))]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct OtherRequestPermissionOutcome {
    /// Custom or future permission outcome.
    ///
    /// Values beginning with `_` are reserved for implementation-specific
    /// extensions. Unknown values that do not begin with `_` are reserved for
    /// future ACP variants.
    pub outcome: String,
    /// Additional fields from the unknown permission outcome payload.
    #[serde(flatten)]
    pub fields: BTreeMap<String, serde_json::Value>,
}

impl OtherRequestPermissionOutcome {
    /// Builds [`OtherRequestPermissionOutcome`] from an unknown discriminator and preserves the remaining extension fields.
    #[must_use]
    pub fn new(
        outcome: impl Into<String>,
        mut fields: BTreeMap<String, serde_json::Value>,
    ) -> Self {
        fields.remove("outcome");
        Self {
            outcome: outcome.into(),
            fields,
        }
    }
}

impl<'de> Deserialize<'de> for OtherRequestPermissionOutcome {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut fields = BTreeMap::<String, serde_json::Value>::deserialize(deserializer)?;
        let outcome = fields
            .remove("outcome")
            .ok_or_else(|| serde::de::Error::missing_field("outcome"))?;
        let serde_json::Value::String(outcome) = outcome else {
            return Err(serde::de::Error::custom("`outcome` must be a string"));
        };

        if is_known_request_permission_outcome(&outcome) {
            return Err(serde::de::Error::custom(format!(
                "known request permission outcome `{outcome}` did not match its schema"
            )));
        }

        Ok(Self { outcome, fields })
    }
}

fn is_known_request_permission_outcome(outcome: &str) -> bool {
    matches!(outcome, "cancelled" | "selected")
}

#[cfg(feature = "schemars")]
fn other_request_permission_outcome_schema(schema: &mut Schema) {
    super::schema_util::reject_known_string_discriminators(
        schema,
        "outcome",
        &["cancelled", "selected"],
    );
}

/// The request was not approved and no option was selected.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CancelledPermissionOutcome {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl CancelledPermissionOutcome {
    /// Builds an empty [`CancelledPermissionOutcome`].
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

impl From<CancelledPermissionOutcome> for RequestPermissionOutcome {
    fn from(outcome: CancelledPermissionOutcome) -> Self {
        Self::Cancelled(outcome)
    }
}

/// The user selected one of the provided options.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct SelectedPermissionOutcome {
    /// The ID of the option the user selected.
    pub option_id: PermissionOptionId,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl SelectedPermissionOutcome {
    /// Builds [`SelectedPermissionOutcome`] with the required fields set; optional fields start unset or empty.
    #[must_use]
    pub fn new(option_id: impl Into<PermissionOptionId>) -> Self {
        Self {
            option_id: option_id.into(),
            meta: None,
        }
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

// Capabilities

/// Capabilities supported by the client.
///
/// Advertised during initialization to inform the agent about
/// available features and methods.
///
/// See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#client-capabilities)
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ClientCapabilities {
    /// Authentication capabilities supported by the client.
    /// Determines which authentication method types the agent may include
    /// in its `InitializeResponse`.
    ///
    /// Optional. Omitted and `null` are equivalent and mean the client does not advertise any
    /// authentication-method extensions.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub auth: Option<ClientAuthCapabilities>,
    /// Elicitation capabilities supported by the client.
    /// Determines which elicitation modes the agent may use.
    ///
    /// Optional. Omitted and `null` are equivalent and mean the client does not advertise
    /// elicitation support.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub elicitation: Option<ElicitationCapabilities>,

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl ClientCapabilities {
    /// Builds an empty [`ClientCapabilities`]; use builder methods to advertise supported sub-capabilities.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Authentication capabilities supported by the client.
    /// Determines which authentication method types the agent may include
    /// in its `InitializeResponse`.
    #[must_use]
    pub fn auth(mut self, auth: impl IntoOption<ClientAuthCapabilities>) -> Self {
        self.auth = auth.into_option();
        self
    }

    /// Elicitation capabilities supported by the client.
    /// Determines which elicitation modes the agent may use.
    #[must_use]
    pub fn elicitation(mut self, elicitation: impl IntoOption<ElicitationCapabilities>) -> Self {
        self.elicitation = elicitation.into_option();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Authentication capabilities supported by the client.
///
/// Advertised during initialization to inform the agent which authentication
/// method types the client can handle. This governs opt-in types that require
/// additional client-side support.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ClientAuthCapabilities {
    /// Whether the client supports `terminal` authentication methods.
    ///
    /// Optional. Omitted and `null` are equivalent and mean the client does not advertise support.
    /// The client should supply `{}` only when it can reproduce the configured
    /// agent invocation in an interactive terminal. Supplying `{}` means the
    /// agent may include `terminal` entries in its authentication methods.
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    pub terminal: Option<TerminalAuthCapabilities>,
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl ClientAuthCapabilities {
    /// Builds an empty [`ClientAuthCapabilities`]; use builder methods to advertise supported sub-capabilities.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Whether the client supports `terminal` authentication methods.
    ///
    /// Omitted and `null` are equivalent and mean the client does not advertise support.
    /// The client should supply `{}` only when it can reproduce the configured
    /// agent invocation in an interactive terminal. Supplying `{}` means the
    /// agent may include `AuthMethod::Terminal` entries in its authentication
    /// methods.
    #[must_use]
    pub fn terminal(mut self, terminal: impl IntoOption<TerminalAuthCapabilities>) -> Self {
        self.terminal = terminal.into_option();
        self
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

/// Capabilities for terminal authentication methods.
///
/// Supplying `{}` means the client can reproduce the configured agent
/// invocation in an interactive terminal and supports terminal authentication
/// methods.
#[serde_as]
#[skip_serializing_none]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct TerminalAuthCapabilities {
    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
    /// Implementations MUST NOT assign meaning to keys they do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[serde_as(deserialize_as = "DefaultOnError")]
    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
    #[serde(default)]
    #[serde(rename = "_meta")]
    pub meta: Option<Meta>,
}

impl TerminalAuthCapabilities {
    /// Builds an empty [`TerminalAuthCapabilities`]; use builder methods to advertise supported sub-capabilities.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
    /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they
    /// do not recognize.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    #[must_use]
    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
        self.meta = meta.into_option();
        self
    }
}

// Method schema

/// Names of all methods that clients handle.
///
/// Provides a centralized definition of method names used in the protocol.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[non_exhaustive]
pub struct ClientMethodNames {
    /// Method for requesting permission from the user.
    pub session_request_permission: &'static str,
    /// Notification for session updates.
    pub session_update: &'static str,
    /// Method for exchanging MCP-over-ACP messages.
    #[cfg(feature = "unstable_mcp_over_acp")]
    pub mcp_message: &'static str,
    /// Method for elicitation.
    pub elicitation_create: &'static str,
    /// Notification for elicitation completion.
    pub elicitation_complete: &'static str,
}

/// Constant containing all client method names.
pub const CLIENT_METHOD_NAMES: ClientMethodNames = ClientMethodNames {
    session_update: SESSION_UPDATE_NOTIFICATION,
    session_request_permission: SESSION_REQUEST_PERMISSION_METHOD_NAME,
    #[cfg(feature = "unstable_mcp_over_acp")]
    mcp_message: MCP_MESSAGE_METHOD_NAME,
    elicitation_create: ELICITATION_CREATE_METHOD_NAME,
    elicitation_complete: ELICITATION_COMPLETE_NOTIFICATION,
};

/// Notification name for session updates.
pub(crate) const SESSION_UPDATE_NOTIFICATION: &str = "session/update";
/// Method name for requesting user permission.
pub(crate) const SESSION_REQUEST_PERMISSION_METHOD_NAME: &str = "session/request_permission";
/// Method name for elicitation.
pub(crate) const ELICITATION_CREATE_METHOD_NAME: &str = "elicitation/create";
/// Notification name for elicitation completion.
pub(crate) const ELICITATION_COMPLETE_NOTIFICATION: &str = "elicitation/complete";

/// All possible requests that an agent can send to a client.
///
/// This enum is used internally for routing RPC requests. You typically won't need
/// to use this directly.
///
/// This enum encompasses all method calls from agent to client.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(untagged)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[non_exhaustive]
pub enum AgentRequest {
    /// Requests permission from the user for an operation.
    ///
    /// Called by the agent when it needs user authorization before executing
    /// a potentially sensitive operation. The client should present the options
    /// to the user and return their decision.
    ///
    /// If the client cancels active session work via `session/cancel`, it MUST
    /// respond to this request with the `cancelled` outcome.
    ///
    /// See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/tool-calls#requesting-permission)
    RequestPermissionRequest(Box<RequestPermissionRequest>),
    /// Requests structured user input via a form or URL.
    ///
    /// See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/elicitation)
    CreateElicitationRequest(Box<CreateElicitationRequest>),
    /// **UNSTABLE**
    ///
    /// This capability is not part of the spec yet, and may be removed or changed at any point.
    ///
    /// Exchanges an MCP-over-ACP message.
    #[cfg(feature = "unstable_mcp_over_acp")]
    MessageMcpRequest(Box<MessageMcpRequest>),
    /// Handles extension method requests from the agent.
    ///
    /// Allows the Agent to send an arbitrary request that is not part of the ACP spec.
    /// Extension methods provide a way to add custom functionality while maintaining
    /// protocol compatibility.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    ExtMethodRequest(Box<ExtRequest>),
}

impl AgentRequest {
    /// Returns the corresponding method name of the request.
    #[must_use]
    pub fn method(&self) -> &str {
        match self {
            Self::RequestPermissionRequest(_) => CLIENT_METHOD_NAMES.session_request_permission,
            Self::CreateElicitationRequest(_) => CLIENT_METHOD_NAMES.elicitation_create,
            #[cfg(feature = "unstable_mcp_over_acp")]
            Self::MessageMcpRequest(_) => CLIENT_METHOD_NAMES.mcp_message,
            Self::ExtMethodRequest(ext_request) => &ext_request.method,
        }
    }
}

/// All possible responses that a client can send to an agent.
///
/// This enum is used internally for routing RPC responses. You typically won't need
/// to use this directly - the responses are handled automatically by the connection.
///
/// These are responses to the corresponding `AgentRequest` variants.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(untagged)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[non_exhaustive]
pub enum ClientResponse {
    /// Successful result returned for a `session/request_permission` request.
    RequestPermissionResponse(Box<RequestPermissionResponse>),
    /// Successful result returned for a `elicitation/create` request.
    CreateElicitationResponse(Box<CreateElicitationResponse>),
    /// Successful result returned by an MCP-over-ACP `mcp/message` request.
    #[cfg(feature = "unstable_mcp_over_acp")]
    MessageMcpResponse(Box<MessageMcpResponse>),
    /// Successful result returned by an extension method outside the core ACP method set.
    ExtMethodResponse(Box<ExtResponse>),
}

/// All possible notifications that an agent can send to a client.
///
/// This enum is used internally for routing RPC notifications. You typically won't need
/// to use this directly.
///
/// Notifications do not expect a response.
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(untagged)]
#[cfg_attr(feature = "schemars", schemars(inline))]
#[non_exhaustive]
pub enum AgentNotification {
    /// Handles session update notifications from the agent.
    ///
    /// This is a notification endpoint (no response expected) that receives
    /// updates about session activity, including message updates, message chunks,
    /// tool calls, and execution plans.
    ///
    /// Note: Clients SHOULD continue accepting tool call updates even after
    /// sending a `session/cancel` notification, as the agent may send final
    /// updates before reporting an idle `state_update` with the cancelled
    /// stop reason.
    ///
    /// See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#3-agent-reports-output)
    UpdateSessionNotification(Box<UpdateSessionNotification>),
    /// Notification that a URL-based elicitation has completed.
    ///
    /// See protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/elicitation#url-completion)
    CompleteElicitationNotification(Box<CompleteElicitationNotification>),
    /// Handles extension notifications from the agent.
    ///
    /// Allows the Agent to send an arbitrary notification that is not part of the ACP spec.
    /// Extension notifications provide a way to send one-way messages for custom functionality
    /// while maintaining protocol compatibility.
    ///
    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
    ExtNotification(Box<ExtNotification>),
}

impl AgentNotification {
    /// Returns the corresponding method name of the notification.
    #[must_use]
    pub fn method(&self) -> &str {
        match self {
            Self::UpdateSessionNotification(_) => CLIENT_METHOD_NAMES.session_update,
            Self::CompleteElicitationNotification(_) => CLIENT_METHOD_NAMES.elicitation_complete,
            Self::ExtNotification(ext_notification) => &ext_notification.method,
        }
    }
}

#[cfg(test)]
mod tests {

    #[test]
    fn replacement_lists_reject_non_arrays_instead_of_clearing() {
        use serde_json::json;
        for (update, key) in [
            ("config_option_update", "configOptions"),
            ("available_commands_update", "availableCommands"),
        ] {
            let empty = json!({ "sessionUpdate": update, key: [] });
            serde_json::from_value::<super::SessionUpdate>(empty).unwrap();
            for bad in [json!("oops"), json!(null), json!({})] {
                let wire = json!({ "sessionUpdate": update, key: bad });
                assert!(
                    serde_json::from_value::<super::SessionUpdate>(wire).is_err(),
                    "{update} {bad}"
                );
            }
        }
        let plan = |entries: serde_json::Value| {
            json!({ "sessionUpdate": "plan_update",
                "plan": { "type": "items", "planId": "p", "entries": entries } })
        };
        serde_json::from_value::<super::SessionUpdate>(plan(json!([]))).unwrap();
        assert!(serde_json::from_value::<super::SessionUpdate>(plan(json!("oops"))).is_err());
        // Invalid items are still skipped.
        let skipped =
            plan(json!([42, { "content": "a", "priority": "high", "status": "pending" }]));
        let super::SessionUpdate::PlanUpdate(update) =
            serde_json::from_value::<super::SessionUpdate>(skipped).unwrap()
        else {
            panic!("expected plan_update");
        };
        let crate::v2::PlanUpdateContent::Items(items) = update.plan else {
            panic!("expected items");
        };
        assert_eq!(items.entries.len(), 1);
    }

    #[test]
    fn other_available_command_preserves_meta_verbatim() {
        for meta in [serde_json::json!({ "k": 1 }), serde_json::json!("bad")] {
            let wire = serde_json::json!({ "type": "_custom", "name": "c",
                "description": "d", "_meta": meta, "extra": true });
            let command: super::AvailableCommand = serde_json::from_value(wire.clone()).unwrap();
            assert_eq!(command.meta(), meta.as_object());
            assert_eq!(serde_json::to_value(&command).unwrap(), wire);
        }
    }

    #[test]
    fn cancelled_permission_outcome_wire_format() {
        let outcome: RequestPermissionOutcome =
            serde_json::from_value(serde_json::json!({ "outcome": "cancelled" })).unwrap();
        assert_eq!(outcome, CancelledPermissionOutcome::new().into());
        assert_eq!(
            serde_json::to_value(&outcome).unwrap(),
            serde_json::json!({ "outcome": "cancelled" })
        );

        let with_meta: RequestPermissionOutcome = CancelledPermissionOutcome::new()
            .meta(serde_json::Map::from_iter([(
                "k".to_string(),
                serde_json::json!(1),
            )]))
            .into();
        let json = serde_json::to_value(&with_meta).unwrap();
        assert_eq!(
            json,
            serde_json::json!({ "outcome": "cancelled", "_meta": { "k": 1 } })
        );
        assert_eq!(
            serde_json::from_value::<RequestPermissionOutcome>(json).unwrap(),
            with_meta
        );
    }

    use super::*;

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_update_serializes_as_upsert() {
        use serde_json::json;

        let announced =
            SessionUpdate::SubagentUpdate(SubagentUpdate::new("sess_child_1").capabilities(
                SubagentSessionCapabilities::new().cancel(SessionCancelCapabilities::new()),
            ));
        let wire = json!({
            "sessionUpdate": "subagent_update",
            "sessionId": "sess_child_1",
            "capabilities": { "cancel": {} }
        });
        assert_eq!(serde_json::to_value(&announced).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<SessionUpdate>(wire).unwrap(),
            announced
        );

        let minimal = SubagentUpdate::new("sess_child_1");
        assert_eq!(
            serde_json::to_value(&minimal).unwrap(),
            json!({
                "sessionId": "sess_child_1"
            })
        );
        assert!(minimal.capabilities.is_undefined());
        assert!(minimal.state.is_undefined());
        assert!(minimal.meta.is_undefined());

        // Patch semantics distinguish omitted fields from explicit nulls.
        let cleared_wire = json!({
            "sessionId": "sess_child_1",
            "capabilities": null,
            "state": null,
            "_meta": null
        });
        let cleared: SubagentUpdate = serde_json::from_value(cleared_wire.clone()).unwrap();
        assert!(cleared.capabilities.is_null());
        assert!(cleared.state.is_null());
        assert!(cleared.meta.is_null());
        assert_eq!(serde_json::to_value(cleared).unwrap(), cleared_wire);

        let revoked: SubagentUpdate = serde_json::from_value(json!({
            "sessionId": "sess_child_1",
            "capabilities": {}
        }))
        .unwrap();
        assert_eq!(
            revoked.capabilities,
            MaybeUndefined::Value(SubagentSessionCapabilities::new())
        );
        assert!(
            matches!(revoked.capabilities, MaybeUndefined::Value(ref child) if child.cancel.is_none())
        );

        assert!(
            serde_json::from_value::<SessionUpdate>(json!({
                "sessionUpdate": "subagent_update"
            }))
            .is_err()
        );
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_cancel_capability_is_optional_object() {
        use serde_json::json;

        for wire in [
            json!({}),
            json!({"cancel": null}),
            json!({"cancel": true}),
            json!({"cancel": false}),
        ] {
            let child: SubagentSessionCapabilities = serde_json::from_value(wire).unwrap();
            assert!(child.cancel.is_none());
            assert_eq!(serde_json::to_value(child).unwrap(), json!({}));
        }
        let enabled = SubagentSessionCapabilities::new().cancel(SessionCancelCapabilities::new());
        assert_eq!(
            serde_json::to_value(&enabled).unwrap(),
            json!({"cancel": {}})
        );
        assert_eq!(
            serde_json::from_value::<SubagentSessionCapabilities>(json!({"cancel": {}})).unwrap(),
            enabled
        );
        let meta: Meta = [("source".into(), json!("worker"))].into_iter().collect();
        let with_meta =
            SubagentSessionCapabilities::new().cancel(SessionCancelCapabilities::new().meta(meta));
        let wire = json!({"cancel": {"_meta": {"source": "worker"}}});
        assert_eq!(serde_json::to_value(&with_meta).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<SubagentSessionCapabilities>(wire).unwrap(),
            with_meta
        );
        assert!(enabled.cancel.is_some());
        assert!(enabled.cancel(None).cancel.is_none());
        let removed = SubagentUpdate::new("child").capabilities(SubagentSessionCapabilities::new());
        assert_eq!(
            serde_json::to_value(removed).unwrap(),
            json!({"sessionId": "child", "capabilities": {}})
        );
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_display_metadata_uses_patch_semantics() {
        use serde_json::json;

        let update = SubagentUpdate::new("child")
            .title("Test investigator".to_string())
            .description("Investigates platform-specific test failures.".to_string());
        let wire = json!({
            "sessionId": "child",
            "title": "Test investigator",
            "description": "Investigates platform-specific test failures."
        });
        assert_eq!(serde_json::to_value(&update).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<SubagentUpdate>(wire).unwrap(),
            update
        );

        let minimal = SubagentUpdate::new("child");
        assert!(minimal.title.is_undefined());
        assert!(minimal.description.is_undefined());
        assert_eq!(
            serde_json::to_value(&minimal).unwrap(),
            json!({"sessionId": "child"})
        );
        let cleared_wire = json!({
            "sessionId": "child", "title": null, "description": null
        });
        let cleared: SubagentUpdate = serde_json::from_value(cleared_wire.clone()).unwrap();
        assert!(cleared.title.is_null());
        assert!(cleared.description.is_null());
        assert_eq!(serde_json::to_value(cleared).unwrap(), cleared_wire);

        let title_only: SubagentUpdate = serde_json::from_value(json!({
            "sessionId": "child", "title": "Updated title"
        }))
        .unwrap();
        assert_eq!(
            title_only.title,
            MaybeUndefined::Value("Updated title".to_string())
        );
        assert!(title_only.description.is_undefined());
        let malformed: SubagentUpdate = serde_json::from_value(json!({
            "sessionId": "child", "title": false, "description": false
        }))
        .unwrap();
        assert_eq!(malformed, minimal);
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_directories_use_strict_patch_semantics() {
        use serde_json::json;

        let update = SubagentUpdate::new("child")
            .cwd("/home/user/project/.worktrees/investigator")
            .additional_directories(vec![]);
        let wire = json!({
            "sessionId": "child",
            "cwd": "/home/user/project/.worktrees/investigator",
            "additionalDirectories": []
        });
        assert_eq!(serde_json::to_value(&update).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<SubagentUpdate>(wire).unwrap(),
            update
        );

        let inherited: SubagentUpdate =
            serde_json::from_value(json!({"sessionId": "child"})).unwrap();
        assert!(inherited.cwd.is_undefined());
        assert!(inherited.additional_directories.is_undefined());

        let cleared_wire = json!({
            "sessionId": "child", "cwd": null, "additionalDirectories": null
        });
        let cleared: SubagentUpdate = serde_json::from_value(cleared_wire.clone()).unwrap();
        assert!(cleared.cwd.is_null());
        assert!(cleared.additional_directories.is_null());
        assert_eq!(serde_json::to_value(cleared).unwrap(), cleared_wire);

        for malformed in [
            json!({"sessionId": "child", "cwd": false}),
            json!({"sessionId": "child", "additionalDirectories": "/tmp/wt"}),
            json!({"sessionId": "child", "additionalDirectories": ["/tmp/wt", false]}),
        ] {
            assert!(
                serde_json::from_value::<SubagentUpdate>(malformed.clone()).is_err(),
                "{malformed}"
            );
        }
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_notification_keeps_parent_and_child_ids_nested() {
        use serde_json::json;

        let notification = UpdateSessionNotification::new(
            "parent",
            SessionUpdate::SubagentUpdate(SubagentUpdate::new("child")),
        );
        let wire = json!({
            "sessionId": "parent",
            "update": {
                "sessionUpdate": "subagent_update",
                "sessionId": "child"
            }
        });
        assert_eq!(serde_json::to_value(&notification).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<UpdateSessionNotification>(wire).unwrap(),
            notification
        );
        for malformed in [
            json!({"sessionId": "parent", "update": {"sessionUpdate": "subagent_update"}}),
            json!({"update": {"sessionUpdate": "subagent_update", "sessionId": "child"}}),
        ] {
            assert!(serde_json::from_value::<UpdateSessionNotification>(malformed).is_err());
        }
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_mirrors_normal_child_state_notifications() {
        use serde_json::json;

        let association = SubagentUpdate::new("sess_child");
        for state in [
            StateUpdate::Running(RunningStateUpdate::new()),
            StateUpdate::RequiresAction(RequiresActionStateUpdate::new()),
            StateUpdate::Unknown(UnknownStateUpdate::new()),
            StateUpdate::Running(RunningStateUpdate::new()),
            StateUpdate::Idle(IdleStateUpdate::new().stop_reason(StopReason::EndTurn)),
            StateUpdate::Running(RunningStateUpdate::new()),
            StateUpdate::Idle(IdleStateUpdate::new().stop_reason(StopReason::Cancelled)),
        ] {
            let child_notification = UpdateSessionNotification::new(
                association.session_id.clone(),
                SessionUpdate::StateUpdate(state.clone()),
            );
            let parent_notification = UpdateSessionNotification::new(
                "sess_parent",
                SessionUpdate::SubagentUpdate(association.clone().state(state)),
            );
            let child_wire = serde_json::to_value(&child_notification).unwrap();
            let parent_wire = serde_json::to_value(&parent_notification).unwrap();
            assert_eq!(child_wire["sessionId"], json!("sess_child"));
            assert_eq!(child_wire["update"]["sessionUpdate"], json!("state_update"));
            assert_eq!(parent_wire["sessionId"], json!("sess_parent"));
            assert_eq!(parent_wire["update"]["sessionId"], json!("sess_child"));
            let mut child_snapshot = child_wire["update"].clone();
            child_snapshot
                .as_object_mut()
                .unwrap()
                .remove("sessionUpdate");
            assert_eq!(parent_wire["update"]["state"], child_snapshot);
            assert_eq!(
                serde_json::from_value::<UpdateSessionNotification>(child_wire).unwrap(),
                child_notification
            );
            assert_eq!(
                serde_json::from_value::<UpdateSessionNotification>(parent_wire).unwrap(),
                parent_notification
            );
        }
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn subagent_state_uses_whole_snapshot_patch_semantics() {
        use serde_json::json;

        let minimal = SubagentUpdate::new("child");
        assert!(minimal.state.is_undefined());
        assert_eq!(
            serde_json::to_value(&minimal).unwrap(),
            json!({"sessionId": "child"})
        );

        let cleared = minimal.clone().state(None::<StateUpdate>);
        assert!(cleared.state.is_null());
        assert_eq!(
            serde_json::to_value(&cleared).unwrap(),
            json!({"sessionId": "child", "state": null})
        );
        assert_eq!(
            serde_json::from_value::<SubagentUpdate>(json!({"sessionId": "child", "state": null}))
                .unwrap(),
            cleared
        );

        for snapshot in [
            json!({"state": "running", "_meta": {"source": "worker"}}),
            json!({"state": "idle", "stopReason": "end_turn"}),
            json!({"state": "requires_action"}),
            json!({"state": "unknown"}),
            json!({"state": "_custom", "detail": {"phase": 2}}),
        ] {
            let state: StateUpdate = serde_json::from_value(snapshot.clone()).unwrap();
            let update = minimal.clone().state(state.clone());
            let wire = json!({"sessionId": "child", "state": snapshot});
            assert_eq!(serde_json::to_value(&update).unwrap(), wire);
            assert_eq!(
                serde_json::from_value::<SubagentUpdate>(wire).unwrap(),
                update
            );
            assert_eq!(update.state, MaybeUndefined::Value(state));
        }

        // Each concrete value is the entire replacement snapshot, not a merge
        // with a previous state's stop reason or metadata.
        let idle = SubagentUpdate::new("child").state(StateUpdate::Idle(
            IdleStateUpdate::new().stop_reason(StopReason::Cancelled),
        ));
        let running = idle.state(StateUpdate::Running(RunningStateUpdate::new()));
        assert_eq!(
            serde_json::to_value(running).unwrap(),
            json!({"sessionId": "child", "state": {"state": "running"}})
        );
        for invalid in [json!(false), json!(42), json!({}), json!({"state": 7})] {
            let parsed: SubagentUpdate =
                serde_json::from_value(json!({"sessionId": "child", "state": invalid})).unwrap();
            assert_eq!(parsed, minimal);
        }
    }

    #[cfg(feature = "unstable_subagents")]
    #[test]
    fn unknown_activity_is_a_known_state_update() {
        use serde_json::json;

        let update = SessionUpdate::StateUpdate(StateUpdate::Unknown(
            UnknownStateUpdate::new().meta(
                [("source".into(), json!("worker"))]
                    .into_iter()
                    .collect::<Meta>(),
            ),
        ));
        let wire = json!({
            "sessionUpdate": "state_update",
            "state": "unknown",
            "_meta": { "source": "worker" }
        });
        assert_eq!(serde_json::to_value(&update).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<SessionUpdate>(wire).unwrap(),
            update
        );

        for meta in [json!(null), json!(false)] {
            let state: StateUpdate = serde_json::from_value(json!({
                "state": "unknown",
                "_meta": meta
            }))
            .unwrap();
            assert_eq!(state, StateUpdate::Unknown(UnknownStateUpdate::new()));
            assert_eq!(
                serde_json::to_value(state).unwrap(),
                json!({"state": "unknown"})
            );
        }
        assert!(serde_json::from_value::<OtherStateUpdate>(json!({"state": "unknown"})).is_err());
    }

    #[cfg(not(feature = "unstable_subagents"))]
    #[test]
    fn unknown_activity_is_preserved_without_subagents_feature() {
        let wire = serde_json::json!({
            "sessionUpdate": "state_update",
            "state": "unknown",
            "_meta": { "source": "worker" }
        });
        let parsed: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
        let SessionUpdate::StateUpdate(StateUpdate::Other(state)) = &parsed else {
            panic!("expected unrecognized state payload");
        };
        assert_eq!(state.state, "unknown");
        assert_eq!(serde_json::to_value(parsed).unwrap(), wire);
    }

    #[cfg(all(feature = "unstable_subagents", feature = "schemars"))]
    #[test]
    fn subagent_schema_carries_optional_nullable_state_snapshot() {
        use serde_json::json;

        let schema = serde_json::to_value(schemars::schema_for!(SubagentUpdate)).unwrap();
        let properties = schema["properties"].as_object().unwrap();
        assert!(properties.contains_key("sessionId"));
        assert!(properties.contains_key("title"));
        assert!(properties.contains_key("description"));
        assert!(properties.contains_key("capabilities"));
        assert!(properties.contains_key("state"));
        assert!(properties.contains_key("_meta"));
        assert!(!properties.contains_key("name"));
        assert!(!properties.contains_key("task"));
        assert_eq!(schema["required"], json!(["sessionId"]));
        assert_eq!(
            properties["state"]["x-deserialize-default-on-error"],
            json!(true)
        );
        let state_variants = properties["state"]["anyOf"].as_array().unwrap();
        assert!(state_variants.contains(&json!({"type": "null"})));
        assert!(
            state_variants
                .iter()
                .any(|variant| variant["$ref"] == "#/$defs/StateUpdate")
        );
        let child =
            serde_json::to_value(schemars::schema_for!(SubagentSessionCapabilities)).unwrap();
        let variants = child["properties"]["cancel"]["anyOf"]
            .as_array()
            .expect("cancel must allow the capability object or null");
        assert!(variants.contains(&json!({"type": "null"})));
        assert!(
            variants
                .iter()
                .any(|variant| variant["type"] == "object" || variant.get("$ref").is_some())
        );
        assert!(!variants.iter().any(|variant| variant["type"] == "boolean"));
        let cancel =
            serde_json::to_value(schemars::schema_for!(SessionCancelCapabilities)).unwrap();
        assert_eq!(cancel["type"], "object");
        assert!(
            !child["required"]
                .as_array()
                .is_some_and(|required| required.contains(&json!("cancel")))
        );
    }

    #[cfg(not(feature = "unstable_subagents"))]
    #[test]
    fn unsupported_subagent_update_is_preserved() {
        let wire = serde_json::json!({
            "sessionUpdate": "subagent_update",
            "sessionId": "sess_child",
            "capabilities": { "cancel": {} }
        });
        let parsed: SessionUpdate = serde_json::from_value(wire.clone()).unwrap();
        assert!(matches!(&parsed, SessionUpdate::Other(_)));
        assert_eq!(serde_json::to_value(parsed).unwrap(), wire);
    }

    #[test]
    fn notice_preserves_wire_shape_nullable_fields_and_open_severity() {
        use serde_json::json;

        let mut meta = Meta::new();
        meta.insert("source".into(), json!("fallback"));
        let v2_notice = SessionUpdate::Notice(
            Notice::new(NoticeSeverity::Error, "Provider degraded")
                .description("Requests may take longer than usual.")
                .meta(meta.clone()),
        );
        let expected = json!({
            "sessionUpdate": "notice",
            "severity": "error",
            "title": "Provider degraded",
            "description": "Requests may take longer than usual.",
            "_meta": { "source": "fallback" }
        });
        assert_eq!(serde_json::to_value(&v2_notice).unwrap(), expected);

        let v1_notice = crate::v1::SessionUpdate::Notice(
            crate::v1::Notice::new(crate::v1::NoticeSeverity::Error, "Provider degraded")
                .description("Requests may take longer than usual.")
                .meta(meta),
        );
        assert_eq!(
            serde_json::to_value(v2_notice).unwrap(),
            serde_json::to_value(v1_notice).unwrap()
        );

        let SessionUpdate::Notice(notice) = serde_json::from_value(json!({
            "sessionUpdate": "notice",
            "severity": "critical",
            "title": "Provider degraded",
            "description": null,
            "_meta": null
        }))
        .unwrap() else {
            panic!("expected notice");
        };

        assert_eq!(
            notice.severity,
            NoticeSeverity::Other("critical".to_string())
        );
        assert_eq!(notice.description, None);
        assert_eq!(notice.meta, None);
        assert_eq!(
            serde_json::to_value(SessionUpdate::Notice(notice)).unwrap(),
            json!({
                "sessionUpdate": "notice",
                "severity": "critical",
                "title": "Provider degraded"
            })
        );
    }

    #[test]
    fn malformed_known_notice_is_not_hidden_as_unknown() {
        use serde_json::json;

        for malformed in [
            json!({
                "sessionUpdate": "notice",
                "severity": "warning",
                "title": 42
            }),
            json!({
                "sessionUpdate": "notice",
                "severity": 42,
                "title": "MCP server unavailable"
            }),
            json!({
                "sessionUpdate": "notice",
                "severity": "warning"
            }),
            json!({
                "sessionUpdate": "notice",
                "severity": "warning",
                "title": null
            }),
            json!({
                "sessionUpdate": "notice",
                "title": "MCP server unavailable"
            }),
            json!({
                "sessionUpdate": "notice",
                "severity": null,
                "title": "MCP server unavailable"
            }),
        ] {
            assert!(serde_json::from_str::<SessionUpdate>(&malformed.to_string()).is_err());
            assert!(serde_json::from_value::<SessionUpdate>(malformed).is_err());
        }
    }

    #[test]
    fn notice_tolerates_invalid_optional_display_fields_and_custom_severity() {
        use serde_json::json;

        let wire = json!({
            "sessionUpdate": "notice",
            "severity": "_custom",
            "title": "Provider degraded",
            "description": 42,
            "_meta": false
        });
        let SessionUpdate::Notice(notice) = serde_json::from_value(wire.clone()).unwrap() else {
            panic!("expected notice");
        };
        assert_eq!(
            serde_json::from_str::<SessionUpdate>(&wire.to_string()).unwrap(),
            SessionUpdate::Notice(notice.clone())
        );
        assert_eq!(notice.severity, NoticeSeverity::Other("_custom".into()));
        assert_eq!(notice.description, None);
        assert_eq!(notice.meta, None);
        assert_eq!(
            serde_json::to_value(notice).unwrap(),
            json!({"severity": "_custom", "title": "Provider degraded"})
        );
    }

    #[cfg(feature = "schemars")]
    #[test]
    fn notice_schema_preserves_required_fields_and_excludes_unknown_fallback() {
        use serde_json::json;

        let schema = serde_json::to_value(schemars::schema_for!(Notice)).unwrap();
        assert_eq!(schema["required"], json!(["severity", "title"]));
        assert_eq!(schema["properties"]["title"]["minLength"], 1);
        for field in ["description", "_meta"] {
            assert!(
                schema["properties"][field]["type"]
                    .as_array()
                    .unwrap()
                    .contains(&json!("null"))
            );
        }
        let fallback = serde_json::to_value(schemars::schema_for!(OtherSessionUpdate)).unwrap();
        assert!(
            fallback["not"]["anyOf"]
                .as_array()
                .unwrap()
                .iter()
                .any(|variant| variant["properties"]["sessionUpdate"]["const"] == "notice")
        );
    }

    #[test]
    fn compaction_updates_preserve_patch_and_open_status_semantics() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::CompactionUpdate(
                CompactionUpdate::new("cmp_001", CompactionStatus::Completed).summary(vec![
                    ContentBlock::Text(crate::v2::TextContent::new("retained")),
                ]),
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "compaction_update",
                "compactionId": "cmp_001",
                "status": "completed",
                "summary": [{ "type": "text", "text": "retained" }]
            })
        );

        let SessionUpdate::CompactionUpdate(update) = serde_json::from_value(json!({
            "sessionUpdate": "compaction_update",
            "compactionId": "cmp_001",
            "status": "paused",
            "summary": null
        }))
        .unwrap() else {
            panic!("expected compaction update");
        };
        assert_eq!(update.status, CompactionStatus::Other("paused".into()));
        assert!(update.summary.is_null());
        assert!(update.error.is_undefined());
    }

    #[test]
    fn malformed_known_compaction_update_is_not_hidden_as_unknown() {
        use serde_json::json;

        assert!(
            serde_json::from_value::<SessionUpdate>(json!({
                "sessionUpdate": "compaction_update",
                "status": "completed"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<SessionUpdate>(json!({
                "sessionUpdate": "compaction_summary_chunk",
                "compactionId": "cmp_001"
            }))
            .is_err()
        );
    }

    #[test]
    fn test_elicitation_capability_semantics() {
        use serde_json::json;

        let unsupported: ClientCapabilities = serde_json::from_value(json!({})).unwrap();
        assert!(unsupported.elicitation.is_none());

        let null: ClientCapabilities =
            serde_json::from_value(json!({ "elicitation": null })).unwrap();
        assert!(null.elicitation.is_none());

        let malformed: ClientCapabilities =
            serde_json::from_value(json!({ "elicitation": false })).unwrap();
        assert!(malformed.elicitation.is_none());

        let empty: ClientCapabilities =
            serde_json::from_value(json!({ "elicitation": {} })).unwrap();
        let empty = empty.elicitation.expect("present capability");
        assert!(!empty.supports_form());
        assert!(!empty.supports_url());

        let form_only: ClientCapabilities = serde_json::from_value(json!({
            "elicitation": { "form": {} }
        }))
        .unwrap();
        let form_only = form_only.elicitation.expect("advertised capability");
        assert!(form_only.supports_form());
        assert!(!form_only.supports_url());

        let url_only: ClientCapabilities = serde_json::from_value(json!({
            "elicitation": { "url": {} }
        }))
        .unwrap();
        let url_only = url_only.elicitation.expect("advertised capability");
        assert!(!url_only.supports_form());
        assert!(url_only.supports_url());

        let both: ClientCapabilities = serde_json::from_value(json!({
            "elicitation": { "form": {}, "url": {} }
        }))
        .unwrap();
        let both = both.elicitation.expect("advertised capability");
        assert!(both.supports_form());
        assert!(both.supports_url());
    }

    #[test]
    fn test_elicitation_method_routing_and_envelopes() {
        use serde_json::json;

        assert_eq!(CLIENT_METHOD_NAMES.elicitation_create, "elicitation/create");
        assert_eq!(
            CLIENT_METHOD_NAMES.elicitation_complete,
            "elicitation/complete"
        );

        let request =
            AgentRequest::CreateElicitationRequest(Box::new(CreateElicitationRequest::new(
                crate::v2::ElicitationFormMode::new(
                    crate::v2::ElicitationSessionScope::new("sess_1"),
                    crate::v2::ElicitationSchema::new(),
                ),
                "Choose a value",
            )));
        assert_eq!(request.method(), "elicitation/create");
        let method = Arc::from(request.method());
        let request = crate::v2::JsonRpcMessage::wrap(crate::v2::Request {
            id: crate::v2::RequestId::Number(7),
            method,
            params: Some(request),
        });
        assert_eq!(
            serde_json::to_value(request).unwrap(),
            json!({
                "jsonrpc": "2.0",
                "id": 7,
                "method": "elicitation/create",
                "params": {
                    "mode": "form",
                    "sessionId": "sess_1",
                    "message": "Choose a value",
                    "requestedSchema": { "type": "object", "properties": {} }
                }
            })
        );

        let notification = AgentNotification::CompleteElicitationNotification(Box::new(
            CompleteElicitationNotification::new("elic_1"),
        ));
        assert_eq!(notification.method(), "elicitation/complete");
        let method = Arc::from(notification.method());
        let notification = crate::v2::JsonRpcMessage::wrap(crate::v2::Notification {
            method,
            params: Some(notification),
        });
        assert_eq!(
            serde_json::to_value(notification).unwrap(),
            json!({
                "jsonrpc": "2.0",
                "method": "elicitation/complete",
                "params": { "elicitationId": "elic_1" }
            })
        );
    }

    #[test]
    fn test_client_capabilities_auth_defaults_on_malformed_value() {
        use serde_json::json;

        let capabilities: ClientCapabilities = serde_json::from_value(json!({
            "auth": false
        }))
        .unwrap();

        assert_eq!(capabilities.auth, None);
    }

    #[test]
    fn test_serialization_behavior() {
        use serde_json::json;

        assert_eq!(
            serde_json::from_value::<SessionInfoUpdate>(json!({})).unwrap(),
            SessionInfoUpdate {
                title: MaybeUndefined::Undefined,
                updated_at: MaybeUndefined::Undefined,
                meta: MaybeUndefined::Undefined
            }
        );
        assert_eq!(
            serde_json::from_value::<SessionInfoUpdate>(json!({"title": null, "updatedAt": null}))
                .unwrap(),
            SessionInfoUpdate {
                title: MaybeUndefined::Null,
                updated_at: MaybeUndefined::Null,
                meta: MaybeUndefined::Undefined
            }
        );
        assert_eq!(
            serde_json::from_value::<SessionInfoUpdate>(
                json!({"title": "title", "updatedAt": "timestamp"})
            )
            .unwrap(),
            SessionInfoUpdate {
                title: MaybeUndefined::Value("title".to_string()),
                updated_at: MaybeUndefined::Value("timestamp".to_string()),
                meta: MaybeUndefined::Undefined
            }
        );

        let clear_meta =
            serde_json::from_value::<SessionInfoUpdate>(json!({"_meta": null})).unwrap();
        assert_eq!(clear_meta.meta, MaybeUndefined::Null);

        let mut meta = Meta::new();
        meta.insert("source".to_string(), json!("session-info"));

        assert_eq!(
            serde_json::from_value::<SessionInfoUpdate>(json!({"_meta": {
                "source": "session-info"
            }}))
            .unwrap()
            .meta,
            MaybeUndefined::Value(meta.clone())
        );

        assert_eq!(
            serde_json::to_value(SessionInfoUpdate::new()).unwrap(),
            json!({})
        );

        assert_eq!(
            serde_json::to_value(SessionInfoUpdate::new().meta(None::<Meta>)).unwrap(),
            json!({"_meta": null})
        );

        assert_eq!(
            serde_json::to_value(SessionInfoUpdate::new().meta(meta)).unwrap(),
            json!({"_meta": {
                "source": "session-info"
            }})
        );
        assert_eq!(
            serde_json::to_value(SessionInfoUpdate::new().title("title")).unwrap(),
            json!({"title": "title"})
        );
        assert_eq!(
            serde_json::to_value(SessionInfoUpdate::new().title(None)).unwrap(),
            json!({"title": null})
        );
        assert_eq!(
            serde_json::to_value(
                SessionInfoUpdate::new()
                    .title("title")
                    .title(MaybeUndefined::Undefined)
            )
            .unwrap(),
            json!({})
        );
    }

    #[test]
    fn test_content_chunk_message_id_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::AgentMessageChunk(ContentChunk::new(
                ContentBlock::Text(crate::v2::TextContent::new("Hello")),
                "msg_agent_c42b9",
            )))
            .unwrap(),
            json!({
                "sessionUpdate": "agent_message_chunk",
                "messageId": "msg_agent_c42b9",
                "content": {
                    "type": "text",
                    "text": "Hello"
                }
            })
        );

        let err = serde_json::from_value::<ContentChunk>(json!({
            "content": {
                "type": "text",
                "text": "Hello"
            }
        }))
        .unwrap_err();

        assert!(err.to_string().contains("messageId"), "{err}");
    }

    #[test]
    fn test_tool_call_content_chunk_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::ToolCallContentChunk(
                ToolCallContentChunk::new(
                    "call_001",
                    crate::v2::ContentBlock::Text(crate::v2::TextContent::new("partial output")),
                )
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "tool_call_content_chunk",
                "toolCallId": "call_001",
                "content": {
                    "type": "content",
                    "content": {
                        "type": "text",
                        "text": "partial output"
                    }
                }
            })
        );

        let err = serde_json::from_value::<ToolCallContentChunk>(json!({
            "content": {
                "type": "content",
                "content": {
                    "type": "text",
                    "text": "partial output"
                }
            }
        }))
        .unwrap_err();

        assert!(err.to_string().contains("toolCallId"), "{err}");
    }

    #[test]
    fn test_full_message_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::UserMessage(
                UserMessage::new("msg_user_8f7a1").content(vec![ContentBlock::Text(
                    crate::v2::TextContent::new("Hello")
                )])
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "user_message",
                "messageId": "msg_user_8f7a1",
                "content": [
                    {
                        "type": "text",
                        "text": "Hello"
                    }
                ]
            })
        );

        assert_eq!(
            serde_json::to_value(SessionUpdate::AgentMessage(
                AgentMessage::new("msg_agent_c42b9").content(vec![ContentBlock::Text(
                    crate::v2::TextContent::new("Hello")
                )])
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "agent_message",
                "messageId": "msg_agent_c42b9",
                "content": [
                    {
                        "type": "text",
                        "text": "Hello"
                    }
                ]
            })
        );

        assert_eq!(
            serde_json::to_value(SessionUpdate::AgentThought(
                AgentThought::new("msg_thought_a12").content(vec![ContentBlock::Text(
                    crate::v2::TextContent::new("Need to inspect the call sites first.")
                )])
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "agent_thought",
                "messageId": "msg_thought_a12",
                "content": [
                    {
                        "type": "text",
                        "text": "Need to inspect the call sites first."
                    }
                ]
            })
        );
    }

    #[test]
    fn test_message_upsert_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::UserMessage(
                UserMessage::new("msg_empty").content(Vec::<ContentBlock>::new())
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "user_message",
                "messageId": "msg_empty",
                "content": []
            })
        );

        let empty = serde_json::from_value::<UserMessage>(json!({
            "messageId": "msg_empty",
            "content": []
        }))
        .unwrap();
        assert!(matches!(
            empty.content,
            MaybeUndefined::Value(ref content) if content.is_empty()
        ));

        let patch = serde_json::from_value::<AgentMessage>(json!({
            "messageId": "msg_agent_c42b9"
        }))
        .unwrap();
        assert_eq!(patch.content, MaybeUndefined::Undefined);
        assert_eq!(patch.meta, MaybeUndefined::Undefined);

        let malformed_meta = serde_json::from_value::<AgentMessage>(json!({
            "messageId": "msg_agent_c42b9",
            "_meta": false
        }))
        .unwrap();
        assert_eq!(malformed_meta.meta, MaybeUndefined::Undefined);

        let patch = serde_json::from_value::<AgentThought>(json!({
            "messageId": "msg_thought_a12"
        }))
        .unwrap();
        assert_eq!(patch.content, MaybeUndefined::Undefined);

        let clear = serde_json::from_value::<UserMessage>(json!({
            "messageId": "msg_user_8f7a1",
            "content": null
        }))
        .unwrap();
        assert_eq!(clear.content, MaybeUndefined::Null);

        let clear_meta = serde_json::from_value::<UserMessage>(json!({
            "messageId": "msg_user_8f7a1",
            "_meta": null
        }))
        .unwrap();
        assert_eq!(clear_meta.meta, MaybeUndefined::Null);

        let mut meta = Meta::new();
        meta.insert("source".to_string(), json!("replay"));

        assert_eq!(
            serde_json::to_value(SessionUpdate::UserMessage(
                UserMessage::new("msg_user_8f7a1").meta(meta)
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "user_message",
                "messageId": "msg_user_8f7a1",
                "_meta": {
                    "source": "replay"
                }
            })
        );

        assert_eq!(
            serde_json::to_value(SessionUpdate::UserMessage(
                UserMessage::new("msg_user_8f7a1").meta(None::<Meta>)
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "user_message",
                "messageId": "msg_user_8f7a1",
                "_meta": null
            })
        );
    }

    #[test]
    fn test_usage_update_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::UsageUpdate(UsageUpdate::new(
                53_000, 200_000
            )))
            .unwrap(),
            json!({
                "sessionUpdate": "usage_update",
                "used": 53000,
                "size": 200_000
            })
        );

        assert_eq!(
            serde_json::to_value(SessionUpdate::UsageUpdate(
                UsageUpdate::new(53_000, 200_000).cost(Cost::new(0.045, "USD"))
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "usage_update",
                "used": 53000,
                "size": 200_000,
                "cost": {
                    "amount": 0.045,
                    "currency": "USD"
                }
            })
        );

        let SessionUpdate::UsageUpdate(update) = serde_json::from_value(json!({
            "sessionUpdate": "usage_update",
            "used": 53000,
            "size": 200_000,
            "cost": null
        }))
        .unwrap() else {
            panic!("expected usage update");
        };

        assert_eq!(update.cost, MaybeUndefined::Null);

        let SessionUpdate::UsageUpdate(update) = serde_json::from_value(json!({
            "sessionUpdate": "usage_update",
            "used": 53000,
            "size": 200_000
        }))
        .unwrap() else {
            panic!("expected usage update");
        };

        assert_eq!(update.cost, MaybeUndefined::Undefined);
    }

    #[test]
    fn error_stop_reason_carries_failure_beside_discriminator() {
        use crate::v2::{Error, ErrorStopReason};
        use serde_json::json;

        let update =
            SessionUpdate::StateUpdate(StateUpdate::Idle(IdleStateUpdate::new().stop_reason(
                StopReason::from(ErrorStopReason::new().error(Error::auth_required())),
            )));
        let wire = json!({
            "sessionUpdate": "state_update",
            "state": "idle",
            "stopReason": "error",
            "error": { "code": -32000, "message": "Authentication required" }
        });
        assert_eq!(serde_json::to_value(&update).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<SessionUpdate>(wire).unwrap(),
            update
        );

        let with_data =
            StateUpdate::Idle(IdleStateUpdate::new().stop_reason(StopReason::from(
                ErrorStopReason::new().error(
                    Error::new(-32099, "Provider unavailable").data(json!({ "status": 503 })),
                ),
            )));
        let wire = json!({
            "state": "idle",
            "stopReason": "error",
            "error": {
                "code": -32099,
                "message": "Provider unavailable",
                "data": { "status": 503 }
            }
        });
        assert_eq!(serde_json::to_value(&with_data).unwrap(), wire);
        assert_eq!(
            serde_json::from_value::<StateUpdate>(wire).unwrap(),
            with_data
        );

        // Missing, null, and malformed details leave a failure without details;
        // the stop reason still ends foreground work.
        let without_details = StateUpdate::Idle(
            IdleStateUpdate::new().stop_reason(StopReason::from(ErrorStopReason::new())),
        );
        for error in [
            None,
            Some(json!(null)),
            Some(json!("failed")),
            Some(json!({ "message": "missing code" })),
        ] {
            let mut wire = json!({ "state": "idle", "stopReason": "error" });
            if let Some(error) = error {
                wire["error"] = error;
            }
            assert_eq!(
                serde_json::from_value::<StateUpdate>(wire).unwrap(),
                without_details
            );
        }
        assert_eq!(
            serde_json::to_value(&without_details).unwrap(),
            json!({ "state": "idle", "stopReason": "error" })
        );

        // `error` is a field of the `error` stop reason only. Beside any other
        // stop reason it is an unknown field: the update stays readable and the
        // error has nowhere to go.
        let parsed: StateUpdate = serde_json::from_value(json!({
            "state": "idle",
            "stopReason": "end_turn",
            "error": { "code": -32603, "message": "Internal error" }
        }))
        .unwrap();
        assert_eq!(
            parsed,
            StateUpdate::Idle(IdleStateUpdate::new().stop_reason(StopReason::EndTurn))
        );
    }

    #[test]
    fn flattened_stop_reason_keeps_open_enum_tolerance() {
        use crate::v2::OtherStopReason;
        use serde_json::json;

        let meta: Meta = [("source".into(), json!("test"))].into_iter().collect();

        // Omitted, null, and malformed stop reasons all mean no stop reason, as
        // when `stopReason` was a separate default-on-error field.
        for stop_reason in [None, Some(json!(null)), Some(json!(true)), Some(json!({}))] {
            let mut wire = json!({ "state": "idle", "_meta": { "source": "test" } });
            if let Some(stop_reason) = stop_reason {
                wire["stopReason"] = stop_reason;
            }
            let StateUpdate::Idle(idle) = serde_json::from_value(wire).unwrap() else {
                panic!("expected idle state update");
            };
            assert_eq!(idle.stop_reason, None);
            assert_eq!(idle.meta, Some(meta.clone()));
        }

        // Unknown stop reasons keep their own fields for proxies and replay,
        // while the idle update's fields stay on the idle update.
        let wire = json!({
            "state": "idle",
            "stopReason": "_paused",
            "resumeAfter": 30,
            "_meta": { "source": "test" }
        });
        let parsed: StateUpdate = serde_json::from_value(wire.clone()).unwrap();
        let expected = StateUpdate::Idle(
            IdleStateUpdate::new()
                .stop_reason(StopReason::Other(OtherStopReason::new(
                    "_paused",
                    [("resumeAfter".into(), json!(30))].into_iter().collect(),
                )))
                .meta(meta),
        );
        assert_eq!(parsed, expected);
        assert_eq!(serde_json::to_value(&parsed).unwrap(), wire);
    }

    #[test]
    fn known_stop_reasons_are_never_read_as_other() {
        use crate::v2::{ErrorStopReason, OtherStopReason};
        use serde_json::json;

        let known = [
            StopReason::EndTurn,
            StopReason::MaxTokens,
            StopReason::MaxTurnRequests,
            StopReason::Refusal,
            StopReason::Cancelled,
            StopReason::Error(ErrorStopReason::new()),
        ];
        // Adding a variant breaks this match, so `known` stays complete.
        for stop_reason in &known {
            match stop_reason {
                StopReason::EndTurn
                | StopReason::MaxTokens
                | StopReason::MaxTurnRequests
                | StopReason::Refusal
                | StopReason::Cancelled
                | StopReason::Error(_)
                | StopReason::Other(_) => {}
            }
        }

        for stop_reason in known {
            let update = StateUpdate::Idle(IdleStateUpdate::new().stop_reason(stop_reason));
            let wire = serde_json::to_value(&update).unwrap();
            assert_eq!(
                serde_json::from_value::<StateUpdate>(wire.clone()).unwrap(),
                update
            );
            assert!(
                serde_json::from_value::<OtherStopReason>(
                    json!({ "stopReason": wire["stopReason"] })
                )
                .is_err(),
                "{} must not be accepted as a custom stop reason",
                wire["stopReason"]
            );
        }
    }

    #[test]
    fn unknown_stop_reason_leaves_usage_on_the_idle_update() {
        use serde_json::json;

        let usage = json!({ "totalTokens": 10, "inputTokens": 6, "outputTokens": 4 });
        let wire = json!({ "state": "idle", "stopReason": "_paused", "usage": usage });
        let StateUpdate::Idle(idle) = serde_json::from_value(wire.clone()).unwrap() else {
            panic!("expected idle state update");
        };
        let Some(StopReason::Other(other)) = &idle.stop_reason else {
            panic!("expected a custom stop reason");
        };
        assert!(other.fields.is_empty());

        #[cfg(feature = "unstable_end_turn_token_usage")]
        {
            assert!(idle.usage.is_some());
            assert_eq!(serde_json::to_value(&idle).unwrap()["usage"], usage);
        }
        // Without the feature, `usage` is not a field of the idle update, and it
        // must not be smuggled through as a field of the stop reason either.
        #[cfg(not(feature = "unstable_end_turn_token_usage"))]
        assert!(serde_json::to_value(&idle).unwrap().get("usage").is_none());
    }

    #[test]
    fn test_state_update_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::StateUpdate(StateUpdate::Running(
                RunningStateUpdate::new()
            )))
            .unwrap(),
            json!({
                "sessionUpdate": "state_update",
                "state": "running"
            })
        );

        assert_eq!(
            serde_json::to_value(SessionUpdate::StateUpdate(StateUpdate::Idle(
                IdleStateUpdate::new().stop_reason(StopReason::EndTurn)
            )))
            .unwrap(),
            json!({
                "sessionUpdate": "state_update",
                "state": "idle",
                "stopReason": "end_turn"
            })
        );

        let SessionUpdate::StateUpdate(update) = serde_json::from_value(json!({
            "sessionUpdate": "state_update",
            "state": "requires_action"
        }))
        .unwrap() else {
            panic!("expected state update");
        };

        assert!(matches!(update, StateUpdate::RequiresAction(_)));

        let SessionUpdate::StateUpdate(StateUpdate::Idle(update)) = serde_json::from_value(json!({
            "sessionUpdate": "state_update",
            "state": "idle",
            "stopReason": null
        }))
        .unwrap() else {
            panic!("expected idle state update");
        };

        assert_eq!(update.stop_reason, None);

        let SessionUpdate::StateUpdate(StateUpdate::Other(update)) =
            serde_json::from_value(json!({
                "sessionUpdate": "state_update",
                "state": "_paused",
                "label": "Paused"
            }))
            .unwrap()
        else {
            panic!("expected unknown state update");
        };

        assert_eq!(update.state, "_paused");
        assert_eq!(update.fields["label"], json!("Paused"));
    }

    #[test]
    fn session_update_preserves_unknown_variant() {
        use serde_json::json;

        let update: SessionUpdate = serde_json::from_value(json!({
            "sessionUpdate": "_status_badge",
            "label": "Indexing",
            "progress": 0.5
        }))
        .unwrap();

        let SessionUpdate::Other(unknown) = update else {
            panic!("expected unknown session update");
        };

        assert_eq!(unknown.session_update, "_status_badge");
        assert_eq!(unknown.fields.get("label"), Some(&json!("Indexing")));
        assert_eq!(unknown.fields.get("progress"), Some(&json!(0.5)));

        assert_eq!(
            serde_json::to_value(SessionUpdate::Other(unknown)).unwrap(),
            json!({
                "sessionUpdate": "_status_badge",
                "label": "Indexing",
                "progress": 0.5
            })
        );
    }

    #[test]
    fn terminal_session_updates_use_known_discriminators() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::TerminalUpdate(
                TerminalUpdate::new("term_1").command("cargo test")
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "terminal_update",
                "terminalId": "term_1",
                "command": "cargo test"
            })
        );
        assert_eq!(
            serde_json::to_value(SessionUpdate::TerminalOutputChunk(
                TerminalOutputChunk::new("term_1", "dGVzdAo=")
            ))
            .unwrap(),
            json!({
                "sessionUpdate": "terminal_output_chunk",
                "terminalId": "term_1",
                "data": "dGVzdAo="
            })
        );
    }

    #[test]
    fn session_update_does_not_hide_malformed_known_terminal_variants() {
        use serde_json::json;

        assert!(
            serde_json::from_value::<SessionUpdate>(json!({
                "sessionUpdate": "terminal_update"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<SessionUpdate>(json!({
                "sessionUpdate": "terminal_output_chunk",
                "terminalId": "term_1"
            }))
            .is_err()
        );
    }

    #[test]
    fn test_plan_update_serialization() {
        use serde_json::json;

        let plan_update =
            SessionUpdate::PlanUpdate(PlanUpdate::new(crate::v2::PlanUpdateContent::items(
                "plan-1",
                vec![crate::v2::PlanEntry::new(
                    "Step 1",
                    crate::v2::PlanEntryPriority::High,
                    crate::v2::PlanEntryStatus::Pending,
                )],
            )));

        assert_eq!(
            serde_json::to_value(plan_update).unwrap(),
            json!({
                "sessionUpdate": "plan_update",
                "plan": {
                    "type": "items",
                    "planId": "plan-1",
                    "entries": [
                        {
                            "content": "Step 1",
                            "priority": "high",
                            "status": "pending"
                        }
                    ]
                }
            })
        );
    }

    #[cfg(feature = "unstable_plan_operations")]
    #[test]
    fn test_plan_removed_serialization() {
        use serde_json::json;

        assert_eq!(
            serde_json::to_value(SessionUpdate::PlanRemoved(PlanRemoved::new("plan-1"))).unwrap(),
            json!({
                "sessionUpdate": "plan_removed",
                "planId": "plan-1"
            })
        );
    }

    #[test]
    fn available_command_uses_type_discriminator() {
        use serde_json::json;

        let command = AvailableCommand::Command(
            Command::new("web", "Search the web")
                .input(AvailableCommandInput::Text(TextCommandInput::new("Query"))),
        );

        let json = serde_json::to_value(&command).unwrap();
        assert_eq!(
            json,
            json!({
                "type": "command",
                "name": "web",
                "description": "Search the web",
                "input": { "type": "text", "hint": "Query" }
            })
        );

        let roundtripped: AvailableCommand = serde_json::from_value(json).unwrap();
        assert_eq!(roundtripped, command);
        assert_eq!(roundtripped.name(), "web");
        assert_eq!(roundtripped.description(), "Search the web");
    }

    #[test]
    fn available_command_preserves_unknown_typed_variant() {
        use serde_json::json;

        let payload = json!({
            "type": "_skill",
            "name": "pdf-processing",
            "description": "Extract text from PDFs",
            "uri": "skill://pdf-processing/SKILL.md",
            "_meta": { "example.com/source": "mcp" }
        });
        let command: AvailableCommand = serde_json::from_value(payload.clone()).unwrap();

        assert_eq!(command.name(), "pdf-processing");
        assert_eq!(command.description(), "Extract text from PDFs");
        assert!(command.meta().is_some());

        let AvailableCommand::Other(unknown) = &command else {
            panic!("expected unknown command");
        };
        assert_eq!(unknown.type_, "_skill");
        assert_eq!(
            unknown.fields.get("uri"),
            Some(&json!("skill://pdf-processing/SKILL.md"))
        );
        assert_eq!(serde_json::to_value(&command).unwrap(), payload);
    }

    #[test]
    fn available_command_unknown_tolerates_invalid_meta() {
        use serde_json::json;

        let command: AvailableCommand = serde_json::from_value(json!({
            "type": "_skill",
            "name": "pdf-processing",
            "description": "Extract text from PDFs",
            "_meta": "oops"
        }))
        .unwrap();

        assert!(matches!(command, AvailableCommand::Other(_)));
        assert!(command.meta().is_none());
    }

    #[test]
    fn available_command_unknown_does_not_hide_malformed_command_variant() {
        use serde_json::json;

        // A missing discriminator is rejected rather than defaulting to `command`.
        assert!(
            serde_json::from_value::<AvailableCommand>(json!({
                "name": "test",
                "description": "Run project tests"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<AvailableCommand>(json!({
                "type": "command",
                "name": "test"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<OtherAvailableCommand>(json!({
                "type": "command",
                "name": "test",
                "description": "Run project tests"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<AvailableCommand>(json!({
                "type": "_skill",
                "name": "pdf-processing"
            }))
            .is_err()
        );
    }

    #[test]
    fn available_command_input_preserves_unknown_typed_variant() {
        use serde_json::json;

        let input: AvailableCommandInput = serde_json::from_value(json!({
            "type": "_choices",
            "hint": "Pick one",
            "options": ["fast", "careful"]
        }))
        .unwrap();

        let AvailableCommandInput::Other(unknown) = input else {
            panic!("expected unknown command input");
        };

        assert_eq!(unknown.type_, "_choices");
        assert_eq!(unknown.fields.get("hint"), Some(&json!("Pick one")));
        assert_eq!(
            unknown.fields.get("options"),
            Some(&json!(["fast", "careful"]))
        );
        assert_eq!(
            serde_json::to_value(AvailableCommandInput::Other(unknown)).unwrap(),
            json!({
                "type": "_choices",
                "hint": "Pick one",
                "options": ["fast", "careful"]
            })
        );
    }

    #[test]
    fn available_command_input_text_uses_type_discriminator() {
        use serde_json::json;

        let input = AvailableCommandInput::Text(TextCommandInput::new("Describe changes"));

        let json = serde_json::to_value(&input).unwrap();
        assert_eq!(
            json,
            json!({
                "type": "text",
                "hint": "Describe changes"
            })
        );

        let roundtripped: AvailableCommandInput = serde_json::from_value(json).unwrap();
        assert!(matches!(roundtripped, AvailableCommandInput::Text(_)));
    }

    #[test]
    fn request_permission_subject_tool_call_uses_type_discriminator() {
        use serde_json::json;

        let subject = RequestPermissionSubject::from(ToolCallUpdate::new("call_001"));

        let json = serde_json::to_value(&subject).unwrap();
        assert_eq!(
            json,
            json!({
                "type": "tool_call",
                "toolCall": {
                    "toolCallId": "call_001"
                }
            })
        );

        let roundtripped: RequestPermissionSubject = serde_json::from_value(json).unwrap();
        assert!(matches!(
            roundtripped,
            RequestPermissionSubject::ToolCall(_)
        ));
    }

    #[test]
    fn request_permission_subject_command_uses_type_discriminator() {
        use serde_json::json;

        let mut meta = Meta::new();
        meta.insert("source".to_string(), json!("shell"));
        let subject = RequestPermissionSubject::from(
            CommandPermissionSubject::new("cargo test", "/workspace/project")
                .tool_call_id("call_001")
                .terminal_id("term_1")
                .meta(meta),
        );

        let json = serde_json::to_value(&subject).unwrap();
        assert_eq!(
            json,
            json!({
                "type": "command",
                "command": "cargo test",
                "cwd": "/workspace/project",
                "toolCallId": "call_001",
                "terminalId": "term_1",
                "_meta": {
                    "source": "shell"
                }
            })
        );

        let roundtripped: RequestPermissionSubject = serde_json::from_value(json).unwrap();
        assert!(matches!(roundtripped, RequestPermissionSubject::Command(_)));
    }

    #[test]
    fn command_permission_subject_treats_optional_association_nulls_as_omitted() {
        use serde_json::json;

        let subject: RequestPermissionSubject = serde_json::from_value(json!({
            "type": "command",
            "command": "cargo test",
            "cwd": "/workspace/project",
            "toolCallId": null,
            "terminalId": null,
            "_meta": null
        }))
        .unwrap();

        let RequestPermissionSubject::Command(subject) = subject else {
            panic!("expected command permission subject");
        };
        assert_eq!(subject.cwd, AbsolutePath::new("/workspace/project"));
        assert_eq!(subject.tool_call_id, None);
        assert_eq!(subject.terminal_id, None);
        assert_eq!(subject.meta, None);
        assert_eq!(
            serde_json::to_value(RequestPermissionSubject::Command(subject)).unwrap(),
            json!({
                "type": "command",
                "command": "cargo test",
                "cwd": "/workspace/project"
            })
        );
    }

    #[test]
    fn request_permission_subject_preserves_unknown_variant() {
        use serde_json::json;

        let subject: RequestPermissionSubject = serde_json::from_value(json!({
            "type": "_review",
            "reason": "needs-review",
            "retryAfterSeconds": 30
        }))
        .unwrap();

        let RequestPermissionSubject::Other(unknown) = subject else {
            panic!("expected unknown permission subject");
        };

        assert_eq!(unknown.type_, "_review");
        assert_eq!(unknown.fields.get("reason"), Some(&json!("needs-review")));
        assert_eq!(unknown.fields.get("retryAfterSeconds"), Some(&json!(30)));
        assert_eq!(
            serde_json::to_value(RequestPermissionSubject::Other(unknown)).unwrap(),
            json!({
                "type": "_review",
                "reason": "needs-review",
                "retryAfterSeconds": 30
            })
        );
    }

    #[test]
    fn request_permission_subject_unknown_does_not_hide_malformed_known_variant() {
        use serde_json::json;

        assert!(
            serde_json::from_value::<RequestPermissionSubject>(json!({
                "type": "tool_call"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<RequestPermissionSubject>(json!({
                "type": 1
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<RequestPermissionSubject>(json!({
                "type": "command",
                "cwd": "/workspace/project"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<RequestPermissionSubject>(json!({
                "type": "command",
                "command": "cargo test"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<RequestPermissionSubject>(json!({
                "type": "command",
                "command": "cargo test",
                "cwd": null
            }))
            .is_err()
        );
    }

    #[test]
    fn request_permission_title_and_description_are_separate_from_tool_call_content() {
        use serde_json::json;

        let request =
            RequestPermissionRequest::new("sess_abc123def456", "Approve file edit?", Vec::new())
                .description("Allow this tool to edit src/main.rs?")
                .subject(RequestPermissionSubject::from(ToolCallUpdate::new(
                    "call_001",
                )));

        assert_eq!(
            serde_json::to_value(request).unwrap(),
            json!({
                "sessionId": "sess_abc123def456",
                "title": "Approve file edit?",
                "description": "Allow this tool to edit src/main.rs?",
                "subject": {
                    "type": "tool_call",
                    "toolCall": {
                        "toolCallId": "call_001"
                    }
                },
                "options": []
            })
        );
    }

    #[test]
    fn request_permission_requires_title_and_allows_missing_subject() {
        use serde_json::json;

        let request = RequestPermissionRequest::new(
            "sess_abc123def456",
            "Approve elevated permissions?",
            Vec::new(),
        );

        assert_eq!(
            serde_json::to_value(request).unwrap(),
            json!({
                "sessionId": "sess_abc123def456",
                "title": "Approve elevated permissions?",
                "options": []
            })
        );

        let missing_subject: RequestPermissionRequest = serde_json::from_value(json!({
            "sessionId": "sess_abc123def456",
            "title": "Approve elevated permissions?",
            "options": []
        }))
        .unwrap();
        assert!(missing_subject.subject.is_none());

        let null_subject: RequestPermissionRequest = serde_json::from_value(json!({
            "sessionId": "sess_abc123def456",
            "title": "Approve elevated permissions?",
            "subject": null,
            "options": []
        }))
        .unwrap();
        assert!(null_subject.subject.is_none());

        assert!(
            serde_json::from_value::<RequestPermissionRequest>(json!({
                "sessionId": "sess_abc123def456",
                "options": []
            }))
            .is_err()
        );
    }

    #[test]
    fn request_permission_outcome_preserves_unknown_variant() {
        use serde_json::json;

        let outcome: RequestPermissionOutcome = serde_json::from_value(json!({
            "outcome": "_defer",
            "reason": "needs-review",
            "retryAfterSeconds": 30
        }))
        .unwrap();

        let RequestPermissionOutcome::Other(unknown) = outcome else {
            panic!("expected unknown permission outcome");
        };

        assert_eq!(unknown.outcome, "_defer");
        assert_eq!(unknown.fields.get("reason"), Some(&json!("needs-review")));
        assert_eq!(unknown.fields.get("retryAfterSeconds"), Some(&json!(30)));
        assert_eq!(
            serde_json::to_value(RequestPermissionOutcome::Other(unknown)).unwrap(),
            json!({
                "outcome": "_defer",
                "reason": "needs-review",
                "retryAfterSeconds": 30
            })
        );
    }

    #[test]
    fn request_permission_outcome_unknown_does_not_hide_malformed_known_variant() {
        use serde_json::json;

        assert!(
            serde_json::from_value::<RequestPermissionOutcome>(json!({
                "outcome": "selected"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<RequestPermissionOutcome>(json!({
                "outcome": 1
            }))
            .is_err()
        );
    }

    #[test]
    fn available_command_input_unknown_does_not_hide_malformed_text_variant() {
        use serde_json::json;

        assert!(serde_json::from_value::<AvailableCommandInput>(json!({})).is_err());
        assert!(
            serde_json::from_value::<AvailableCommandInput>(json!({
                "hint": "Pick one"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<AvailableCommandInput>(json!({
                "type": 1,
                "hint": "Pick one"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<OtherAvailableCommandInput>(json!({
                "type": "text",
                "hint": "Pick one"
            }))
            .is_err()
        );
    }

    #[cfg(feature = "unstable_mcp_over_acp")]
    #[test]
    fn test_agent_mcp_request_method_names() {
        use serde_json::json;

        let params: serde_json::Map<String, serde_json::Value> =
            [("cursor".to_string(), json!("abc"))].into_iter().collect();

        assert_eq!(CLIENT_METHOD_NAMES.mcp_message, "mcp/message");
        assert_eq!(
            AgentRequest::MessageMcpRequest(Box::new(MessageMcpRequest::new(
                "server-1",
                "req-1",
                "tools/list"
            )))
            .method(),
            "mcp/message"
        );
        assert_eq!(
            serde_json::to_value(
                MessageMcpRequest::new("server-1", "req-1", "tools/list").params(params)
            )
            .unwrap(),
            json!({
                "serverId": "server-1",
                "requestId": "req-1",
                "method": "tools/list",
                "params": { "cursor": "abc" }
            })
        );

        let request_with_null_params: MessageMcpRequest = serde_json::from_value(json!({
            "serverId": "server-1",
            "requestId": "req-1",
            "method": "tools/list",
            "params": null,
            "_meta": null
        }))
        .unwrap();
        assert_eq!(request_with_null_params.params, None);
        assert_eq!(request_with_null_params.meta, None);
        for key in ["serverId", "requestId", "method"] {
            let mut value =
                json!({"serverId":"server-1", "requestId":"req-1", "method":"tools/list"});
            value.as_object_mut().unwrap().remove(key);
            assert!(serde_json::from_value::<MessageMcpRequest>(value).is_err());
        }
        for key in ["serverId", "requestId", "method"] {
            let mut value =
                json!({"serverId":"server-1", "requestId":"req-1", "method":"tools/list"});
            value[key] = serde_json::Value::Null;
            assert!(serde_json::from_value::<MessageMcpRequest>(value).is_err());
        }
    }

    #[test]
    fn test_auth_capabilities_serialize_terminal_support_as_object() {
        use serde_json::json;

        let capabilities = ClientAuthCapabilities::new().terminal(TerminalAuthCapabilities::new());

        assert_eq!(
            serde_json::to_value(&capabilities).unwrap(),
            json!({
                "terminal": {}
            })
        );

        let deserialized: ClientAuthCapabilities = serde_json::from_value(json!({
            "terminal": false
        }))
        .unwrap();
        assert!(deserialized.terminal.is_none());
    }

    #[test]
    fn request_permission_request_rejects_malformed_options() {
        use serde_json::json;

        assert!(
            serde_json::from_value::<RequestPermissionRequest>(json!({
                "sessionId": "sess-1",
                "title": "Run tool?",
                "options": "not-an-array"
            }))
            .is_err()
        );
        assert!(
            serde_json::from_value::<RequestPermissionRequest>(json!({
                "sessionId": "sess-1",
                "title": "Run tool?",
                "options": [{"optionId": "allow"}]
            }))
            .is_err()
        );
    }

    #[cfg(feature = "unstable_plan_operations")]
    #[test]
    fn malformed_plan_removed_is_not_hidden_as_unknown_update() {
        use serde_json::json;

        assert!(
            serde_json::from_value::<SessionUpdate>(json!({
                "sessionUpdate": "plan_removed"
            }))
            .is_err()
        );
    }
}