feat: guardian as an extension (contributors part) (#22216)

Part 1 of guardian as extension. This bind all the logic to spawn
another agent from an extension and it adds `ThreadId` in the start
thread collaborator

codex-rs/ext/extension-api/src/capabilities/agent.rs

@@ -0,0 +1,38 @@
+use std::future::Future;
+use std::pin::Pin;
+
+use codex_protocol::ThreadId;
+
+/// Future returned by one injected subagent-spawn helper.
+pub type AgentSpawnFuture<'a, T, E> = Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>>;
+
+/// Constructor-injected host helper for extensions that need to spawn subagents.
+///
+/// The extension owns the request shape and resulting handle types. The host
+/// provides the implementation when it constructs the extension.
+pub trait AgentSpawner<R>: Send + Sync {
+    type Spawned;
+    type Error;
+
+    fn spawn_subagent<'a>(
+        &'a self,
+        forked_from_thread_id: ThreadId,
+        request: R,
+    ) -> AgentSpawnFuture<'a, Self::Spawned, Self::Error>;
+}
+
+impl<R, S, E, F> AgentSpawner<R> for F
+where
+    F: Fn(ThreadId, R) -> AgentSpawnFuture<'static, S, E> + Send + Sync,
+{
+    type Spawned = S;
+    type Error = E;
+
+    fn spawn_subagent<'a>(
+        &'a self,
+        forked_from_thread_id: ThreadId,
+        request: R,
+    ) -> AgentSpawnFuture<'a, Self::Spawned, Self::Error> {
+        self(forked_from_thread_id, request)
+    }
+}

codex-rs/ext/extension-api/src/capabilities/mod.rs

@@ -0,0 +1,4 @@
+mod agent;
+
+pub use agent::AgentSpawnFuture;
+pub use agent::AgentSpawner;

codex-rs/ext/extension-api/src/contributors.rs

@@ -1,5 +1,6 @@
 use std::future::Future;
 
+use codex_protocol::ThreadId;
 use codex_protocol::items::TurnItem;
 use codex_tool_api::ToolBundle;
 
@@ -10,10 +11,16 @@ mod prompt;
 pub use prompt::PromptFragment;
 pub use prompt::PromptSlot;
 
-/// Contributor that receives host-owned thread-start input before later
-/// contributors read from extension stores.
+/// Contributor that receives the live thread id and host-owned thread-start
+/// input before later contributors read from extension stores.
 pub trait ThreadStartContributor<C>: Send + Sync {
-    fn contribute(&self, input: &C, session_store: &ExtensionData, thread_store: &ExtensionData);
+    fn contribute(
+        &self,
+        thread_id: ThreadId,
+        input: &C,
+        session_store: &ExtensionData,
+        thread_store: &ExtensionData,
+    );
 }
 
 /// Extension contribution that adds prompt fragments during prompt assembly.

codex-rs/ext/extension-api/src/lib.rs

@@ -1,7 +1,10 @@
+mod capabilities;
 mod contributors;
 mod registry;
 mod state;
 
+pub use capabilities::AgentSpawnFuture;
+pub use capabilities::AgentSpawner;
 pub use codex_tool_api::FunctionToolSpec;
 pub use codex_tool_api::ToolBundle;
 pub use codex_tool_api::ToolCall;