Preserve assistant phase for replayed messages

ResponseInputItem::Message can contain assistant-authored history that is later converted into ResponseItem::Message. Preserve phase across that boundary instead of inferring phase from message content.

InterAgentCommunication::to_response_input_item records inter-agent mailbox messages as commentary because they are assistant-authored in-between updates, not completed final answers.

This follows the assistant phase guidance in https://developers.openai.com/api/docs/guides/deployment-checklist#set-up-the-assistant-phase-parameter.

Co-authored-by: Codex <noreply@openai.com>

Author: friel-openai

codex-rs/core/src/codex_thread.rs

@@ -437,9 +437,15 @@ impl CodexThread {
 
 fn pending_message_input_item(message: &ResponseItem) -> CodexResult<ResponseInputItem> {
     match message {
-        ResponseItem::Message { role, content, .. } => Ok(ResponseInputItem::Message {
+        ResponseItem::Message {
+            role,
+            content,
+            phase,
+            ..
+        } => Ok(ResponseInputItem::Message {
             role: role.clone(),
             content: content.clone(),
+            phase: phase.clone(),
         }),
         _ => Err(CodexErr::InvalidRequest(
             "append_message only supports ResponseItem::Message".to_string(),

codex-rs/core/src/goals.rs

@@ -1307,6 +1307,7 @@ impl Session {
                 content: vec![ContentItem::InputText {
                     text: continuation_prompt(&goal),
                 }],
+                phase: None,
             }],
         })
     }
@@ -1452,6 +1453,7 @@ fn budget_limit_steering_item(goal: &ThreadGoal) -> ResponseInputItem {
         content: vec![ContentItem::InputText {
             text: budget_limit_prompt(goal),
         }],
+        phase: None,
     }
 }
 

codex-rs/core/src/session/handlers.rs

@@ -1270,6 +1270,7 @@ Approved action:
     let items = vec![ResponseInputItem::Message {
         role: "developer".to_string(),
         content: vec![ContentItem::InputText { text }],
+        phase: None,
     }];
 
     if let Err(items) = sess.inject_response_items(items).await {

codex-rs/core/src/session/mod.rs

@@ -1687,6 +1687,7 @@ impl Session {
             .inject_response_items(vec![ResponseInputItem::Message {
                 role: "developer".to_string(),
                 content: vec![ContentItem::InputText { text }],
+                phase: None,
             }])
             .await
             .is_err()
@@ -1783,6 +1784,7 @@ impl Session {
             .inject_response_items(vec![ResponseInputItem::Message {
                 role: "developer".to_string(),
                 content: vec![ContentItem::InputText { text }],
+                phase: None,
             }])
             .await
             .is_err()

codex-rs/core/src/session/tests.rs

@@ -6250,6 +6250,7 @@ async fn task_finish_emits_turn_item_lifecycle_for_leftover_pending_user_input()
         content: vec![ContentItem::InputText {
             text: "late pending input".to_string(),
         }],
+        phase: None,
     }])
     .await
     .expect("inject pending input into active turn");
@@ -6495,18 +6496,21 @@ async fn prepend_pending_input_keeps_older_tail_ahead_of_newer_input() {
         content: vec![ContentItem::InputText {
             text: "blocked queued prompt".to_string(),
         }],
+        phase: None,
     };
     let later = ResponseInputItem::Message {
         role: "user".to_string(),
         content: vec![ContentItem::InputText {
             text: "later queued prompt".to_string(),
         }],
+        phase: None,
     };
     let newer = ResponseInputItem::Message {
         role: "user".to_string(),
         content: vec![ContentItem::InputText {
             text: "newer queued prompt".to_string(),
         }],
+        phase: None,
     };
 
     sess.inject_response_items(vec![blocked.clone(), later.clone()])
@@ -6537,6 +6541,7 @@ async fn queued_response_items_for_next_turn_move_into_next_active_turn() {
         content: vec![ContentItem::InputText {
             text: "queued before wake".to_string(),
         }],
+        phase: None,
     };
 
     sess.queue_response_items_for_next_turn(vec![queued_item.clone()])
@@ -6563,6 +6568,7 @@ async fn idle_interrupt_does_not_wake_queued_next_turn_items() {
         content: vec![ContentItem::InputText {
             text: "queued before interrupt".to_string(),
         }],
+        phase: None,
     };
 
     sess.queue_response_items_for_next_turn(vec![queued_item])
@@ -6582,6 +6588,7 @@ async fn abort_empty_active_turn_preserves_pending_input() {
         content: vec![ContentItem::InputText {
             text: "late pending input".to_string(),
         }],
+        phase: None,
     };
     let turn_state = {
         let mut active = sess.active_turn.lock().await;
@@ -6787,7 +6794,7 @@ async fn budget_limited_accounting_steers_active_turn_without_aborting() -> anyh
     .await?;
 
     let pending_input = sess.get_pending_input().await;
-    let [ResponseInputItem::Message { role, content }] = pending_input.as_slice() else {
+    let [ResponseInputItem::Message { role, content, .. }] = pending_input.as_slice() else {
         panic!("expected one budget-limit steering message, got {pending_input:#?}");
     };
     assert_eq!("developer", role);

codex-rs/core/src/tasks/user_shell.rs

@@ -354,7 +354,16 @@ async fn persist_user_shell_output(
     }
 
     let response_input_item = match output_item {
-        ResponseItem::Message { role, content, .. } => ResponseInputItem::Message { role, content },
+        ResponseItem::Message {
+            role,
+            content,
+            phase,
+            ..
+        } => ResponseInputItem::Message {
+            role,
+            content,
+            phase,
+        },
         _ => unreachable!("user shell command output record should always be a message"),
     };
 

codex-rs/protocol/src/models.rs

@@ -675,6 +675,9 @@ pub enum ResponseInputItem {
     Message {
         role: String,
         content: Vec<ContentItem>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        #[ts(optional)]
+        phase: Option<MessagePhase>,
     },
     FunctionCallOutput {
         call_id: String,
@@ -1106,11 +1109,15 @@ pub fn local_image_content_items_with_label_number(
 impl From<ResponseInputItem> for ResponseItem {
     fn from(item: ResponseInputItem) -> Self {
         match item {
-            ResponseInputItem::Message { role, content } => Self::Message {
+            ResponseInputItem::Message {
+                role,
+                content,
+                phase,
+            } => Self::Message {
                 role,
                 content,
                 id: None,
-                phase: None,
+                phase,
             },
             ResponseInputItem::FunctionCallOutput { call_id, output } => {
                 Self::FunctionCallOutput { call_id, output }
@@ -1248,6 +1255,7 @@ impl From<Vec<UserInput>> for ResponseInputItem {
                     UserInput::Skill { .. } | UserInput::Mention { .. } => Vec::new(), // Tool bodies are injected later in core
                 })
                 .collect::<Vec<ContentItem>>(),
+            phase: None,
         }
     }
 }
@@ -1652,6 +1660,29 @@ mod tests {
     use pretty_assertions::assert_eq;
     use tempfile::tempdir;
 
+    #[test]
+    fn response_input_message_conversion_preserves_phase() {
+        let item = ResponseItem::from(ResponseInputItem::Message {
+            role: "assistant".to_string(),
+            content: vec![ContentItem::OutputText {
+                text: "still working".to_string(),
+            }],
+            phase: Some(MessagePhase::Commentary),
+        });
+
+        assert_eq!(
+            item,
+            ResponseItem::Message {
+                id: None,
+                role: "assistant".to_string(),
+                content: vec![ContentItem::OutputText {
+                    text: "still working".to_string(),
+                }],
+                phase: Some(MessagePhase::Commentary),
+            }
+        );
+    }
+
     #[test]
     fn sandbox_permissions_helpers_match_documented_semantics() {
         let cases = [

codex-rs/protocol/src/protocol.rs

@@ -858,6 +858,7 @@ impl InterAgentCommunication {
             content: vec![ContentItem::OutputText {
                 text: serde_json::to_string(self).unwrap_or_default(),
             }],
+            phase: Some(MessagePhase::Commentary),
         }
     }