feat: pass codex thread ID in notifier metadata (#4582)

codex-rs/core/src/codex.rs

@@ -1858,6 +1858,7 @@ pub(crate) async fn run_task(
                     );
                     sess.notifier()
                         .notify(&UserNotification::AgentTurnComplete {
+                            thread_id: sess.conversation_id.to_string(),
                             turn_id: sub_id.clone(),
                             input_messages: turn_input_messages,
                             last_assistant_message: last_agent_message.clone(),

codex-rs/core/src/user_notification.rs

@@ -49,6 +49,7 @@ impl UserNotifier {
 pub(crate) enum UserNotification {
     #[serde(rename_all = "kebab-case")]
     AgentTurnComplete {
+        thread_id: String,
         turn_id: String,
 
         /// Messages that the user sent to the agent to initiate the turn.
@@ -67,6 +68,7 @@ mod tests {
     #[test]
     fn test_user_notification() -> Result<()> {
         let notification = UserNotification::AgentTurnComplete {
+            thread_id: "b5f6c1c2-1111-2222-3333-444455556666".to_string(),
             turn_id: "12345".to_string(),
             input_messages: vec!["Rename `foo` to `bar` and update the callsites.".to_string()],
             last_assistant_message: Some(
@@ -76,7 +78,7 @@ mod tests {
         let serialized = serde_json::to_string(&notification)?;
         assert_eq!(
             serialized,
-            r#"{"type":"agent-turn-complete","turn-id":"12345","input-messages":["Rename `foo` to `bar` and update the callsites."],"last-assistant-message":"Rename complete and verified `cargo build` succeeds."}"#
+            r#"{"type":"agent-turn-complete","thread-id":"b5f6c1c2-1111-2222-3333-444455556666","turn-id":"12345","input-messages":["Rename `foo` to `bar` and update the callsites."],"last-assistant-message":"Rename complete and verified `cargo build` succeeds."}"#
         );
         Ok(())
     }

docs/config.md

@@ -602,6 +602,7 @@ Specify a program that will be executed to get notified about events generated b
 ```json
 {
   "type": "agent-turn-complete",
+  "thread-id": "b5f6c1c2-1111-2222-3333-444455556666",
   "turn-id": "12345",
   "input-messages": ["Rename `foo` to `bar` and update the callsites."],
   "last-assistant-message": "Rename complete and verified `cargo build` succeeds."
@@ -610,6 +611,8 @@ Specify a program that will be executed to get notified about events generated b
 
 The `"type"` property will always be set. Currently, `"agent-turn-complete"` is the only notification type that is supported.
 
+`"thread-id"` contains a string that identifies the Codex session that produced the notification; you can use it to correlate multiple turns that belong to the same task.
+
 As an example, here is a Python script that parses the JSON and decides whether to show a desktop push notification using [terminal-notifier](https://github.com/julienXX/terminal-notifier) on macOS:
 
 ```python
@@ -644,6 +647,8 @@ def main() -> int:
             print(f"not sending a push notification for: {notification_type}")
             return 0
 
+    thread_id = notification.get("thread-id", "")
+
     subprocess.check_output(
         [
             "terminal-notifier",
@@ -652,7 +657,7 @@ def main() -> int:
             "-message",
             message,
             "-group",
-            "codex",
+            "codex-" + thread_id,
             "-ignoreDnD",
             "-activate",
             "com.googlecode.iterm2",