Merge branch 'main' into feature/large-user-message-tempfile

codex-rs/protocol/src/config_types.rs

@@ -4,6 +4,8 @@ use serde::Serialize;
 use strum_macros::Display;
 use ts_rs::TS;
 
+use crate::openai_models::ReasoningEffort;
+
 /// A summary of the reasoning performed by the model. This can be useful for
 /// debugging and understanding the model's reasoning process.
 /// See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries
@@ -63,6 +65,18 @@ pub enum SandboxMode {
     DangerFullAccess,
 }
 
+#[derive(
+    Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq, Display, JsonSchema, TS, Default,
+)]
+#[serde(rename_all = "lowercase")]
+#[strum(serialize_all = "lowercase")]
+pub enum WebSearchMode {
+    #[default]
+    Disabled,
+    Cached,
+    Live,
+}
+
 #[derive(Debug, Serialize, Deserialize, Clone, Copy, PartialEq, Eq, Display, JsonSchema, TS)]
 #[serde(rename_all = "lowercase")]
 #[strum(serialize_all = "lowercase")]
@@ -115,3 +129,72 @@ pub enum AltScreenMode {
     /// Never use alternate screen (inline mode only).
     Never,
 }
+
+/// Collaboration mode for a Codex session.
+#[derive(Clone, PartialEq, Eq, Hash, Debug, Serialize, Deserialize, JsonSchema, TS)]
+#[serde(tag = "mode", rename_all = "lowercase")]
+pub enum CollaborationMode {
+    Plan(Settings),
+    PairProgramming(Settings),
+    Execute(Settings),
+    Custom(Settings),
+}
+
+impl CollaborationMode {
+    /// Returns a reference to the settings, regardless of variant.
+    fn settings(&self) -> &Settings {
+        match self {
+            CollaborationMode::Plan(settings)
+            | CollaborationMode::PairProgramming(settings)
+            | CollaborationMode::Execute(settings)
+            | CollaborationMode::Custom(settings) => settings,
+        }
+    }
+
+    pub fn model(&self) -> &str {
+        self.settings().model.as_str()
+    }
+
+    pub fn reasoning_effort(&self) -> Option<ReasoningEffort> {
+        self.settings().reasoning_effort
+    }
+
+    /// Updates the collaboration mode with new model and/or effort values.
+    ///
+    /// - `model`: `Some(s)` to update the model, `None` to keep the current model
+    /// - `effort`: `Some(Some(e))` to set effort to `e`, `Some(None)` to clear effort, `None` to keep current effort
+    /// - `developer_instructions`: `Some(s)` to update developer instructions, `None` to keep current
+    ///
+    /// Returns a new `CollaborationMode` with updated values, preserving the variant.
+    pub fn with_updates(
+        &self,
+        model: Option<String>,
+        effort: Option<Option<ReasoningEffort>>,
+        developer_instructions: Option<String>,
+    ) -> Self {
+        let settings = self.settings();
+        let updated_settings = Settings {
+            model: model.unwrap_or_else(|| settings.model.clone()),
+            reasoning_effort: effort.unwrap_or(settings.reasoning_effort),
+            developer_instructions: developer_instructions
+                .or_else(|| settings.developer_instructions.clone()),
+        };
+
+        match self {
+            CollaborationMode::Plan(_) => CollaborationMode::Plan(updated_settings),
+            CollaborationMode::PairProgramming(_) => {
+                CollaborationMode::PairProgramming(updated_settings)
+            }
+            CollaborationMode::Execute(_) => CollaborationMode::Execute(updated_settings),
+            CollaborationMode::Custom(_) => CollaborationMode::Custom(updated_settings),
+        }
+    }
+}
+
+/// Settings for a collaboration mode.
+#[derive(Clone, PartialEq, Eq, Hash, Debug, Serialize, Deserialize, JsonSchema, TS)]
+pub struct Settings {
+    pub model: String,
+    pub reasoning_effort: Option<ReasoningEffort>,
+    pub developer_instructions: Option<String>,
+}

codex-rs/protocol/src/items.rs

@@ -4,6 +4,8 @@ use crate::protocol::AgentReasoningRawContentEvent;
 use crate::protocol::EventMsg;
 use crate::protocol::UserMessageEvent;
 use crate::protocol::WebSearchEndEvent;
+use crate::user_input::ByteRange;
+use crate::user_input::TextElement;
 use crate::user_input::UserInput;
 use schemars::JsonSchema;
 use serde::Deserialize;
@@ -62,9 +64,13 @@ impl UserMessageItem {
     }
 
     pub fn as_legacy_event(&self) -> EventMsg {
+        // Legacy user-message events flatten only text inputs into `message` and
+        // rebase text element ranges onto that concatenated text.
         EventMsg::UserMessage(UserMessageEvent {
             message: self.message(),
             images: Some(self.image_urls()),
+            local_images: self.local_image_paths(),
+            text_elements: self.text_elements(),
         })
     }
 
@@ -72,13 +78,39 @@ impl UserMessageItem {
         self.content
             .iter()
             .map(|c| match c {
-                UserInput::Text { text } => text.clone(),
+                UserInput::Text { text, .. } => text.clone(),
                 _ => String::new(),
             })
             .collect::<Vec<String>>()
             .join("")
     }
 
+    pub fn text_elements(&self) -> Vec<TextElement> {
+        let mut out = Vec::new();
+        let mut offset = 0usize;
+        for input in &self.content {
+            if let UserInput::Text {
+                text,
+                text_elements,
+            } = input
+            {
+                // Text element ranges are relative to each text chunk; offset them so they align
+                // with the concatenated message returned by `message()`.
+                for elem in text_elements {
+                    out.push(TextElement {
+                        byte_range: ByteRange {
+                            start: offset + elem.byte_range.start,
+                            end: offset + elem.byte_range.end,
+                        },
+                        placeholder: elem.placeholder.clone(),
+                    });
+                }
+                offset += text.len();
+            }
+        }
+        out
+    }
+
     pub fn image_urls(&self) -> Vec<String> {
         self.content
             .iter()
@@ -88,6 +120,16 @@ impl UserMessageItem {
             })
             .collect()
     }
+
+    pub fn local_image_paths(&self) -> Vec<std::path::PathBuf> {
+        self.content
+            .iter()
+            .filter_map(|c| match c {
+                UserInput::LocalImage { path } => Some(path.clone()),
+                _ => None,
+            })
+            .collect()
+    }
 }
 
 impl AgentMessageItem {

codex-rs/protocol/src/models.rs

@@ -10,8 +10,11 @@ use serde::Serialize;
 use serde::ser::Serializer;
 use ts_rs::TS;
 
+use crate::config_types::CollaborationMode;
 use crate::config_types::SandboxMode;
 use crate::protocol::AskForApproval;
+use crate::protocol::COLLABORATION_MODE_CLOSE_TAG;
+use crate::protocol::COLLABORATION_MODE_OPEN_TAG;
 use crate::protocol::NetworkAccess;
 use crate::protocol::SandboxPolicy;
 use crate::protocol::WritableRoot;
@@ -273,6 +276,25 @@ impl DeveloperInstructions {
         )
     }
 
+    /// Returns developer instructions from a collaboration mode if they exist and are non-empty.
+    pub fn from_collaboration_mode(collaboration_mode: &CollaborationMode) -> Option<Self> {
+        let settings = match collaboration_mode {
+            CollaborationMode::Plan(settings)
+            | CollaborationMode::PairProgramming(settings)
+            | CollaborationMode::Execute(settings)
+            | CollaborationMode::Custom(settings) => settings,
+        };
+        settings
+            .developer_instructions
+            .as_ref()
+            .filter(|instructions| !instructions.is_empty())
+            .map(|instructions| {
+                DeveloperInstructions::new(format!(
+                    "{COLLABORATION_MODE_OPEN_TAG}{instructions}{COLLABORATION_MODE_CLOSE_TAG}"
+                ))
+            })
+    }
+
     fn from_permissions_with_network(
         sandbox_mode: SandboxMode,
         network_access: NetworkAccess,
@@ -593,7 +615,7 @@ impl From<Vec<UserInput>> for ResponseInputItem {
             content: items
                 .into_iter()
                 .flat_map(|c| match c {
-                    UserInput::Text { text } => vec![ContentItem::InputText { text }],
+                    UserInput::Text { text, .. } => vec![ContentItem::InputText { text }],
                     UserInput::Image { image_url } => vec![
                         ContentItem::InputText {
                             text: image_open_tag_text(),

codex-rs/protocol/src/openai_models.rs

@@ -1,4 +1,5 @@
 use std::collections::HashMap;
+use std::collections::HashSet;
 
 use schemars::JsonSchema;
 use serde::Deserialize;
@@ -54,6 +55,7 @@ pub struct ModelUpgrade {
     pub migration_config_key: String,
     pub model_link: Option<String>,
     pub upgrade_copy: Option<String>,
+    pub migration_markdown: Option<String>,
 }
 
 /// Metadata describing a Codex-supported model.
@@ -176,7 +178,7 @@ pub struct ModelInfo {
     pub visibility: ModelVisibility,
     pub supported_in_api: bool,
     pub priority: i32,
-    pub upgrade: Option<String>,
+    pub upgrade: Option<ModelInfoUpgrade>,
     pub base_instructions: String,
     pub supports_reasoning_summaries: bool,
     pub support_verbosity: bool,
@@ -206,6 +208,21 @@ impl ModelInfo {
     }
 }
 
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]
+pub struct ModelInfoUpgrade {
+    pub model: String,
+    pub migration_markdown: String,
+}
+
+impl From<&ModelUpgrade> for ModelInfoUpgrade {
+    fn from(upgrade: &ModelUpgrade) -> Self {
+        ModelInfoUpgrade {
+            model: upgrade.id.clone(),
+            migration_markdown: upgrade.migration_markdown.clone().unwrap_or_default(),
+        }
+    }
+}
+
 /// Response wrapper for `/models`.
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema, Default)]
 pub struct ModelsResponse {
@@ -225,8 +242,8 @@ impl From<ModelInfo> for ModelPreset {
                 .unwrap_or(ReasoningEffort::None),
             supported_reasoning_efforts: info.supported_reasoning_levels.clone(),
             is_default: false, // default is the highest priority available model
-            upgrade: info.upgrade.as_ref().map(|upgrade_slug| ModelUpgrade {
-                id: upgrade_slug.clone(),
+            upgrade: info.upgrade.as_ref().map(|upgrade| ModelUpgrade {
+                id: upgrade.model.clone(),
                 reasoning_effort_mapping: reasoning_effort_mapping_from_presets(
                     &info.supported_reasoning_levels,
                 ),
@@ -234,6 +251,7 @@ impl From<ModelInfo> for ModelPreset {
                 // todo(aibrahim): add the model link here.
                 model_link: None,
                 upgrade_copy: None,
+                migration_markdown: Some(upgrade.migration_markdown.clone()),
             }),
             show_in_picker: info.visibility == ModelVisibility::List,
             supported_in_api: info.supported_in_api,
@@ -241,6 +259,46 @@ impl From<ModelInfo> for ModelPreset {
     }
 }
 
+impl ModelPreset {
+    /// Filter models based on authentication mode.
+    ///
+    /// In ChatGPT mode, all models are visible. Otherwise, only API-supported models are shown.
+    pub fn filter_by_auth(models: Vec<ModelPreset>, chatgpt_mode: bool) -> Vec<ModelPreset> {
+        models
+            .into_iter()
+            .filter(|model| chatgpt_mode || model.supported_in_api)
+            .collect()
+    }
+
+    /// Merge remote presets with existing presets, preferring remote when slugs match.
+    ///
+    /// Remote presets take precedence. Existing presets not in remote are appended with `is_default` set to false.
+    pub fn merge(
+        remote_presets: Vec<ModelPreset>,
+        existing_presets: Vec<ModelPreset>,
+    ) -> Vec<ModelPreset> {
+        if remote_presets.is_empty() {
+            return existing_presets;
+        }
+
+        let remote_slugs: HashSet<&str> = remote_presets
+            .iter()
+            .map(|preset| preset.model.as_str())
+            .collect();
+
+        let mut merged_presets = remote_presets.clone();
+        for mut preset in existing_presets {
+            if remote_slugs.contains(preset.model.as_str()) {
+                continue;
+            }
+            preset.is_default = false;
+            merged_presets.push(preset);
+        }
+
+        merged_presets
+    }
+}
+
 fn reasoning_effort_mapping_from_presets(
     presets: &[ReasoningEffortPreset],
 ) -> Option<HashMap<ReasoningEffort, ReasoningEffort>> {

codex-rs/protocol/src/protocol.rs

@@ -4,6 +4,7 @@
 //! between user and agent.
 
 use std::collections::HashMap;
+use std::ffi::OsStr;
 use std::fmt;
 use std::path::Path;
 use std::path::PathBuf;
@@ -12,6 +13,7 @@ use std::time::Duration;
 
 use crate::ThreadId;
 use crate::approvals::ElicitationRequestEvent;
+use crate::config_types::CollaborationMode;
 use crate::config_types::ReasoningSummary as ReasoningSummaryConfig;
 use crate::custom_prompts::CustomPrompt;
 use crate::items::TurnItem;
@@ -49,6 +51,8 @@ pub const USER_INSTRUCTIONS_OPEN_TAG: &str = "<user_instructions>";
 pub const USER_INSTRUCTIONS_CLOSE_TAG: &str = "</user_instructions>";
 pub const ENVIRONMENT_CONTEXT_OPEN_TAG: &str = "<environment_context>";
 pub const ENVIRONMENT_CONTEXT_CLOSE_TAG: &str = "</environment_context>";
+pub const COLLABORATION_MODE_OPEN_TAG: &str = "<collaboration_mode>";
+pub const COLLABORATION_MODE_CLOSE_TAG: &str = "</collaboration_mode>";
 pub const USER_MESSAGE_BEGIN: &str = "## My request for Codex:";
 
 /// Submission Queue Entry - requests from user
@@ -114,6 +118,11 @@ pub enum Op {
         summary: ReasoningSummaryConfig,
         // The JSON schema to use for the final assistant message
         final_output_json_schema: Option<Value>,
+
+        /// EXPERIMENTAL - set a pre-set collaboration mode.
+        /// Takes precedence over model, effort, and developer instructions if set.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        collaboration_mode: Option<CollaborationMode>,
     },
 
     /// Override parts of the persistent turn context for subsequent turns.
@@ -149,6 +158,11 @@ pub enum Op {
         /// Updated reasoning summary preference (honored only for reasoning-capable models).
         #[serde(skip_serializing_if = "Option::is_none")]
         summary: Option<ReasoningSummaryConfig>,
+
+        /// EXPERIMENTAL - set a pre-set collaboration mode.
+        /// Takes precedence over model, effort, and developer instructions if set.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        collaboration_mode: Option<CollaborationMode>,
     },
 
     /// Approve a command execution
@@ -505,12 +519,26 @@ impl SandboxPolicy {
                 roots
                     .into_iter()
                     .map(|writable_root| {
-                        let mut subpaths = Vec::new();
+                        let mut subpaths: Vec<AbsolutePathBuf> = Vec::new();
                         #[allow(clippy::expect_used)]
                         let top_level_git = writable_root
                             .join(".git")
                             .expect(".git is a valid relative path");
-                        if top_level_git.as_path().is_dir() {
+                        // This applies to typical repos (directory .git), worktrees/submodules
+                        // (file .git with gitdir pointer), and bare repos when the gitdir is the
+                        // writable root itself.
+                        let top_level_git_is_file = top_level_git.as_path().is_file();
+                        let top_level_git_is_dir = top_level_git.as_path().is_dir();
+                        if top_level_git_is_dir || top_level_git_is_file {
+                            if top_level_git_is_file
+                                && is_git_pointer_file(&top_level_git)
+                                && let Some(gitdir) = resolve_gitdir_from_file(&top_level_git)
+                                && !subpaths
+                                    .iter()
+                                    .any(|subpath| subpath.as_path() == gitdir.as_path())
+                            {
+                                subpaths.push(gitdir);
+                            }
                             subpaths.push(top_level_git);
                         }
                         #[allow(clippy::expect_used)]
@@ -531,6 +559,71 @@ impl SandboxPolicy {
     }
 }
 
+fn is_git_pointer_file(path: &AbsolutePathBuf) -> bool {
+    path.as_path().is_file() && path.as_path().file_name() == Some(OsStr::new(".git"))
+}
+
+fn resolve_gitdir_from_file(dot_git: &AbsolutePathBuf) -> Option<AbsolutePathBuf> {
+    let contents = match std::fs::read_to_string(dot_git.as_path()) {
+        Ok(contents) => contents,
+        Err(err) => {
+            error!(
+                "Failed to read {path} for gitdir pointer: {err}",
+                path = dot_git.as_path().display()
+            );
+            return None;
+        }
+    };
+
+    let trimmed = contents.trim();
+    let (_, gitdir_raw) = match trimmed.split_once(':') {
+        Some(parts) => parts,
+        None => {
+            error!(
+                "Expected {path} to contain a gitdir pointer, but it did not match `gitdir: <path>`.",
+                path = dot_git.as_path().display()
+            );
+            return None;
+        }
+    };
+    let gitdir_raw = gitdir_raw.trim();
+    if gitdir_raw.is_empty() {
+        error!(
+            "Expected {path} to contain a gitdir pointer, but it was empty.",
+            path = dot_git.as_path().display()
+        );
+        return None;
+    }
+    let base = match dot_git.as_path().parent() {
+        Some(base) => base,
+        None => {
+            error!(
+                "Unable to resolve parent directory for {path}.",
+                path = dot_git.as_path().display()
+            );
+            return None;
+        }
+    };
+    let gitdir_path = match AbsolutePathBuf::resolve_path_against_base(gitdir_raw, base) {
+        Ok(path) => path,
+        Err(err) => {
+            error!(
+                "Failed to resolve gitdir path {gitdir_raw} from {path}: {err}",
+                path = dot_git.as_path().display()
+            );
+            return None;
+        }
+    };
+    if !gitdir_path.as_path().exists() {
+        error!(
+            "Resolved gitdir path {path} does not exist.",
+            path = gitdir_path.as_path().display()
+        );
+        return None;
+    }
+    Some(gitdir_path)
+}
+
 /// Event Queue Entry - events from agent
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct Event {
@@ -693,6 +786,71 @@ pub enum EventMsg {
     AgentMessageContentDelta(AgentMessageContentDeltaEvent),
     ReasoningContentDelta(ReasoningContentDeltaEvent),
     ReasoningRawContentDelta(ReasoningRawContentDeltaEvent),
+
+    /// Collab interaction: agent spawn begin.
+    CollabAgentSpawnBegin(CollabAgentSpawnBeginEvent),
+    /// Collab interaction: agent spawn end.
+    CollabAgentSpawnEnd(CollabAgentSpawnEndEvent),
+    /// Collab interaction: agent interaction begin.
+    CollabAgentInteractionBegin(CollabAgentInteractionBeginEvent),
+    /// Collab interaction: agent interaction end.
+    CollabAgentInteractionEnd(CollabAgentInteractionEndEvent),
+    /// Collab interaction: waiting begin.
+    CollabWaitingBegin(CollabWaitingBeginEvent),
+    /// Collab interaction: waiting end.
+    CollabWaitingEnd(CollabWaitingEndEvent),
+    /// Collab interaction: close begin.
+    CollabCloseBegin(CollabCloseBeginEvent),
+    /// Collab interaction: close end.
+    CollabCloseEnd(CollabCloseEndEvent),
+}
+
+impl From<CollabAgentSpawnBeginEvent> for EventMsg {
+    fn from(event: CollabAgentSpawnBeginEvent) -> Self {
+        EventMsg::CollabAgentSpawnBegin(event)
+    }
+}
+
+impl From<CollabAgentSpawnEndEvent> for EventMsg {
+    fn from(event: CollabAgentSpawnEndEvent) -> Self {
+        EventMsg::CollabAgentSpawnEnd(event)
+    }
+}
+
+impl From<CollabAgentInteractionBeginEvent> for EventMsg {
+    fn from(event: CollabAgentInteractionBeginEvent) -> Self {
+        EventMsg::CollabAgentInteractionBegin(event)
+    }
+}
+
+impl From<CollabAgentInteractionEndEvent> for EventMsg {
+    fn from(event: CollabAgentInteractionEndEvent) -> Self {
+        EventMsg::CollabAgentInteractionEnd(event)
+    }
+}
+
+impl From<CollabWaitingBeginEvent> for EventMsg {
+    fn from(event: CollabWaitingBeginEvent) -> Self {
+        EventMsg::CollabWaitingBegin(event)
+    }
+}
+
+impl From<CollabWaitingEndEvent> for EventMsg {
+    fn from(event: CollabWaitingEndEvent) -> Self {
+        EventMsg::CollabWaitingEnd(event)
+    }
+}
+
+impl From<CollabCloseBeginEvent> for EventMsg {
+    fn from(event: CollabCloseBeginEvent) -> Self {
+        EventMsg::CollabCloseBegin(event)
+    }
+}
+
+impl From<CollabCloseEndEvent> for EventMsg {
+    fn from(event: CollabCloseEndEvent) -> Self {
+        EventMsg::CollabCloseEnd(event)
+    }
 }
 
 /// Agent lifecycle status, derived from emitted events.
@@ -1110,8 +1268,19 @@ pub struct AgentMessageEvent {
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
 pub struct UserMessageEvent {
     pub message: String,
+    /// Image URLs sourced from `UserInput::Image`. These are safe
+    /// to replay in legacy UI history events and correspond to images sent to
+    /// the model.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub images: Option<Vec<String>>,
+    /// Local file paths sourced from `UserInput::LocalImage`. These are kept so
+    /// the UI can reattach images when editing history, and should not be sent
+    /// to the model or treated as API-ready URLs.
+    #[serde(default)]
+    pub local_images: Vec<std::path::PathBuf>,
+    /// UI-defined spans within `message` used to render or persist special elements.
+    #[serde(default)]
+    pub text_elements: Vec<crate::user_input::TextElement>,
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
@@ -1220,6 +1389,22 @@ pub enum InitialHistory {
 }
 
 impl InitialHistory {
+    pub fn forked_from_id(&self) -> Option<ThreadId> {
+        match self {
+            InitialHistory::New => None,
+            InitialHistory::Resumed(resumed) => {
+                resumed.history.iter().find_map(|item| match item {
+                    RolloutItem::SessionMeta(meta_line) => meta_line.meta.forked_from_id,
+                    _ => None,
+                })
+            }
+            InitialHistory::Forked(items) => items.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => Some(meta_line.meta.id),
+                _ => None,
+            }),
+        }
+    }
+
     pub fn get_rollout_items(&self) -> Vec<RolloutItem> {
         match self {
             InitialHistory::New => Vec::new(),
@@ -1303,11 +1488,12 @@ impl fmt::Display for SubAgentSource {
 #[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, TS)]
 pub struct SessionMeta {
     pub id: ThreadId,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub forked_from_id: Option<ThreadId>,
     pub timestamp: String,
     pub cwd: PathBuf,
     pub originator: String,
     pub cli_version: String,
-    pub instructions: Option<String>,
     #[serde(default)]
     pub source: SessionSource,
     pub model_provider: Option<String>,
@@ -1317,11 +1503,11 @@ impl Default for SessionMeta {
     fn default() -> Self {
         SessionMeta {
             id: ThreadId::default(),
+            forked_from_id: None,
             timestamp: String::new(),
             cwd: PathBuf::new(),
             originator: String::new(),
             cli_version: String::new(),
-            instructions: None,
             source: SessionSource::default(),
             model_provider: None,
         }
@@ -1500,21 +1686,18 @@ pub struct ReviewLineRange {
     pub end: u32,
 }
 
-#[derive(Debug, Clone, Copy, Display, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS)]
+#[derive(
+    Debug, Clone, Copy, Display, Deserialize, Serialize, PartialEq, Eq, JsonSchema, TS, Default,
+)]
 #[serde(rename_all = "snake_case")]
 pub enum ExecCommandSource {
+    #[default]
     Agent,
     UserShell,
     UnifiedExecStartup,
     UnifiedExecInteraction,
 }
 
-impl Default for ExecCommandSource {
-    fn default() -> Self {
-        Self::Agent
-    }
-}
-
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
 pub struct ExecCommandBeginEvent {
     /// Identifier so this can be paired with the ExecCommandEnd event.
@@ -1806,13 +1989,33 @@ pub enum SkillScope {
 pub struct SkillMetadata {
     pub name: String,
     pub description: String,
-    #[ts(optional)]
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[ts(optional)]
+    /// Legacy short_description from SKILL.md. Prefer SKILL.toml interface.short_description.
     pub short_description: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[ts(optional)]
+    pub interface: Option<SkillInterface>,
     pub path: PathBuf,
     pub scope: SkillScope,
 }
 
+#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS, PartialEq, Eq)]
+pub struct SkillInterface {
+    #[ts(optional)]
+    pub display_name: Option<String>,
+    #[ts(optional)]
+    pub short_description: Option<String>,
+    #[ts(optional)]
+    pub icon_small: Option<PathBuf>,
+    #[ts(optional)]
+    pub icon_large: Option<PathBuf>,
+    #[ts(optional)]
+    pub brand_color: Option<String>,
+    #[ts(optional)]
+    pub default_prompt: Option<String>,
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize, JsonSchema, TS)]
 pub struct SkillErrorInfo {
     pub path: PathBuf,
@@ -1830,6 +2033,8 @@ pub struct SkillsListEntry {
 pub struct SessionConfiguredEvent {
     /// Name left as session_id instead of thread_id for backwards compatibility.
     pub session_id: ThreadId,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub forked_from_id: Option<ThreadId>,
 
     /// Tell the client what model is being queried.
     pub model: String,
@@ -1943,6 +2148,103 @@ pub enum TurnAbortReason {
     ReviewEnded,
 }
 
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabAgentSpawnBeginEvent {
+    /// Identifier for the collab tool call.
+    pub call_id: String,
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Initial prompt sent to the agent. Can be empty to prevent CoT leaking at the
+    /// beginning.
+    pub prompt: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabAgentSpawnEndEvent {
+    /// Identifier for the collab tool call.
+    pub call_id: String,
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Thread ID of the newly spawned agent, if it was created.
+    pub new_thread_id: Option<ThreadId>,
+    /// Initial prompt sent to the agent. Can be empty to prevent CoT leaking at the
+    /// beginning.
+    pub prompt: String,
+    /// Last known status of the new agent reported to the sender agent.
+    pub status: AgentStatus,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabAgentInteractionBeginEvent {
+    /// Identifier for the collab tool call.
+    pub call_id: String,
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Thread ID of the receiver.
+    pub receiver_thread_id: ThreadId,
+    /// Prompt sent from the sender to the receiver. Can be empty to prevent CoT
+    /// leaking at the beginning.
+    pub prompt: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabAgentInteractionEndEvent {
+    /// Identifier for the collab tool call.
+    pub call_id: String,
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Thread ID of the receiver.
+    pub receiver_thread_id: ThreadId,
+    /// Prompt sent from the sender to the receiver. Can be empty to prevent CoT
+    /// leaking at the beginning.
+    pub prompt: String,
+    /// Last known status of the receiver agent reported to the sender agent.
+    pub status: AgentStatus,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabWaitingBeginEvent {
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Thread ID of the receivers.
+    pub receiver_thread_ids: Vec<ThreadId>,
+    /// ID of the waiting call.
+    pub call_id: String,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabWaitingEndEvent {
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// ID of the waiting call.
+    pub call_id: String,
+    /// Last known status of the receiver agents reported to the sender agent.
+    pub statuses: HashMap<ThreadId, AgentStatus>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabCloseBeginEvent {
+    /// Identifier for the collab tool call.
+    pub call_id: String,
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Thread ID of the receiver.
+    pub receiver_thread_id: ThreadId,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema, TS)]
+pub struct CollabCloseEndEvent {
+    /// Identifier for the collab tool call.
+    pub call_id: String,
+    /// Thread ID of the sender.
+    pub sender_thread_id: ThreadId,
+    /// Thread ID of the receiver.
+    pub receiver_thread_id: ThreadId,
+    /// Last known status of the receiver agent reported to the sender agent before
+    /// the close.
+    pub status: AgentStatus,
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2054,6 +2356,48 @@ mod tests {
         Ok(())
     }
 
+    #[test]
+    fn user_input_text_serializes_empty_text_elements() -> Result<()> {
+        let input = UserInput::Text {
+            text: "hello".to_string(),
+            text_elements: Vec::new(),
+        };
+
+        let json_input = serde_json::to_value(input)?;
+        assert_eq!(
+            json_input,
+            json!({
+                "type": "text",
+                "text": "hello",
+                "text_elements": [],
+            })
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn user_message_event_serializes_empty_metadata_vectors() -> Result<()> {
+        let event = UserMessageEvent {
+            message: "hello".to_string(),
+            images: None,
+            local_images: Vec::new(),
+            text_elements: Vec::new(),
+        };
+
+        let json_event = serde_json::to_value(event)?;
+        assert_eq!(
+            json_event,
+            json!({
+                "message": "hello",
+                "local_images": [],
+                "text_elements": [],
+            })
+        );
+
+        Ok(())
+    }
+
     /// Serialize Event to verify that its JSON representation has the expected
     /// amount of nesting.
     #[test]
@@ -2064,6 +2408,7 @@ mod tests {
             id: "1234".to_string(),
             msg: EventMsg::SessionConfigured(SessionConfiguredEvent {
                 session_id: conversation_id,
+                forked_from_id: None,
                 model: "codex-mini-latest".to_string(),
                 model_provider_id: "openai".to_string(),
                 approval_policy: AskForApproval::Never,

codex-rs/protocol/src/user_input.rs

@@ -10,17 +10,19 @@ use ts_rs::TS;
 pub enum UserInput {
     Text {
         text: String,
+        /// UI-defined spans within `text` that should be treated as special elements.
+        /// These are byte ranges into the UTF-8 `text` buffer and are used to render
+        /// or persist rich input markers (e.g., image placeholders) across history
+        /// and resume without mutating the literal text.
+        #[serde(default)]
+        text_elements: Vec<TextElement>,
     },
     /// Pre‑encoded data: URI image.
-    Image {
-        image_url: String,
-    },
+    Image { image_url: String },
 
     /// Local image path provided by the user.  This will be converted to an
     /// `Image` variant (base64 data URL) during request serialization.
-    LocalImage {
-        path: std::path::PathBuf,
-    },
+    LocalImage { path: std::path::PathBuf },
 
     /// Skill selected by the user (name + path to SKILL.md).
     Skill {
@@ -28,3 +30,28 @@ pub enum UserInput {
         path: std::path::PathBuf,
     },
 }
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, TS, JsonSchema)]
+pub struct TextElement {
+    /// Byte range in the parent `text` buffer that this element occupies.
+    pub byte_range: ByteRange,
+    /// Optional human-readable placeholder for the element, displayed in the UI.
+    pub placeholder: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq, TS, JsonSchema)]
+pub struct ByteRange {
+    /// Start byte offset (inclusive) within the UTF-8 text buffer.
+    pub start: usize,
+    /// End byte offset (exclusive) within the UTF-8 text buffer.
+    pub end: usize,
+}
+
+impl From<std::ops::Range<usize>> for ByteRange {
+    fn from(range: std::ops::Range<usize>) -> Self {
+        Self {
+            start: range.start,
+            end: range.end,
+        }
+    }
+}