extension-api: add TurnItemEmitter to tool calls (#24813)

## Why
Extension-contributed tools need to emit visible turn items through
Codex's normal event and persistence pipeline.

## What
- Add `TurnItemEmitter` to extension `ToolCall`s and route the core
implementation through `Session::emit_turn_item_*`.
- Hold weak session and turn references so retained tool calls cannot
keep host state alive.
- Provide a no-op emitter for extension test callers.

## Test Plan
- `just test -p codex-core -E
'test(passes_turn_fields_and_scoped_turn_item_emitter_to_extension_call)'`

---------

Co-authored-by: jif-oai <jif@openai.com>

codex-rs/tools/src/lib.rs

@@ -62,7 +62,11 @@ pub use responses_api::mcp_tool_to_deferred_responses_api_tool;
 pub use responses_api::mcp_tool_to_responses_api_tool;
 pub use responses_api::tool_definition_to_responses_api_tool;
 pub use tool_call::ConversationHistory;
+pub use tool_call::ExtensionTurnItem;
+pub use tool_call::NoopTurnItemEmitter;
 pub use tool_call::ToolCall;
+pub use tool_call::TurnItemEmissionFuture;
+pub use tool_call::TurnItemEmitter;
 pub use tool_config::ShellCommandBackendConfig;
 pub use tool_config::ToolEnvironmentMode;
 pub use tool_config::ToolUserShellType;

codex-rs/tools/src/tool_call.rs

@@ -1,8 +1,11 @@
 use crate::FunctionCallError;
 use crate::ToolName;
 use crate::ToolPayload;
+use codex_protocol::items::WebSearchItem;
 use codex_protocol::models::ResponseItem;
 use codex_utils_output_truncation::TruncationPolicy;
+use std::future::Future;
+use std::pin::Pin;
 use std::sync::Arc;
 
 /// Raw response history snapshot available when an extension tool is invoked.
@@ -23,17 +26,70 @@ impl ConversationHistory {
     }
 }
 
+/// Future returned when an extension tool emits a visible turn-item lifecycle event.
+pub type TurnItemEmissionFuture<'a> = Pin<Box<dyn Future<Output = ()> + Send + 'a>>;
+
+/// Visible turn items that an extension fully owns and may emit as-is.
+///
+/// Add only item kinds that require no additional host finalization before
+/// persistence or client delivery. Richer items need a host-owned publish path.
+#[derive(Clone, Debug, PartialEq)]
+pub enum ExtensionTurnItem {
+    WebSearch(WebSearchItem),
+}
+
+/// Host-provided capability for extension tools to emit finalized visible turn items.
+///
+/// Implementations route lifecycle events through the host's normal item event
+/// pipeline, including any persistence and client delivery owned by the host.
+pub trait TurnItemEmitter: Send + Sync {
+    /// Emits the beginning of one visible turn item.
+    fn emit_started<'a>(&'a self, item: ExtensionTurnItem) -> TurnItemEmissionFuture<'a>;
+
+    /// Emits the completion of one visible turn item.
+    fn emit_completed<'a>(&'a self, item: ExtensionTurnItem) -> TurnItemEmissionFuture<'a>;
+}
+
+/// Turn-item emitter used when a caller does not expose visible item emission.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct NoopTurnItemEmitter;
+
+impl TurnItemEmitter for NoopTurnItemEmitter {
+    fn emit_started<'a>(&'a self, _item: ExtensionTurnItem) -> TurnItemEmissionFuture<'a> {
+        Box::pin(std::future::ready(()))
+    }
+
+    fn emit_completed<'a>(&'a self, _item: ExtensionTurnItem) -> TurnItemEmissionFuture<'a> {
+        Box::pin(std::future::ready(()))
+    }
+}
+
 // TODO: this is temporary and will disappear in the next PR (as we make codex-extension-api generic on Invocation.
-#[derive(Clone, Debug)]
+#[derive(Clone)]
 pub struct ToolCall {
     pub turn_id: String,
     pub call_id: String,
     pub tool_name: ToolName,
     pub truncation_policy: TruncationPolicy,
     pub conversation_history: ConversationHistory,
+    pub turn_item_emitter: Arc<dyn TurnItemEmitter>,
     pub payload: ToolPayload,
 }
 
+impl std::fmt::Debug for ToolCall {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ToolCall")
+            .field("turn_id", &self.turn_id)
+            .field("call_id", &self.call_id)
+            .field("tool_name", &self.tool_name)
+            .field("truncation_policy", &self.truncation_policy)
+            .field("conversation_history", &self.conversation_history)
+            .field("turn_item_emitter", &"<host turn item emitter>")
+            .field("payload", &self.payload)
+            .finish()
+    }
+}
+
 impl ToolCall {
     pub fn function_arguments(&self) -> Result<&str, FunctionCallError> {
         match &self.payload {