Lightweight coding agent that runs in your terminal
Rust
Add turn trigger metadata (#40665)
pakrym-oai538900ee769f
diff --git a/codex-rs/app-server-protocol/schema/json/ClientRequest.json b/codex-rs/app-server-protocol/schema/json/ClientRequest.jsonindex ec5e3b67bd..9911cd1c52 100644--- a/codex-rs/app-server-protocol/schema/json/ClientRequest.json+++ b/codex-rs/app-server-protocol/schema/json/ClientRequest.json@@ -5266,6 +5266,13 @@},"threadId": {"type": "string"+ },+ "turnTrigger": {+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",+ "type": [+ "string",+ "null"+ ]}},"required": [diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.jsonindex 780cdf059b..d32a69565c 100644--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json@@ -23959,6 +23959,13 @@},"threadId": {"type": "string"+ },+ "turnTrigger": {+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",+ "type": [+ "string",+ "null"+ ]}},"required": [diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.jsonindex 79fed91877..e70fa88d12 100644--- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json+++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json@@ -21694,6 +21694,13 @@},"threadId": {"type": "string"+ },+ "turnTrigger": {+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",+ "type": [+ "string",+ "null"+ ]}},"required": [diff --git a/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json b/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.jsonindex 197bdeff8c..96327a5cf6 100644--- a/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json+++ b/codex-rs/app-server-protocol/schema/json/v2/TurnStartParams.json@@ -675,6 +675,13 @@},"threadId": {"type": "string"+ },+ "turnTrigger": {+ "description": "Optional source classification for the caller that starts this turn. Ignored when this request steers an already-active turn.",+ "type": [+ "string",+ "null"+ ]}},"required": [diff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zstindex b40f3eca94..570c8718d2 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-experimental.json.zst differdiff --git a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zstindex a134b06aec..f764283be1 100644Binary files a/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst and b/codex-rs/app-server-protocol/schema/precomputed/app-server-exports-stable.json.zst differdiff --git a/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts b/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.tsindex 7bccf79043..785ca22750 100644--- a/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts+++ b/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartParams.ts@@ -11,6 +11,10 @@ import type { SandboxPolicy } from "./SandboxPolicy";import type { UserInput } from "./UserInput";export type TurnStartParams = {threadId: string, clientUserMessageId?: string | null, input: Array<UserInput>, /**+ * Optional source classification for the caller that starts this turn.+ * Ignored when this request steers an already-active turn.+ */+turnTrigger?: string | null, /*** Override the working directory for this turn and subsequent turns.*/cwd?: string | null, /**diff --git a/codex-rs/app-server-protocol/src/protocol/v2/tests.rs b/codex-rs/app-server-protocol/src/protocol/v2/tests.rsindex 309196dd1c..491b882941 100644--- a/codex-rs/app-server-protocol/src/protocol/v2/tests.rs+++ b/codex-rs/app-server-protocol/src/protocol/v2/tests.rs@@ -4714,6 +4714,7 @@ fn turn_start_params_preserve_explicit_null_service_tier() {thread_id: "thread_123".to_string(),client_user_message_id: None,input: vec![],+ turn_trigger: None,responsesapi_client_metadata: None,additional_context: None,environments: None,diff --git a/codex-rs/app-server-protocol/src/protocol/v2/turn.rs b/codex-rs/app-server-protocol/src/protocol/v2/turn.rsindex b1763095e7..6778748814 100644--- a/codex-rs/app-server-protocol/src/protocol/v2/turn.rs+++ b/codex-rs/app-server-protocol/src/protocol/v2/turn.rs@@ -121,6 +121,10 @@ pub struct TurnStartParams {#[ts(optional = nullable)]pub client_user_message_id: Option<String>,pub input: Vec<UserInput>,+ /// Optional source classification for the caller that starts this turn.+ /// Ignored when this request steers an already-active turn.+ #[ts(optional = nullable)]+ pub turn_trigger: Option<String>,/// Optional metadata to enrich Codex's ResponsesAPI turn metadata.////// Entries are flattened into the JSON string sent asdiff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.mdindex 5734d53446..993f0fa910 100644--- a/codex-rs/app-server/README.md+++ b/codex-rs/app-server/README.md@@ -209,7 +209,7 @@ Example with notification opt-out:- `thread/backgroundTerminals/terminate` — terminate one running background terminal by app-server `processId` (experimental; requires `capabilities.experimentalApi`); returns whether a process was terminated.- `thread/rollback` — deprecated and will be removed soon. Drop the last N turns from the agent’s in-memory context and persist a rollback marker in the rollout so future resumes see the pruned history; returns the updated `thread` (with `turns` populated) on success. Paginated threads do not support rollback. Parent-owned Multi-Agent V2 subagents reject direct rollback requests.- `thread/revert` — experimental. Replace a loaded paginated thread's durable history with the prefix strictly before `beforeTurnId` while preserving its thread id. The operation interrupts an active turn if needed, leaves older rollout files immutable, reloads the thread, returns updated thread metadata with empty `turns` plus pagination cursors, and emits `thread/reverted`. It does not revert local file changes. Parent-owned Multi-Agent V2 subagents reject direct revert requests.-- `turn/start` — add user input to a thread and begin Codex generation; responds with the initial `turn` object and streams `turn/started`, `item/*`, and `turn/completed` notifications. `clientUserMessageId` is optional; when supplied, the corresponding `userMessage` item echoes it as `clientId`. Experimental `runtimeWorkspaceRoots` supplies the default roots for newly resolved environment selections. Explicit `environments[].runtimeWorkspaceRoots` override that fallback with environment-native absolute paths. Prefer experimental `permissions` profile selection by id for permission overrides; the legacy `sandboxPolicy` field is still accepted but cannot be combined with `permissions`. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode". Deprecated experimental `multiAgentMode` is ignored; Ultra reasoning effort selects proactive behavior. Parent-owned Multi-Agent V2 subagents reject direct turns.+- `turn/start` — add user input to a thread and begin Codex generation; responds with the initial `turn` object and streams `turn/started`, `item/*`, and `turn/completed` notifications. Optional `turnTrigger` classifies who or what started a new turn and is sent as `turn_trigger` in Responses request metadata; it is ignored if the request steers an active turn. `clientUserMessageId` is optional; when supplied, the corresponding `userMessage` item echoes it as `clientId`. Experimental `runtimeWorkspaceRoots` supplies the default roots for newly resolved environment selections. Explicit `environments[].runtimeWorkspaceRoots` override that fallback with environment-native absolute paths. Prefer experimental `permissions` profile selection by id for permission overrides; the legacy `sandboxPolicy` field is still accepted but cannot be combined with `permissions`. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode". Deprecated experimental `multiAgentMode` is ignored; Ultra reasoning effort selects proactive behavior. Parent-owned Multi-Agent V2 subagents reject direct turns.- `thread/inject_items` — append raw Responses API items to a loaded thread’s model-visible history without starting a user turn; returns `{}` on success. Parent-owned Multi-Agent V2 subagents reject direct item injection.- `turn/settings/update` — experimental; publish a narrow model-settings patch to the exact live task identified by `threadId` and `turnId`, regardless of task kind. Requires `step_model_switching`; returns `status: "applied"` or `status: "targetUnavailable"`, or a request error if rejected. Future-thread settings and already captured steps are unchanged. Parent-owned Multi-Agent V2 subagents reject direct settings updates.- `turn/steer` — add user input to an already in-flight regular turn without starting a new turn; returns the active `turnId` that accepted the input. `clientUserMessageId` is optional; when supplied, the corresponding `userMessage` item echoes it as `clientId`. Review and manual compaction turns reject `turn/steer`. Parent-owned Multi-Agent V2 subagents reject direct steering.diff --git a/codex-rs/app-server/src/message_processor_tracing_tests.rs b/codex-rs/app-server/src/message_processor_tracing_tests.rsindex f3246bb453..a452929e0a 100644--- a/codex-rs/app-server/src/message_processor_tracing_tests.rs+++ b/codex-rs/app-server/src/message_processor_tracing_tests.rs@@ -663,6 +663,7 @@ async fn turn_start_jsonrpc_span_parents_core_turn_spans() -> Result<()> {text: "hello".to_string(),text_elements: Vec::new(),}],+ turn_trigger: None,responsesapi_client_metadata: None,additional_context: None,cwd: None,diff --git a/codex-rs/app-server/src/request_processors/turn_processor.rs b/codex-rs/app-server/src/request_processors/turn_processor.rsindex d199d79b26..6ece29cc0b 100644--- a/codex-rs/app-server/src/request_processors/turn_processor.rs+++ b/codex-rs/app-server/src/request_processors/turn_processor.rs@@ -580,6 +580,7 @@ impl TurnRequestProcessor {}).with_thread_settings(thread_settings).on_start(TurnStartOptions {+ turn_trigger: params.turn_trigger,final_output_json_schema: params.output_schema,service_tier: params.service_tier_for_turn,..Default::default()diff --git a/codex-rs/app-server/tests/suite/v2/client_metadata.rs b/codex-rs/app-server/tests/suite/v2/client_metadata.rsindex 3904bee770..67b1412039 100644--- a/codex-rs/app-server/tests/suite/v2/client_metadata.rs+++ b/codex-rs/app-server/tests/suite/v2/client_metadata.rs@@ -75,6 +75,7 @@ async fn turn_start_forwards_client_metadata_to_responses_request_v2() -> Result"context_window_id".to_string(),"client-supplied".to_string(),),+ ("turn_trigger".to_string(), "client-supplied".to_string()),]);let turn_req = mcp.send_turn_start_request(TurnStartParams {@@ -84,6 +85,7 @@ async fn turn_start_forwards_client_metadata_to_responses_request_v2() -> Resulttext: "Hello".to_string(),text_elements: Vec::new(),}],+ turn_trigger: Some("user".to_string()),responsesapi_client_metadata: Some(client_metadata.clone()),..Default::default()})@@ -106,6 +108,7 @@ async fn turn_start_forwards_client_metadata_to_responses_request_v2() -> Resultassert_eq!(metadata["fiber_run_id"].as_str(), Some("fiber-start-123"));assert_eq!(metadata["origin"].as_str(), Some("gaas"));assert_eq!(metadata["thread_source"].as_str(), Some("automation"));+ assert_eq!(metadata["turn_trigger"].as_str(), Some("user"));assert_eq!(metadata["turn_id"].as_str(), Some(turn.id.as_str()));assert!(metadata.get("installation_id").is_some());assert!(metadata.get("session_id").is_some());@@ -437,6 +440,7 @@ async fn turn_steer_updates_client_metadata_on_follow_up_responses_request_v2()text: "Run sleep".to_string(),text_elements: Vec::new(),}],+ turn_trigger: Some("user".to_string()),responsesapi_client_metadata: Some(start_metadata.clone()),..Default::default()})@@ -490,6 +494,7 @@ async fn turn_steer_updates_client_metadata_on_follow_up_responses_request_v2()Some("fiber-start-123"));assert_eq!(first_metadata["turn_id"].as_str(), Some(turn_id.as_str()));+ assert_eq!(first_metadata["turn_trigger"].as_str(), Some("user"));let second_metadata = requests[1].header("x-codex-turn-metadata")@@ -502,6 +507,7 @@ async fn turn_steer_updates_client_metadata_on_follow_up_responses_request_v2());assert_eq!(second_metadata["origin"].as_str(), Some("gaas"));assert_eq!(second_metadata["turn_id"].as_str(), Some(turn_id.as_str()));+ assert_eq!(second_metadata["turn_trigger"].as_str(), Some("user"));Ok(())}@@ -555,6 +561,7 @@ async fn turn_start_forwards_client_metadata_to_responses_websocket_request_bodytext: "Hello".to_string(),text_elements: Vec::new(),}],+ turn_trigger: Some("user".to_string()),responsesapi_client_metadata: Some(client_metadata),..Default::default()})@@ -589,6 +596,7 @@ async fn turn_start_forwards_client_metadata_to_responses_websocket_request_bodyassert_eq!(metadata["fiber_run_id"].as_str(), Some("fiber-start-123"));assert_eq!(metadata["origin"].as_str(), Some("gaas"));assert_eq!(metadata["thread_source"].as_str(), Some("automation"));+ assert_eq!(metadata["turn_trigger"].as_str(), Some("user"));assert_eq!(metadata["turn_id"].as_str(), Some(turn.id.as_str()));assert!(metadata.get("session_id").is_some());assert_eq!(diff --git a/codex-rs/app-server/tests/suite/v2/thread_queue.rs b/codex-rs/app-server/tests/suite/v2/thread_queue.rsindex d094af9223..1b7099dc45 100644--- a/codex-rs/app-server/tests/suite/v2/thread_queue.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_queue.rs@@ -412,6 +412,7 @@ async fn idle_queue_dispatch_preserves_client_id() -> Result<()> {metadata["turn_id"].as_str(),Some(completed.turn.id.as_str()));+ assert_eq!(metadata["turn_trigger"].as_str(), Some("queue"));Ok(())}@@ -715,7 +716,7 @@ async fn queue_start_without_id_starts_the_head_when_idle() -> Result<()> {create_final_assistant_message_sse_response("first queued message done")?,create_final_assistant_message_sse_response("second queued message done")?,];- let (mut app, _codex_home, _server) = queue_app(responses).await?;+ let (mut app, _codex_home, server) = queue_app(responses).await?;let thread_id = app.start_thread(ThreadStartParams::default()).await?@@ -765,6 +766,26 @@ async fn queue_start_without_id_starts_the_head_when_idle() -> Result<()> {assert_eq!(completed.turn.status, TurnStatus::Completed);}assert!(list_queue(&mut app, &thread_id).await?.data.is_empty());++ let requests = server+ .received_requests()+ .await+ .context("mock request capture unavailable")?;+ let response_requests = requests+ .iter()+ .filter(|request| request.url.path().ends_with("/responses"))+ .collect::<Vec<_>>();+ assert_eq!(response_requests.len(), 3);+ for request in &response_requests[1..] {+ let metadata_header = request+ .headers+ .get("x-codex-turn-metadata")+ .context("queued model request is missing its x-codex-turn-metadata header")?+ .to_str()+ .context("queued turn metadata header is not valid ASCII")?;+ let metadata: Value = serde_json::from_str(metadata_header)?;+ assert_eq!(metadata["turn_trigger"].as_str(), Some("queue"));+ }Ok(())}diff --git a/codex-rs/app-server/tests/suite/v2/thread_resume.rs b/codex-rs/app-server/tests/suite/v2/thread_resume.rsindex dd7a2a0ac4..7250a3d752 100644--- a/codex-rs/app-server/tests/suite/v2/thread_resume.rs+++ b/codex-rs/app-server/tests/suite/v2/thread_resume.rs@@ -3021,6 +3021,23 @@ async fn thread_goal_lifecycle_emits_analytics_and_clear_deletes_goal() -> Resul.is_some());+ let requests = server+ .received_requests()+ .await+ .expect("wiremock should record response requests");+ let response_requests = requests+ .iter()+ .filter(|request| request.url.path().ends_with("/responses"))+ .collect::<Vec<_>>();+ assert_eq!(response_requests.len(), 2);+ let metadata_header = response_requests[1]+ .headers+ .get("x-codex-turn-metadata")+ .expect("goal continuation should include turn metadata")+ .to_str()?;+ let metadata: serde_json::Value = serde_json::from_str(metadata_header)?;+ assert_eq!(metadata["turn_trigger"].as_str(), Some("goal"));+let status = wait_for_goal_event(&server,DEFAULT_READ_TIMEOUT,diff --git a/codex-rs/app-server/tests/suite/v2/turn_start.rs b/codex-rs/app-server/tests/suite/v2/turn_start.rsindex 433be28752..33f22aa063 100644--- a/codex-rs/app-server/tests/suite/v2/turn_start.rs+++ b/codex-rs/app-server/tests/suite/v2/turn_start.rs@@ -357,6 +357,7 @@ async fn turn_start_steers_active_turn_and_returns_active_turn_id() -> Result<()text: "start".to_string(),text_elements: Vec::new(),}],+ turn_trigger: Some("user".to_string()),..Default::default()},})@@ -377,6 +378,7 @@ async fn turn_start_steers_active_turn_and_returns_active_turn_id() -> Result<()text: "steer".to_string(),text_elements: Vec::new(),}],+ turn_trigger: Some("goal".to_string()),..Default::default()},})@@ -391,6 +393,18 @@ async fn turn_start_steers_active_turn_and_returns_active_turn_id() -> Result<()mcp.read_stream_until_notification_message("turn/completed"),).await??;++ let requests = server.requests().await;+ assert_eq!(requests.len(), 2);+ for request in requests {+ let body: Value = serde_json::from_slice(&request)?;+ let turn_metadata: Value = serde_json::from_str(+ body["client_metadata"]["x-codex-turn-metadata"]+ .as_str()+ .context("expected x-codex-turn-metadata")?,+ )?;+ assert_eq!(turn_metadata["turn_trigger"].as_str(), Some("user"));+ }Ok(())}@@ -2767,6 +2781,7 @@ async fn turn_start_explicit_local_environment_updates_legacy_cwd_between_turns(text: "first turn".to_string(),text_elements: Vec::new(),}],+ turn_trigger: None,responsesapi_client_metadata: None,additional_context: None,cwd: Some(first_cwd.clone()),@@ -2816,6 +2831,7 @@ async fn turn_start_explicit_local_environment_updates_legacy_cwd_between_turns(text: "second turn".to_string(),text_elements: Vec::new(),}],+ turn_trigger: None,responsesapi_client_metadata: None,additional_context: None,cwd: None,diff --git a/codex-rs/core/src/codex_delegate.rs b/codex-rs/core/src/codex_delegate.rsindex b23d82b507..3bd74e0afa 100644--- a/codex-rs/core/src/codex_delegate.rs+++ b/codex-rs/core/src/codex_delegate.rs@@ -217,6 +217,7 @@ pub(crate) async fn run_codex_thread_one_shot(service_tier: None,parent_turn_id: Some(parent_turn_id),root_turn_id,+ ..Default::default()}),TurnInputMode::StartIfIdle,)diff --git a/codex-rs/core/src/guardian/review_session.rs b/codex-rs/core/src/guardian/review_session.rsindex 3f29a2595e..8e9bd6bb12 100644--- a/codex-rs/core/src/guardian/review_session.rs+++ b/codex-rs/core/src/guardian/review_session.rs@@ -1182,6 +1182,7 @@ async fn run_review_on_session(service_tier: None,parent_turn_id: Some(parent_turn.sub_id.clone()),root_turn_id: parent_turn.turn_metadata_state.root_turn_id(),+ ..Default::default()}),TurnInputMode::StartIfIdle,);diff --git a/codex-rs/core/src/responses_metadata.rs b/codex-rs/core/src/responses_metadata.rsindex a06086280d..a520072975 100644--- a/codex-rs/core/src/responses_metadata.rs+++ b/codex-rs/core/src/responses_metadata.rs@@ -43,6 +43,7 @@ pub(crate) const PARENT_TURN_ID_KEY: &str = "parent_turn_id";pub(crate) const ROOT_TURN_ID_KEY: &str = "root_turn_id";pub(crate) const SUBAGENT_KIND_KEY: &str = "subagent_kind";pub(crate) const THREAD_SOURCE_KEY: &str = "thread_source";+pub(crate) const TURN_TRIGGER_KEY: &str = "turn_trigger";pub(crate) const SANDBOX_KEY: &str = "sandbox";pub(crate) const SANDBOX_MODE_KEY: &str = "sandbox_mode";pub(crate) const AUTO_REVIEW_ENABLED_KEY: &str = "auto_review_enabled";@@ -76,6 +77,7 @@ const RESERVED_METADATA_KEYS: &[&str] = &[ROOT_TURN_ID_KEY,SUBAGENT_KIND_KEY,THREAD_SOURCE_KEY,+ TURN_TRIGGER_KEY,SANDBOX_KEY,SANDBOX_MODE_KEY,AUTO_REVIEW_ENABLED_KEY,@@ -220,6 +222,7 @@ pub struct CodexResponsesMetadata {pub(crate) subagent_header: Option<String>,pub(crate) subagent_kind: Option<String>,pub(crate) thread_source: Option<ThreadSource>,+ pub(crate) turn_trigger: Option<String>,pub(crate) sandbox: Option<String>,pub(crate) sandbox_mode: Option<String>,pub(crate) auto_review_enabled: Option<bool>,@@ -255,6 +258,7 @@ impl CodexResponsesMetadata {subagent_header: None,subagent_kind: None,thread_source: None,+ turn_trigger: None,sandbox: None,sandbox_mode: None,auto_review_enabled: None,@@ -379,6 +383,7 @@ impl CodexResponsesMetadata {root_turn_id: self.root_turn_id.as_deref(),subagent_kind: self.subagent_kind.as_deref(),thread_source: self.thread_source.as_ref(),+ turn_trigger: self.turn_trigger.as_deref(),sandbox: self.sandbox.as_deref(),sandbox_mode: self.sandbox_mode.as_deref(),auto_review_enabled: self.auto_review_enabled,@@ -508,6 +513,8 @@ struct CodexTurnMetadataPayload<'a> {#[serde(default, skip_serializing_if = "Option::is_none")]thread_source: Option<&'a ThreadSource>,#[serde(default, skip_serializing_if = "Option::is_none")]+ turn_trigger: Option<&'a str>,+ #[serde(default, skip_serializing_if = "Option::is_none")]sandbox: Option<&'a str>,#[serde(default, skip_serializing_if = "Option::is_none")]sandbox_mode: Option<&'a str>,diff --git a/codex-rs/core/src/session/turn_input.rs b/codex-rs/core/src/session/turn_input.rsindex f0a34e2a27..7eb922ba42 100644--- a/codex-rs/core/src/session/turn_input.rs+++ b/codex-rs/core/src/session/turn_input.rs@@ -120,6 +120,7 @@ impl PreparedTurnInputSettings {kind: TurnStartKind,) -> CodexResult<Option<Arc<TurnContext>>> {let TurnStartOptions {+ turn_trigger,final_output_json_schema,service_tier,parent_turn_id,@@ -147,6 +148,11 @@ impl PreparedTurnInputSettings {let Some((turn_context, settings_snapshot)) = turn_context else {return Ok(None);};+ if let Some(turn_trigger) = turn_trigger {+ turn_context+ .turn_metadata_state+ .set_turn_trigger(turn_trigger);+ }if emit_thread_settings_applied {thread_settings::emit_applied(session, submission_id, settings_snapshot).await;}@@ -205,7 +211,12 @@ pub(super) async fn handle_recovery(thread_settings: ThreadSettingsOverrides,submission_id: String,) -> CodexResult<TurnInputSubmission> {- let request = TurnInputRequest::user_input(Vec::new()).with_thread_settings(thread_settings);+ let request = TurnInputRequest::user_input(Vec::new())+ .with_thread_settings(thread_settings)+ .on_start(TurnStartOptions {+ turn_trigger: Some("retry".to_string()),+ ..Default::default()+ });start_if_idle(session, request, submission_id, TurnStartKind::Recovery).await}@@ -482,7 +493,11 @@ impl Session {TurnInputRequest::user_input(vec![UserInput::Text {text,text_elements: Vec::new(),- }]),+ }])+ .on_start(TurnStartOptions {+ turn_trigger: Some("realtime".to_string()),+ ..Default::default()+ }),TurnInputMode::StartOrSteer,submission_id.clone(),)diff --git a/codex-rs/core/src/turn_metadata.rs b/codex-rs/core/src/turn_metadata.rsindex 51face5f2c..05b50f1894 100644--- a/codex-rs/core/src/turn_metadata.rs+++ b/codex-rs/core/src/turn_metadata.rs@@ -113,6 +113,7 @@ pub(crate) struct TurnMetadataState {subagent_header: Option<String>,subagent_kind: Option<String>,thread_source: Option<ThreadSource>,+ turn_trigger: OnceLock<String>,turn_id: String,// TODO(anp): Derive this cached tag from TurnEnvironment::sandbox_context// so metadata reflects the selected environment's backend.@@ -184,6 +185,7 @@ impl TurnMetadataState {subagent_header: subagent_header_value(session_source),subagent_kind: subagent_metadata_kind(session_source),thread_source,+ turn_trigger: OnceLock::new(),turn_id,sandbox,sandbox_mode,@@ -297,6 +299,13 @@ impl TurnMetadataState {let _ = self.root_turn_id.set(root_turn_id);}+ pub(crate) fn set_turn_trigger(&self, turn_trigger: String) {+ if turn_trigger.trim().is_empty() {+ return;+ }+ let _ = self.turn_trigger.set(turn_trigger);+ }+pub(crate) fn root_turn_id(&self) -> Option<String> {self.root_turn_id.get()@@ -390,6 +399,7 @@ impl TurnMetadataState {subagent_header: self.subagent_header.clone(),subagent_kind: self.subagent_kind.clone(),thread_source: self.thread_source.clone(),+ turn_trigger: self.turn_trigger.get().cloned(),sandbox: self.sandbox.clone(),sandbox_mode: self.sandbox_mode.clone(),auto_review_enabled: Some(self.auto_review_enabled),diff --git a/codex-rs/core/src/turn_metadata_tests.rs b/codex-rs/core/src/turn_metadata_tests.rsindex 36ad699bbd..1c296dd3d4 100644--- a/codex-rs/core/src/turn_metadata_tests.rs+++ b/codex-rs/core/src/turn_metadata_tests.rs@@ -12,6 +12,7 @@ use crate::responses_metadata::PARENT_TURN_ID_KEY;use crate::responses_metadata::ROOT_TURN_ID_KEY;use crate::responses_metadata::SANDBOX_MODE_KEY;use crate::responses_metadata::TOOL_NAMESPACES_INFO_KEY;+use crate::responses_metadata::TURN_TRIGGER_KEY;use crate::responses_metadata::TurnToolFunctionInfo;use crate::responses_metadata::TurnToolNamespaceInfo;use crate::responses_metadata::TurnToolSource;@@ -682,6 +683,7 @@ fn turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields()]));state.set_parent_turn_id("parent-turn-a".to_string());state.set_root_turn_id("root-turn-a".to_string());+ state.set_turn_trigger("goal".to_string());state.set_responsesapi_client_metadata(HashMap::from([("codex_security_surface".to_string(),@@ -737,6 +739,7 @@ fn turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields("client-supplied".to_string(),),("thread_source".to_string(), "client-supplied".to_string()),+ (TURN_TRIGGER_KEY.to_string(), "client-supplied".to_string()),("request_kind".to_string(), "client-supplied".to_string()),("turn_started_at_unix_ms".to_string(),@@ -814,6 +817,7 @@ fn turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields(assert_eq!(json[ROOT_TURN_ID_KEY].as_str(), Some("root-turn-a"));assert_eq!(json["subagent_kind"].as_str(), Some("thread_spawn"));assert_eq!(json["thread_source"].as_str(), Some("automation"));+ assert_eq!(json[TURN_TRIGGER_KEY].as_str(), Some("goal"));assert_eq!(json["turn_id"].as_str(), Some("turn-a"));assert!(json.get("request_kind").is_none());assert!(json.get(WINDOW_ID_KEY).is_none());@@ -953,7 +957,12 @@ fn turn_metadata_state_overlays_compaction_only_on_compaction_requests() {#[test]fn responses_api_metadata_rejects_reserved_keys() {- for reserved_key in ["thread_source", WINDOW_ID_KEY, CONTEXT_WINDOW_ID_KEY] {+ for reserved_key in [+ "thread_source",+ TURN_TRIGGER_KEY,+ WINDOW_ID_KEY,+ CONTEXT_WINDOW_ID_KEY,+ ] {assert_eq!(validate_extra_metadata(BTreeMap::from([(reserved_key.to_string(), "sdk".to_string())]).iter()diff --git a/codex-rs/core/tests/suite/realtime_conversation.rs b/codex-rs/core/tests/suite/realtime_conversation.rsindex 7df6a447bf..490a546ea8 100644--- a/codex-rs/core/tests/suite/realtime_conversation.rs+++ b/codex-rs/core/tests/suite/realtime_conversation.rs@@ -4184,6 +4184,13 @@ async fn inbound_handoff_request_starts_turn() -> Result<()> {.await;let request = response_mock.single_request();+ let turn_metadata: Value = serde_json::from_str(+ request+ .header("x-codex-turn-metadata")+ .as_deref()+ .context("realtime-routed turn should include turn metadata")?,+ )?;+ assert_eq!(turn_metadata["turn_trigger"].as_str(), Some("realtime"));let user_texts = request.message_input_texts("user");assert!(user_texts.iter().any(|text| text== "<realtime_delegation>\n <input>text from realtime</input>\n <transcript_delta>user: text from realtime</transcript_delta>\n</realtime_delegation>"));diff --git a/codex-rs/core/tests/suite/turn_input_submission.rs b/codex-rs/core/tests/suite/turn_input_submission.rsindex f333ba84f3..475b6a0584 100644--- a/codex-rs/core/tests/suite/turn_input_submission.rs+++ b/codex-rs/core/tests/suite/turn_input_submission.rs@@ -178,9 +178,16 @@ async fn recover_turn_if_idle_preserves_id_and_resumes_plan_mode() {}).await;- let user_input_groups = response_mock- .single_request()- .message_input_text_groups("user");+ let request = response_mock.single_request();+ let turn_metadata: Value = serde_json::from_str(+ request+ .header("x-codex-turn-metadata")+ .as_deref()+ .expect("recovered turn should include turn metadata"),+ )+ .expect("recovered turn metadata should be valid JSON");+ assert_eq!(turn_metadata["turn_trigger"].as_str(), Some("retry"));+ let user_input_groups = request.message_input_text_groups("user");assert_eq!(user_input_groups.len(), 1);assert_eq!(user_input_groups[0].len(), 1);assert!(user_input_groups[0][0].starts_with("<environment_context>"));diff --git a/codex-rs/exec/src/lib.rs b/codex-rs/exec/src/lib.rsindex efb59b4424..3d049ab907 100644--- a/codex-rs/exec/src/lib.rs+++ b/codex-rs/exec/src/lib.rs@@ -973,6 +973,7 @@ async fn run_exec_session(args: ExecRunArgs) -> anyhow::Result<()> {request_id: request_ids.next(),params: TurnStartParams {thread_id: primary_thread_id_for_span.clone(),+ turn_trigger: None,client_user_message_id: None,input: items.into_iter().map(Into::into).collect(),responsesapi_client_metadata: None,diff --git a/codex-rs/ext/goal/src/runtime.rs b/codex-rs/ext/goal/src/runtime.rsindex 28cc327127..d0579090fd 100644--- a/codex-rs/ext/goal/src/runtime.rs+++ b/codex-rs/ext/goal/src/runtime.rs@@ -7,6 +7,7 @@ use codex_core::StartIfIdleSubmission;use codex_core::ThreadManager;use codex_core::TurnInput;use codex_core::TurnInputRequest;+use codex_core::TurnStartOptions;use codex_protocol::ThreadId;use codex_protocol::models::ResponseItem;use codex_protocol::protocol::ThreadGoal;@@ -406,7 +407,12 @@ impl GoalRuntimeHandle {let item = continuation_steering_item(&protocol_goal_from_state(goal));match thread- .start_turn_if_idle(TurnInputRequest::new(TurnInput::ResponseItem(item)))+ .start_turn_if_idle(+ TurnInputRequest::new(TurnInput::ResponseItem(item)).on_start(TurnStartOptions {+ turn_trigger: Some("goal".to_string()),+ ..Default::default()+ }),+ ).await{Ok(StartIfIdleSubmission::Started { .. }) => {}diff --git a/codex-rs/ext/queue/src/service.rs b/codex-rs/ext/queue/src/service.rsindex a8686efb83..e72f0c7cb7 100644--- a/codex-rs/ext/queue/src/service.rs+++ b/codex-rs/ext/queue/src/service.rs@@ -10,6 +10,7 @@ use codex_core::StartIfIdleSubmission;use codex_core::ThreadManager;use codex_core::TurnInput;use codex_core::TurnInputRequest;+use codex_core::TurnStartOptions;use codex_extension_api::ExtensionEventSink;use codex_extension_api::ExtensionFuture;use codex_extension_api::ThreadIdleCause;@@ -388,7 +389,12 @@ impl QueuedItemService {return Err(QueueServiceError::InvalidInput);};let submission = thread- .start_turn_if_idle(TurnInputRequest::new(input).with_trace(trace))+ .start_turn_if_idle(TurnInputRequest::new(input).with_trace(trace).on_start(+ TurnStartOptions {+ turn_trigger: Some("queue".to_string()),+ ..Default::default()+ },+ )).await?;if matches!(submission, StartIfIdleSubmission::Started { .. }) {self.delete_locked(thread_id, queued_item_id).await?;@@ -431,7 +437,10 @@ impl QueuedItemService {}match thread- .start_turn_if_idle(TurnInputRequest::new(input))+ .start_turn_if_idle(TurnInputRequest::new(input).on_start(TurnStartOptions {+ turn_trigger: Some("queue".to_string()),+ ..Default::default()+ })).await{Ok(StartIfIdleSubmission::Started { .. }) => {diff --git a/codex-rs/protocol/src/turn_input.rs b/codex-rs/protocol/src/turn_input.rsindex 2fe52a1a43..209de883ca 100644--- a/codex-rs/protocol/src/turn_input.rs+++ b/codex-rs/protocol/src/turn_input.rs@@ -143,6 +143,9 @@ pub enum TurnInputMode {/// child input, Core also compares root lineage to detect ambiguity.#[derive(Clone, Debug, Default)]pub struct TurnStartOptions {+ /// Source classification for the caller that starts a new turn.+ /// Ignored when the submitted input steers an active turn.+ pub turn_trigger: Option<String>,/// Structured-output schema for a new turn. When steering, Core rejects/// the input if the active turn uses a different schema.pub final_output_json_schema: Option<Value>,diff --git a/codex-rs/tui/src/app_server_session.rs b/codex-rs/tui/src/app_server_session.rsindex 5a60b3af58..186b5393af 100644--- a/codex-rs/tui/src/app_server_session.rs+++ b/codex-rs/tui/src/app_server_session.rs@@ -1201,6 +1201,7 @@ impl AppServerSession {request_id,params: TurnStartParams {thread_id: thread_id.to_string(),+ turn_trigger: None,client_user_message_id: None,input: items,responsesapi_client_metadata: None,