Round out builder coverage and document the Option<T> escape hatch

After landing per-field builders on the four highest-traffic
consumer-facing config structs (MessageOptions, ClientOptions, Tool,
SessionConfig/ResumeSessionConfig), this commit closes the long tail.

Rust ecosystem research (tokio, reqwest, tonic, axum, AWS SDK) confirms
two design points:

1. The dominant pattern for #[non_exhaustive] config builders is the
   single `with_<field>(impl Into<T>) -> Self` setter that always
   Some-wraps. AWS SDK's dual `field` + `set_field(Option<T>)` shape
   is justified by codegen, not by ergonomics — and the
   `impl Into<Option<T>>` magic that some older crates use has fallen
   out of fashion (it conflicts with `impl Into<T>` chaining and
   produces poor type-inference errors).

2. Direct field assignment on a `pub` field is idiomatic Rust for
   forwarding `Option<T>` values from upstream code. The
   http::request::Parts / hyper::Body::Builder pattern. We already
   support it; we just hadn't documented it.

This commit therefore:

- Adds full builders to the four bare consumer-facing structs:
  CustomAgentConfig (name + prompt required, six with_* setters),
  InfiniteSessionConfig (three with_* setters), ProviderConfig
  (base_url required, six with_* setters), SystemMessageConfig
  (three with_* setters).
- Expands TraceContext with a symmetric new() + with_traceparent pair
  alongside the existing from_traceparent shorthand. The shorthand
  is now expressed in terms of the chain (`new().with_traceparent(x)`)
  for consistency.
- Documents the direct-field-assignment escape hatch on SessionConfig
  and ResumeSessionConfig, with a doc example showing how to mix the
  fluent chain (for compile-time-known values) with direct mutation
  (for Option<T> pass-throughs).

Per-field `with_<x>_opt(Option<T>)` setters were considered and
deliberately rejected: doubling the method count for ~30-field
configs would hurt rustdoc discoverability and conflict with the
single-setter precedent we just shipped. The mut-let escape hatch
covers the same use case without polluting the API surface.

Adds 5 unit tests (one per new builder + a TraceContext suite) and
extends the existing CHANGELOG "Builder ergonomics" subsection.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: tclem

rust/CHANGELOG.md

@@ -381,6 +381,25 @@ public surface.
   `let mut cfg = ResumeSessionConfig::new(id); cfg.client_name =
   Some("...".into()); cfg.streaming = Some(true); ...` (10-15
   lines per site) to a single fluent chain.
+- Round out builder coverage on the remaining consumer-facing
+  config structs: `CustomAgentConfig::new(name, prompt)` plus
+  `with_display_name`, `with_description`, `with_tools`,
+  `with_mcp_servers`, `with_infer`, `with_skills`;
+  `InfiniteSessionConfig::new()` plus `with_enabled`,
+  `with_background_compaction_threshold`,
+  `with_buffer_exhaustion_threshold`;
+  `ProviderConfig::new(base_url)` plus `with_provider_type`,
+  `with_wire_api`, `with_api_key`, `with_bearer_token`,
+  `with_azure`, `with_headers`; `SystemMessageConfig::new()` plus
+  `with_mode`, `with_content`, `with_sections`. `TraceContext`
+  also gains a symmetric `new()` + `with_traceparent` pair
+  alongside the existing `from_traceparent` shorthand.
+- Documented the direct-field-assignment escape hatch on
+  `SessionConfig` and `ResumeSessionConfig` for callers forwarding
+  `Option<T>` values from upstream code (matches the
+  `http::request::Parts` / `hyper::Body::Builder` convention; per-
+  field `with_*_opt` setters intentionally omitted to keep the
+  primary API surface small).
 
 ### Fixed
 - `SessionUi::elicitation` (and the `confirm` / `select` / `input`

rust/src/trace_context.rs

@@ -35,13 +35,26 @@ pub struct TraceContext {
 }
 
 impl TraceContext {
+    /// Construct an empty [`TraceContext`]; both fields default to unset
+    /// (the SDK skips trace-context injection on the wire).
+    pub fn new() -> Self {
+        Self::default()
+    }
+
     /// Construct a [`TraceContext`] from a `traceparent` header value, with
     /// no `tracestate`.
+    ///
+    /// Equivalent to `TraceContext::new().with_traceparent(value)`; kept
+    /// for ergonomics in the common single-header case.
     pub fn from_traceparent(traceparent: impl Into<String>) -> Self {
-        Self {
-            traceparent: Some(traceparent.into()),
-            tracestate: None,
-        }
+        Self::new().with_traceparent(traceparent)
+    }
+
+    /// Set or replace the `traceparent` header value, returning `self` for
+    /// chaining.
+    pub fn with_traceparent(mut self, traceparent: impl Into<String>) -> Self {
+        self.traceparent = Some(traceparent.into());
+        self
     }
 
     /// Set or replace the `tracestate` header value, returning `self` for
@@ -87,3 +100,33 @@ pub(crate) fn inject_trace_context(params: &mut serde_json::Value, ctx: &TraceCo
         params["tracestate"] = serde_json::Value::String(ts.clone());
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::TraceContext;
+
+    #[test]
+    fn new_yields_empty_context() {
+        let ctx = TraceContext::new();
+        assert!(ctx.is_empty());
+        assert!(ctx.traceparent.is_none());
+        assert!(ctx.tracestate.is_none());
+    }
+
+    #[test]
+    fn builder_composes_traceparent_and_tracestate() {
+        let ctx = TraceContext::new()
+            .with_traceparent("00-trace-span-01")
+            .with_tracestate("vendor=key");
+        assert_eq!(ctx.traceparent.as_deref(), Some("00-trace-span-01"));
+        assert_eq!(ctx.tracestate.as_deref(), Some("vendor=key"));
+        assert!(!ctx.is_empty());
+    }
+
+    #[test]
+    fn from_traceparent_matches_builder() {
+        let direct = TraceContext::from_traceparent("00-trace-span-01");
+        let chained = TraceContext::new().with_traceparent("00-trace-span-01");
+        assert_eq!(direct, chained);
+    }
+}