fix: preserve defined W3C flags in native tracing

.changeset/defined-native-trace-flags.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents': patch
+'@openai/agents-codex': patch
+---
+
+fix: accept defined sampled and random-trace-ID flag combinations and preserve them through native parent and callback header propagation, including later owned child turns.

packages/agents-codex/native/patches/0058-w3c-defined-trace-flags.patch

@@ -0,0 +1,294 @@
+diff --git a/codex-rs/otel/src/trace_context.rs b/codex-rs/otel/src/trace_context.rs
+index e1c62777f1c1bd33eaf6898a57b9157de0085e79..bc5c1f256f8e5419c64508b25383fb2300e6a2ae 100644
+--- a/codex-rs/otel/src/trace_context.rs
++++ b/codex-rs/otel/src/trace_context.rs
+@@ -9,7 +9,10 @@ use std::sync::RwLock;
+ use codex_protocol::protocol::W3cTraceContext;
+ use opentelemetry::Context;
+ use opentelemetry::propagation::TextMapPropagator;
++use opentelemetry::trace::SpanContext;
+ use opentelemetry::trace::TraceContextExt;
++use opentelemetry::trace::TraceFlags;
++use opentelemetry::trace::TraceId;
+ use opentelemetry::trace::TraceState;
+ use opentelemetry_sdk::propagation::TraceContextPropagator;
+ use tracing::Span;
+@@ -17,6 +20,13 @@ use tracing::debug;
+ use tracing::warn;
+ use tracing_opentelemetry::OpenTelemetrySpanExt;
+
++// The pinned SDK clears flags on dropped spans. Bind the inherited random bit
++// to its trace identity so it cannot leak when a Context adopts another trace.
++struct RandomTraceId {
++    trace_id: TraceId,
++    random: bool,
++}
++
+ const TRACEPARENT_ENV_VAR: &str = "TRACEPARENT";
+ const TRACESTATE_ENV_VAR: &str = "TRACESTATE";
+ static TRACEPARENT_CONTEXT: OnceLock<Option<Context>> = OnceLock::new();
+@@ -42,6 +52,22 @@ pub(crate) fn context_w3c_trace_context(context: &Context) -> Option<W3cTraceCon
+
+     let mut headers = HashMap::new();
+     TraceContextPropagator::new().inject_context(context, &mut headers);
++    // The pinned propagator predates the W3C random-trace-id flag. Child
++    // spans retain it, so preserve it when writing their canonical header.
++    let mut flags = context.span().span_context().trace_flags().to_u8() & 0x03;
++    if let Some(random) = context
++        .get::<RandomTraceId>()
++        .filter(|random| random.trace_id == context.span().span_context().trace_id())
++    {
++        flags = (flags & !0x02) | if random.random { 0x02 } else { 0 };
++    }
++    if flags & 0x02 != 0 {
++        if let Some(parent) = headers.get_mut("traceparent") {
++            if let Some((prefix, _)) = parent.rsplit_once('-') {
++                *parent = format!("{prefix}-{flags:02x}");
++            }
++        }
++    }
+     let tracestate = headers.remove("tracestate");
+     let configured_tracestate_guard = tracestate_entries()
+         .read()
+@@ -122,7 +148,23 @@ pub fn set_parent_from_w3c_trace_context(span: &Span, trace: &W3cTraceContext) -
+ }
+
+ pub fn set_parent_from_context(span: &Span, context: Context) {
+-    let _ = span.set_parent(context);
++    let _ = span.set_parent(with_inherited_random_flag(context));
++}
++
++fn with_inherited_random_flag(context: Context) -> Context {
++    let parent = context.span().span_context().clone();
++    let context =
++        if parent.is_valid() && (parent.is_remote() || parent.trace_flags().to_u8() & 0x02 != 0) {
++            // Remote adoption is authoritative, including an explicitly unset bit.
++            // Local dropped children retain the inherited value in their Context.
++            context.with_value(RandomTraceId {
++                trace_id: parent.trace_id(),
++                random: parent.trace_flags().to_u8() & 0x02 != 0,
++            })
++        } else {
++            context
++        };
++    context
+ }
+
+ pub fn traceparent_context_from_env() -> Option<Context> {
+@@ -135,9 +177,36 @@ pub(crate) fn context_from_trace_headers(
+     traceparent: Option<&str>,
+     tracestate: Option<&str>,
+ ) -> Option<Context> {
+-    let traceparent = traceparent?;
++    let traceparent = traceparent?.trim();
++    // The pinned propagator accepts short hexadecimal IDs. Require the W3C
++    // field widths, then delegate all remaining validation to the propagator.
++    let mut fields = traceparent.split('-');
++    let version = fields.next()?;
++    let trace_id = fields.next()?;
++    let parent_id = fields.next()?;
++    let raw_flags = fields.next()?;
++    if version.len() != 2 || trace_id.len() != 32 || parent_id.len() != 16 || raw_flags.len() != 2 {
++        return None;
++    }
++    // W3C Level 2 defines bit 0 as sampled and bit 1 as random trace ID.
++    // Let the pinned propagator validate all other header syntax using its
++    // supported sampling bit, then restore the complete defined flags.
++    let flags = match raw_flags {
++        "02" => Some(0x02),
++        "03" => Some(0x03),
++        _ => None,
++    };
++    let normalized = flags.and_then(|flags| {
++        traceparent.strip_prefix("00-")?;
++        traceparent
++            .strip_suffix(if flags == 2 { "02" } else { "03" })
++            .map(|prefix| format!("{prefix}{:02x}", flags & 1))
++    });
+     let mut headers = HashMap::new();
+-    headers.insert("traceparent".to_string(), traceparent.to_string());
++    headers.insert(
++        "traceparent".to_string(),
++        normalized.unwrap_or_else(|| traceparent.to_string()),
++    );
+     if let Some(tracestate) = tracestate {
+         headers.insert("tracestate".to_string(), tracestate.to_string());
+     }
+@@ -147,7 +216,20 @@ pub(crate) fn context_from_trace_headers(
+     if !context.span().span_context().is_valid() {
+         return None;
+     }
+-    Some(context)
++    if let Some(flags) = flags {
++        let span = context.span();
++        let parent = span.span_context();
++        return Some(with_inherited_random_flag(
++            context.with_remote_span_context(SpanContext::new(
++                parent.trace_id(),
++                parent.span_id(),
++                TraceFlags::new(flags),
++                true,
++                parent.trace_state().clone(),
++            )),
++        ));
++    }
++    Some(with_inherited_random_flag(context))
+ }
+
+ fn load_traceparent_context() -> Option<Context> {
+@@ -373,6 +455,155 @@ mod tests {
+         assert!(span_context.is_remote());
+     }
+
++    #[test]
++    fn defined_trace_flags_survive_child_header_propagation() {
++        use super::span_w3c_trace_context;
++        use tracing_opentelemetry::OpenTelemetrySpanExt;
++
++        for flags in ["00", "01", "02", "03"] {
++            let provider = SdkTracerProvider::builder().build();
++            let subscriber = tracing_subscriber::registry()
++                .with(tracing_opentelemetry::layer().with_tracer(provider.tracer("flags")));
++            tracing::subscriber::with_default(subscriber, || {
++                let parent =
++                    format!("00-11111111111111111111111111111111-2222222222222222-{flags}");
++                let context =
++                    context_from_trace_headers(Some(&parent), Some("vendor=value")).unwrap();
++                assert_eq!(
++                    context.span().span_context().trace_flags().to_u8(),
++                    u8::from_str_radix(flags, 16).unwrap()
++                );
++                let span = tracing::info_span!("child");
++                super::set_parent_from_context(&span, context);
++                let headers = span_w3c_trace_context(&span).unwrap();
++                let header = headers.traceparent.unwrap();
++                assert_eq!(&header[3..35], &parent[3..35]);
++                assert_eq!(&header[53..], flags);
++                assert_ne!(&header[36..52], &parent[36..52]);
++                let grandchild = tracing::info_span!("grandchild");
++                super::set_parent_from_context(&grandchild, span.context());
++                let grandchild_header = span_w3c_trace_context(&grandchild)
++                    .unwrap()
++                    .traceparent
++                    .unwrap();
++                assert_eq!(&grandchild_header[3..35], &parent[3..35]);
++                assert_eq!(&grandchild_header[53..], flags);
++                assert_ne!(&grandchild_header[36..52], &header[36..52]);
++                assert_eq!(headers.tracestate.as_deref(), Some("vendor=value"));
++            });
++        }
++        assert!(
++            context_from_trace_headers(
++                Some("00-00000000000000000000000000000000-2222222222222222-03"),
++                None
++            )
++            .is_none()
++        );
++        assert!(context_from_trace_headers(Some("00-bad-2222222222222222-03"), None).is_none());
++    }
++
++    #[test]
++    fn inherited_random_flag_preserves_local_sampling_decisions() {
++        for (sampler, incoming, outgoing) in [
++            (opentelemetry_sdk::trace::Sampler::AlwaysOff, "03", "02"),
++            (opentelemetry_sdk::trace::Sampler::AlwaysOn, "02", "03"),
++        ] {
++            let provider = SdkTracerProvider::builder().with_sampler(sampler).build();
++            let subscriber = tracing_subscriber::registry()
++                .with(tracing_opentelemetry::layer().with_tracer(provider.tracer("sampling")));
++            tracing::subscriber::with_default(subscriber, || {
++                let parent =
++                    format!("00-11111111111111111111111111111111-2222222222222222-{incoming}");
++                let context = context_from_trace_headers(Some(&parent), None).unwrap();
++                let span = tracing::info_span!("sampling");
++                super::set_parent_from_context(&span, context);
++                let header = super::span_w3c_trace_context(&span)
++                    .unwrap()
++                    .traceparent
++                    .unwrap();
++                assert_eq!(&header[53..], outgoing);
++                assert_eq!(&header[3..35], &parent[3..35]);
++                assert_ne!(&header[36..52], &parent[36..52]);
++            });
++        }
++    }
++
++    #[test]
++    fn inherited_random_flag_does_not_cross_trace_ids_or_fresh_roots() {
++        use tracing_opentelemetry::OpenTelemetrySpanExt;
++        let provider = SdkTracerProvider::builder().build();
++        let subscriber = tracing_subscriber::registry()
++            .with(tracing_opentelemetry::layer().with_tracer(provider.tracer("identity")));
++        tracing::subscriber::with_default(subscriber, || {
++            let parent = "00-11111111111111111111111111111111-2222222222222222-02";
++            let span = tracing::info_span!("original");
++            super::set_parent_from_context(
++                &span,
++                context_from_trace_headers(Some(parent), None).unwrap(),
++            );
++            for (trace_id, flags) in [
++                ("11111111111111111111111111111111", 0),
++                ("11111111111111111111111111111111", 1),
++                ("33333333333333333333333333333333", 1),
++            ] {
++                let replacement = span.context().with_remote_span_context(
++                    opentelemetry::trace::SpanContext::new(
++                        TraceId::from_hex(trace_id).unwrap(),
++                        SpanId::from_hex("4444444444444444").unwrap(),
++                        opentelemetry::trace::TraceFlags::new(flags),
++                        true,
++                        Default::default(),
++                    ),
++                );
++                let other = tracing::info_span!("other");
++                super::set_parent_from_context(&other, replacement);
++                let header = super::span_w3c_trace_context(&other)
++                    .unwrap()
++                    .traceparent
++                    .unwrap();
++                assert_eq!(&header[3..35], trace_id);
++                assert_eq!(&header[53..], format!("{flags:02x}"));
++                assert_ne!(&header[36..52], "4444444444444444");
++            }
++            let invalid = tracing::info_span!("invalid");
++            super::set_parent_from_context(
++                &invalid,
++                span.context()
++                    .with_remote_span_context(opentelemetry::trace::SpanContext::empty_context()),
++            );
++            assert!(super::span_w3c_trace_context(&invalid).is_none());
++            let fresh = tracing::info_span!("fresh");
++            super::set_parent_from_context(&fresh, opentelemetry::Context::new());
++            let header = super::span_w3c_trace_context(&fresh)
++                .unwrap()
++                .traceparent
++                .unwrap();
++            assert_ne!(&header[3..35], &parent[3..35]);
++            assert_eq!(&header[53..], "01");
++        });
++    }
++
++    #[test]
++    fn direct_native_context_keeps_unsampled_random_trace_flag() {
++        use opentelemetry::trace::Tracer as _;
++        let provider = SdkTracerProvider::builder().build();
++        let tracer = provider.tracer("direct");
++        let parent = context_from_trace_headers(
++            Some("00-11111111111111111111111111111111-2222222222222222-02"),
++            None,
++        )
++        .unwrap();
++        let child = tracer.start_with_context("direct-child", &parent);
++        let context = parent.with_span(child);
++        let header = super::context_w3c_trace_context(&context)
++            .unwrap()
++            .traceparent
++            .unwrap();
++        assert_eq!(&header[3..35], "11111111111111111111111111111111");
++        assert_ne!(&header[36..52], "2222222222222222");
++        assert_eq!(&header[53..], "02");
++    }
++
+     #[test]
+     fn invalid_traceparent_returns_none() {
+         let parent = context_from_trace_headers(

packages/agents-codex/native/patches/series.json

@@ -271,7 +271,11 @@
     {
       "path": "0059-native-request-metadata.patch",
       "sha256": "00fb1ca9eff806e34ebd56521d4367c4905e6be285b773a2c32cc8ec617f17ae"
+    },
+    {
+      "path": "0058-w3c-defined-trace-flags.patch",
+      "sha256": "1c689d4839940e41ceb5f47c3c65d02a51608a02c63230ed435997a1c751b6ed"
     }
   ],
-  "result_tree": "6e3ca2e842c1caf783abd91fb2aed74233b8366d"
+  "result_tree": "a58aca9912ec58771e46f1fd577395486798cfbf"
 }

packages/agents-codex/native/rust/lib.rs

@@ -3950,44 +3950,46 @@ mod native_trace_merge_tests {
         )
         .unwrap();
         let token = readback["handle"].as_str().unwrap();
-        let explicit = W3cTraceContext {
-            traceparent: Some(format!(
-                "00-{}-{}-01",
-                readback["trace_id"].as_str().unwrap(),
-                readback["span_id"].as_str().unwrap()
-            )),
-            tracestate: Some("fixture=explicit".into()),
-        };
-        let mut mismatch = json!({"input":[],"trace":carrier("12345678901234ab","01","fixture=other"),"tracing_context":token});
-        let receipt = ops::prepare_submission_trace(&mut mismatch)
-            .unwrap()
-            .unwrap();
-        assert_eq!(receipt["status"], "not_submitted");
-        assert_eq!(receipt["reason"]["type"], "trace_context_conflict");
-        assert!(codex_otel::sdk_trace::trace_span_context(token).is_ok());
-        let mut matching = json!({"input":[],"trace":explicit,"tracing_context":token});
-        assert!(
-            ops::prepare_submission_trace(&mut matching)
+        for flags in ["02", "03"] {
+            let explicit = W3cTraceContext {
+                traceparent: Some(format!(
+                    "00-{}-{}-{flags}",
+                    readback["trace_id"].as_str().unwrap(),
+                    readback["span_id"].as_str().unwrap()
+                )),
+                tracestate: Some("fixture=explicit".into()),
+            };
+            let mut mismatch = json!({"input":[],"trace":carrier("12345678901234ab","01","fixture=other"),"tracing_context":token});
+            let receipt = ops::prepare_submission_trace(&mut mismatch)
                 .unwrap()
-                .is_none()
-        );
-        assert_eq!(
-            matching["trace"]["traceparent"],
-            explicit.traceparent.as_deref().unwrap()
-        );
-        assert_eq!(matching["trace"]["tracestate"], "fixture=explicit");
-        assert!(matching.get("tracing_context").is_none());
-        let parsed = codex_otel::context_from_w3c_trace_context(&explicit).unwrap();
-        assert!(codex_otel::sdk_trace::policy_for_context(&parsed).is_none());
-        let _caller = codex_otel::sdk_trace::context(token).unwrap().attach();
-        let restored = codex_otel::sdk_trace::current_scope_policy().unwrap();
-        let original = codex_otel::sdk_trace::policy_for_context(
-            &codex_otel::sdk_trace::context(token).unwrap(),
-        )
-        .unwrap();
-        assert!(std::sync::Arc::ptr_eq(&restored, &original));
-        assert!(restored.disabled);
-        assert!(!restored.include_sensitive_data);
+                .unwrap();
+            assert_eq!(receipt["status"], "not_submitted");
+            assert_eq!(receipt["reason"]["type"], "trace_context_conflict");
+            assert!(codex_otel::sdk_trace::trace_span_context(token).is_ok());
+            let mut matching = json!({"input":[],"trace":explicit,"tracing_context":token});
+            assert!(
+                ops::prepare_submission_trace(&mut matching)
+                    .unwrap()
+                    .is_none()
+            );
+            assert_eq!(
+                matching["trace"]["traceparent"],
+                explicit.traceparent.as_deref().unwrap()
+            );
+            assert_eq!(matching["trace"]["tracestate"], "fixture=explicit");
+            assert!(matching.get("tracing_context").is_none());
+            let parsed = codex_otel::context_from_w3c_trace_context(&explicit).unwrap();
+            assert!(codex_otel::sdk_trace::policy_for_context(&parsed).is_none());
+            let _caller = codex_otel::sdk_trace::context(token).unwrap().attach();
+            let restored = codex_otel::sdk_trace::current_scope_policy().unwrap();
+            let original = codex_otel::sdk_trace::policy_for_context(
+                &codex_otel::sdk_trace::context(token).unwrap(),
+            )
+            .unwrap();
+            assert!(std::sync::Arc::ptr_eq(&restored, &original));
+            assert!(restored.disabled);
+            assert!(!restored.include_sensitive_data);
+        }
         let mut scoped_only = json!({"input":[],"tracing_context":token});
         assert!(
             ops::prepare_submission_trace(&mut scoped_only)