fix(acp): Prevent race condition during agent switching

When switching agents, events from the OLD agent could leak into the NEW
widget before SessionConfigured was received, causing the UI to show
responses from the wrong agent.

Fix:
- Add expected_model field to ChatWidgetInit to specify expected model
- Add session_configured_received flag to ChatWidget
- Filter events in handle_codex_event() until SessionConfigured arrives
  with matching model name

Also:
- Add E2E tests for agent switch message flow
- Remove unused ClearPendingAgent event and has_pending_agent method
- Fix clippy warnings for dead code
🤖 Generated with [Nori](https://nori.ai)

Co-Authored-By: Nori <contact@tilework.tech>

Author: CSRessel

codex-rs/tui-pty-e2e/docs.md

@@ -145,7 +145,7 @@ This delay allows the PTY subprocess time to process input and update the displa
 | `@/codex-rs/tui-pty-e2e/tests/input_handling.rs` | Text editing, backspace, Ctrl-C clearing, arrow key navigation with snapshot testing |
 | `@/codex-rs/tui-pty-e2e/tests/streaming.rs` | Prompt submission with timing delays, agent response streaming |
 | `@/codex-rs/tui-pty-e2e/tests/acp_mode.rs` | ACP mode startup, response flow, and approval bridging - validates TUI works with ACP wire API and mock agent; includes test for permission request display |
-| `@/codex-rs/tui-pty-e2e/tests/agent_switching.rs` | ACP agent subprocess lifecycle - verifies subprocess spawning, cleanup on session switch, and different agents use different processes (Linux only) |
+| `@/codex-rs/tui-pty-e2e/tests/agent_switching.rs` | ACP agent subprocess lifecycle and event isolation - verifies subprocess spawning, cleanup on session switch, different agents use different processes, and event filtering prevents cross-agent contamination (Linux only) |
 | `@/codex-rs/tui-pty-e2e/tests/live_acp.rs` | Live authenticated ACP tests for Gemini and Claude with real API connections (opt-in, marked `#[ignore]`) |
 
 **Snapshot Files:**
@@ -237,7 +237,9 @@ See `@/codex-rs/mock-acp-agent/docs.md` for full list of env vars.
 
 **Agent Subprocess Lifecycle Testing (`agent_switching.rs`):**
 
-Linux-only tests that verify ACP subprocess lifecycle management by parsing the `.codex-acp.log` file for PID entries:
+Linux-only tests that verify ACP subprocess lifecycle management and event isolation:
+
+*Subprocess Management Tests:*
 - `acp_log_path()` method on `TuiSession` returns the path to the ACP tracing log file
 - Tests extract PIDs from log lines matching `"ACP agent spawned (pid: Some(...))"`
 - Uses `/proc/{pid}` filesystem to verify process existence and zombie state
@@ -248,6 +250,11 @@ Linux-only tests that verify ACP subprocess lifecycle management by parsing the
   - Cleanup happens when session switches, not when individual prompt turns end
   - Different models (`mock-model` vs `mock-model-alt`) spawn different subprocesses
 
+*Event Isolation Tests:*
+- `extract_agent_messages_from_log()` helper parses `Mock agent:` log entries from ACP log file
+- `test_agent_switch_message_flow_mock_to_mock_alt` verifies that after switching agents, the NEW agent receives and responds to prompts (catches race conditions where OLD agent events could leak)
+- `test_agent_switch_logs_correct_sequence` verifies the expected log sequence during agent switch: agent receives prompt, logs receipt, sends response
+
 **Binary Discovery:**
 
 `codex_binary_path()` locates the compiled binary:

codex-rs/tui-pty-e2e/tests/agent_switching.rs

@@ -707,3 +707,244 @@ fn test_agent_cleanup_after_switch_on_prompt() {
         initial_pid
     );
 }
+
+// ============================================================================
+// Test: Agent Switch Message Flow - Verifies NEW agent receives and responds
+// ============================================================================
+
+/// Helper to extract agent messages from log file
+/// Each mock agent logs to stderr which is captured in the ACP log
+fn extract_agent_messages_from_log(log_path: &std::path::Path) -> Vec<String> {
+    std::fs::read_to_string(log_path)
+        .unwrap_or_default()
+        .lines()
+        .filter(|line| {
+            line.contains("Mock agent:")
+                || line.contains("cancel")
+                || line.contains("shutdown")
+                || line.contains("prompt")
+        })
+        .map(|s| s.to_string())
+        .collect()
+}
+
+/// Test that when switching agents via /agent command, the NEW agent
+/// correctly receives and responds to the submitted prompt.
+///
+/// This test explicitly verifies the message flow:
+/// 1. OLD agent should receive a cancel/shutdown signal
+/// 2. NEW agent should receive a new_session request
+/// 3. NEW agent should receive the prompt and respond
+/// 4. Response from NEW agent appears on screen
+///
+/// This catches the race condition bug where events from the OLD agent
+/// could leak into the NEW widget, causing the prompt to be lost.
+#[test]
+#[cfg(target_os = "linux")]
+fn test_agent_switch_message_flow_mock_to_mock_alt() {
+    // Use default response (Test message 1/2) - both agents will use this
+    let config = SessionConfig::new().with_model("mock-model".to_string());
+
+    let mut session = TuiSession::spawn_with_config(24, 80, config).expect("Failed to spawn TUI");
+
+    session
+        .wait_for_text("›", TIMEOUT)
+        .expect("TUI should start");
+    std::thread::sleep(TIMEOUT_INPUT);
+
+    let log_path = session.acp_log_path().expect("Should have log path");
+
+    // First, verify initial agent works - send a prompt
+    session.send_str("test initial").unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+
+    // Wait for initial agent response (default response)
+    session
+        .wait_for_text("Test message", Duration::from_secs(5))
+        .expect("Initial agent should respond");
+
+    // Log messages before switch
+    let msgs_before_switch = extract_agent_messages_from_log(&log_path);
+    eprintln!("Messages before switch: {:?}", msgs_before_switch);
+
+    // Open agent picker with /agent command
+    session.send_str("/agent").unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+
+    // Wait for agent picker to appear
+    session
+        .wait_for(
+            |screen| screen.contains("Select Agent") || screen.contains("mock-model"),
+            Duration::from_secs(3),
+        )
+        .expect("Agent picker should appear");
+
+    // Select mock-model-alt (different agent)
+    session.send_key(Key::Down).unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+    std::thread::sleep(Duration::from_millis(500));
+
+    // Messages after selection (but before prompt submission)
+    let msgs_after_selection = extract_agent_messages_from_log(&log_path);
+    eprintln!("Messages after selection: {:?}", msgs_after_selection);
+
+    // Now submit a prompt - this should trigger the actual agent switch
+    // The NEW agent (mock-model-alt) should receive this prompt and respond
+    session.send_str("test after switch").unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+
+    // Wait for the NEW agent's response to appear.
+    // The key verification: we should see TWO instances of "Test message" -
+    // one from the first prompt, and one from the second prompt after switch.
+    // If the switch fails, the second response won't appear.
+    std::thread::sleep(Duration::from_secs(3)); // Give time for response
+
+    // Log messages after prompt submission
+    let msgs_after_prompt = extract_agent_messages_from_log(&log_path);
+    eprintln!("Messages after prompt submission: {:?}", msgs_after_prompt);
+
+    // Verify we got two prompt calls (one before switch, one after)
+    let prompt_count = msgs_after_prompt
+        .iter()
+        .filter(|m| m.contains("Mock agent: prompt"))
+        .count();
+
+    if prompt_count < 2 {
+        let screen = session.screen_contents();
+        panic!(
+            "Expected 2 prompt calls (before and after switch), got {}.\n\
+             Screen contents: {}\n\
+             Agent messages in log: {:?}",
+            prompt_count, screen, msgs_after_prompt
+        );
+    }
+
+    // Verify message flow in logs:
+    // 1. Should see "Mock agent: new_session" for the NEW agent
+    // 2. Should see "Mock agent: prompt" for the NEW agent
+    let has_new_session = msgs_after_prompt
+        .iter()
+        .filter(|m| m.contains("new_session"))
+        .count()
+        >= 2; // Initial + after switch
+
+    assert!(
+        has_new_session,
+        "Should have new_session calls for both agents, messages: {:?}",
+        msgs_after_prompt
+    );
+    assert!(
+        prompt_count >= 2,
+        "Should have prompt calls for both agents, messages: {:?}",
+        msgs_after_prompt
+    );
+
+    // Final verification: the screen should show response content
+    let screen = session.screen_contents();
+    assert!(
+        screen.contains("Test message"),
+        "Screen should contain response text. Screen:\n{}",
+        screen
+    );
+}
+
+/// Test that verifies the expected sequence of operations when switching agents
+/// This is a more focused test that checks specific message ordering
+#[test]
+#[cfg(target_os = "linux")]
+fn test_agent_switch_logs_correct_sequence() {
+    let config = SessionConfig::new().with_model("mock-model".to_string());
+
+    let mut session = TuiSession::spawn_with_config(24, 80, config).expect("Failed to spawn TUI");
+
+    session
+        .wait_for_text("›", TIMEOUT)
+        .expect("TUI should start");
+    std::thread::sleep(TIMEOUT_INPUT);
+
+    let log_path = session.acp_log_path().expect("Should have log path");
+    let initial_pids = extract_mock_agent_pids_from_log(&log_path);
+    assert!(!initial_pids.is_empty(), "Should have initial PID");
+
+    // Select new agent via /agent
+    session.send_str("/agent").unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+
+    session
+        .wait_for(
+            |screen| screen.contains("Select Agent"),
+            Duration::from_secs(3),
+        )
+        .expect("Agent picker should appear");
+
+    session.send_key(Key::Down).unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+    std::thread::sleep(Duration::from_millis(300));
+
+    // Submit prompt to trigger switch
+    session.send_str("trigger").unwrap();
+    std::thread::sleep(TIMEOUT_INPUT);
+    session.send_key(Key::Enter).unwrap();
+
+    // Wait for response
+    session
+        .wait_for_text("Test message", Duration::from_secs(10))
+        .expect("Should see response from new agent");
+
+    // Parse the log to verify sequence
+    let log_content = std::fs::read_to_string(&log_path).unwrap_or_default();
+
+    // Count agent spawns - should be 2 (initial + after switch)
+    let spawn_count = log_content
+        .lines()
+        .filter(|l| l.contains("ACP agent spawned"))
+        .count();
+
+    assert!(
+        spawn_count >= 2,
+        "Should spawn at least 2 agents (initial + after switch), got: {}. Log:\n{}",
+        spawn_count,
+        log_content
+    );
+
+    // Verify new_session and prompt sequence
+    let agent_messages: Vec<&str> = log_content
+        .lines()
+        .filter(|l| l.contains("Mock agent:"))
+        .collect();
+
+    eprintln!("Agent message sequence:");
+    for (i, msg) in agent_messages.iter().enumerate() {
+        eprintln!("  {}: {}", i, msg);
+    }
+
+    // Should have: initialize, new_session, prompt (first agent)
+    // Then: initialize, new_session, prompt (second agent)
+    let new_session_count = agent_messages
+        .iter()
+        .filter(|m| m.contains("new_session"))
+        .count();
+    let prompt_count = agent_messages
+        .iter()
+        .filter(|m| m.contains("prompt"))
+        .count();
+
+    assert!(
+        new_session_count >= 2,
+        "Should have at least 2 new_session calls, got: {}",
+        new_session_count
+    );
+    assert!(
+        prompt_count >= 1,
+        "Should have at least 1 prompt call, got: {}",
+        prompt_count
+    );
+}

codex-rs/tui/docs.md

@@ -122,6 +122,19 @@ Most event types (exec begin/end, MCP calls, elicitation) are queued during acti
 - The `InterruptManager` still contains `ExecApproval` and `ApplyPatchApproval` variants for completeness, but these methods are marked `#[allow(dead_code)]`
 - `on_task_complete()` calls `flush_interrupt_queue()` for any remaining queued items
 
+**Agent Switch Event Filtering:**
+
+When switching between ACP agents (e.g., via `/agent` command), `ChatWidget` uses an event filtering mechanism to prevent race conditions:
+
+- `expected_model: Option<String>` in `ChatWidgetInit` specifies which model the widget expects
+- `session_configured_received: bool` tracks whether `SessionConfigured` has arrived from the expected model
+- When `expected_model` is set, `handle_codex_event()` filters events:
+  - All events are ignored until `SessionConfigured` arrives
+  - `SessionConfigured` is only accepted if `event.model` matches `expected_model` (case-insensitive)
+  - Once matching `SessionConfigured` arrives, `session_configured_received` is set to `true` and normal event processing resumes
+- This prevents the OLD agent's final events (completion, shutdown) from being processed by the NEW agent's widget
+- Fresh sessions, resumed sessions, and `/new` command use `expected_model: None` (no filtering)
+
 **Color System:**
 
 The `color.rs` and `terminal_palette.rs` modules handle terminal color detection and theming. The app queries terminal colors at startup for theme adaptation.

codex-rs/tui/src/app.rs

@@ -10,6 +10,7 @@ use crate::history_cell::HistoryCell;
 use crate::model_migration::ModelMigrationOutcome;
 use crate::model_migration::migration_copy_for_config;
 use crate::model_migration::run_model_migration_prompt;
+use crate::nori::agent_picker::PendingAgentSelection;
 use crate::pager_overlay::Overlay;
 use crate::render::highlight::highlight_bash_to_lines;
 use crate::render::renderable::Renderable;
@@ -234,15 +235,6 @@ pub(crate) struct App {
     pending_agent: Option<PendingAgentSelection>,
 }
 
-/// Information about a pending agent switch.
-#[derive(Debug, Clone)]
-pub(crate) struct PendingAgentSelection {
-    /// The model name of the selected agent (e.g., "mock-model", "gemini-2.5-flash")
-    pub model_name: String,
-    /// The display name for the status indicator
-    pub display_name: String,
-}
-
 impl App {
     async fn shutdown_current_conversation(&mut self) {
         if let Some(conversation_id) = self.chat_widget.conversation_id() {
@@ -307,6 +299,7 @@ impl App {
                     enhanced_keys_supported,
                     auth_manager: auth_manager.clone(),
                     feedback: feedback.clone(),
+                    expected_model: None, // No filtering for fresh sessions
                 };
                 ChatWidget::new(init, conversation_manager.clone())
             }
@@ -330,6 +323,7 @@ impl App {
                     enhanced_keys_supported,
                     auth_manager: auth_manager.clone(),
                     feedback: feedback.clone(),
+                    expected_model: None, // No filtering for resumed sessions
                 };
                 ChatWidget::new_from_existing(
                     init,
@@ -484,6 +478,7 @@ impl App {
                     enhanced_keys_supported: self.enhanced_keys_supported,
                     auth_manager: self.auth_manager.clone(),
                     feedback: self.feedback.clone(),
+                    expected_model: None, // No filtering for /new command
                 };
                 self.chat_widget = ChatWidget::new(init, self.server.clone());
                 if let Some(summary) = summary {
@@ -916,19 +911,11 @@ impl App {
                 );
                 self.chat_widget.add_info_message(
                     format!(
-                        "Agent '{}' selected. Will switch on next prompt submission.",
-                        display_name
+                        "Agent '{display_name}' selected. Will switch on next prompt submission."
                     ),
                     None,
                 );
             }
-            AppEvent::ClearPendingAgent => {
-                if self.pending_agent.is_some() {
-                    tracing::info!("Pending agent selection cleared");
-                    self.pending_agent = None;
-                    self.chat_widget.clear_pending_agent();
-                }
-            }
             AppEvent::SubmitWithAgentSwitch {
                 model_name,
                 display_name,
@@ -951,6 +938,7 @@ impl App {
                 self.shutdown_current_conversation().await;
 
                 // Create the new chat widget with the new config and the message as initial prompt
+                // Set expected_model to filter events from the OLD agent until SessionConfigured
                 let init = crate::chatwidget::ChatWidgetInit {
                     config: self.config.clone(),
                     frame_requester: tui.frame_requester(),
@@ -960,13 +948,12 @@ impl App {
                     enhanced_keys_supported: self.enhanced_keys_supported,
                     auth_manager: self.auth_manager.clone(),
                     feedback: self.feedback.clone(),
+                    expected_model: Some(model_name.clone()),
                 };
                 self.chat_widget = ChatWidget::new(init, self.server.clone());
 
-                self.chat_widget.add_info_message(
-                    format!("Switched to agent: {}", display_name),
-                    None,
-                );
+                self.chat_widget
+                    .add_info_message(format!("Switched to agent: {display_name}"), None);
             }
         }
         Ok(true)

codex-rs/tui/src/app_backtrack.rs

@@ -347,6 +347,7 @@ impl App {
             enhanced_keys_supported: self.enhanced_keys_supported,
             auth_manager: self.auth_manager.clone(),
             feedback: self.feedback.clone(),
+            expected_model: None, // No filtering for backtracked conversations
         };
         self.chat_widget =
             crate::chatwidget::ChatWidget::new_from_existing(init, conv, session_configured);