Add ClientOptions::new() and Tool::new() builder methods

Mirrors the existing MessageOptions::new() / with_* builder pattern
on the two other public #[non_exhaustive] config types that consumers
construct most often. Closes the cross-crate ergonomics gap that
#[non_exhaustive] introduces: external callers can't use struct-
literal syntax (with or without ..Default::default()) on these types,
so every field assignment becomes its own mut-let statement. The
builder shape collapses that into a single chained expression.

Caught by github-app PR #4140 review on src-tauri/src/session/cli.rs:
the mut-let-and-assign pattern read as awkward to reviewers even
after trimming to the four fields that diverge from default. Same
ergonomic friction that prompted the make_tool() helper consumers
were writing for Tool. Builder ships zero-cost convenience without
giving up #[non_exhaustive]'s SemVer protection on growable config
struct.

ClientOptions builder (rust/src/lib.rs):

- new() -> Self                         (documented entry point)
- with_program(impl Into<CliProgram>)
- with_prefix_args<I: IntoIterator<...>>(args)
- with_cwd(impl Into<PathBuf>)
- with_env<I: IntoIterator<(K, V)>>
- with_env_remove<I: IntoIterator<S>>
- with_extra_args<I: IntoIterator<S>>
- with_transport(Transport)
- with_github_token(impl Into<String>)
- with_use_logged_in_user(bool)
- with_log_level(LogLevel)
- with_session_idle_timeout_seconds(u64)
- with_list_models_handler<H: ListModelsHandler + 'static>     (Arc-wrapped internally)
- with_session_fs(SessionFsConfig)
- with_trace_context_provider<P: TraceContextProvider + 'static>    (Arc-wrapped internally)
- with_telemetry(TelemetryConfig)

Tool builder (rust/src/types.rs):

- new(impl Into<String>) -> Self        (name + defaults)
- with_namespaced_name(impl Into<String>)
- with_description(impl Into<String>)
- with_instructions(impl Into<String>)
- with_parameters(serde_json::Value)
- with_overrides_built_in_tool(bool)
- with_skip_permission(bool)

Pure additive: no existing ClientOptions::default() / mut-let
patterns break, no public field visibility changes. Both builders
compose by wrapping ::default() and mutating-and-returning self,
matching MessageOptions's idiom.

Tests: client_options_builder_composes verifies all 10 chained
builder methods produce the expected internal state.
tool_builder_composes does the same for Tool's seven methods, plus
tool_with_parameters_handles_non_object_value covers the
HashMap-from-Value extraction edge case (json!(null) -> empty map
rather than panic).

CHANGELOG: new "Builder ergonomics" subsection under Documentation,
explaining the rationale and listing both builders.

Validation: 220 tests pass (was 215 + 5 new builder tests across
unit + doctest), cargo doc -D warnings clean, cargo fmt --check
clean, cargo clippy --all-features --all-targets -- -D warnings
clean.

Companion ask from github-app PR #4140 review (Sync session)
follows up: github-app's `cli.rs` and ~25 Tool::new() call sites
will switch to the builder form once this lands and the next
sync round-trip pulls it.

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

Author: tclem

rust/CHANGELOG.md

@@ -349,6 +349,28 @@ public surface.
   `lifecycle_observer`.
 - `RELEASING.md` operational runbook for maintainers.
 
+#### Builder ergonomics
+- `ClientOptions::new()` plus a chainable `with_*` builder per public
+  field (`with_program`, `with_prefix_args`, `with_cwd`, `with_env`,
+  `with_env_remove`, `with_extra_args`, `with_transport`,
+  `with_github_token`, `with_use_logged_in_user`, `with_log_level`,
+  `with_session_idle_timeout_seconds`, `with_list_models_handler`,
+  `with_session_fs`, `with_trace_context_provider`, `with_telemetry`).
+  Mirrors the existing [`MessageOptions::new`] / `with_*` shape and
+  closes the cross-crate ergonomics gap on `#[non_exhaustive]` —
+  external callers no longer need to write
+  `let mut opts = ClientOptions::default(); opts.field = ...;` for
+  every field they touch. Existing `ClientOptions::default()` and
+  mut-let-and-assign continue to work unchanged.
+- `Tool::new(name)` plus `with_namespaced_name`, `with_description`,
+  `with_instructions`, `with_parameters`, `with_overrides_built_in_tool`,
+  `with_skip_permission` for tool definitions. Same rationale —
+  `Tool` is the most-instantiated `#[non_exhaustive]` type at consumer
+  call sites (~25 sites in github-app's tool catalog), where the
+  builder shape replaces the per-consumer `make_tool(name, desc,
+  params)` helper that consumers were writing to smooth over the
+  mut-let pattern.
+
 ### Fixed
 - `SessionUi::elicitation` (and the `confirm` / `select` / `input`
   convenience helpers that delegate through it) now sends the user-supplied

rust/src/lib.rs

@@ -571,6 +571,146 @@ impl Default for ClientOptions {
     }
 }
 
+impl ClientOptions {
+    /// Construct a new [`ClientOptions`] with default values.
+    ///
+    /// Equivalent to [`ClientOptions::default`]; provided as a documented
+    /// construction entry point for the builder chain. The struct is
+    /// `#[non_exhaustive]`, so external callers cannot use struct-literal
+    /// syntax — use this builder or [`Default::default`] plus mut-let.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use github_copilot_sdk::{ClientOptions, LogLevel};
+    /// let opts = ClientOptions::new()
+    ///     .with_log_level(LogLevel::Debug)
+    ///     .with_github_token("ghp_…");
+    /// ```
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// How to locate the CLI binary. See [`CliProgram`].
+    pub fn with_program(mut self, program: impl Into<CliProgram>) -> Self {
+        self.program = program.into();
+        self
+    }
+
+    /// Arguments prepended before `--server` (e.g. the script path for node).
+    pub fn with_prefix_args<I, S>(mut self, args: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<OsString>,
+    {
+        self.prefix_args = args.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Working directory for the CLI process.
+    pub fn with_cwd(mut self, cwd: impl Into<PathBuf>) -> Self {
+        self.cwd = cwd.into();
+        self
+    }
+
+    /// Environment variables to set on the child process.
+    pub fn with_env<I, K, V>(mut self, env: I) -> Self
+    where
+        I: IntoIterator<Item = (K, V)>,
+        K: Into<OsString>,
+        V: Into<OsString>,
+    {
+        self.env = env.into_iter().map(|(k, v)| (k.into(), v.into())).collect();
+        self
+    }
+
+    /// Environment variable names to remove from the child process.
+    pub fn with_env_remove<I, S>(mut self, names: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<OsString>,
+    {
+        self.env_remove = names.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Extra CLI flags appended after the transport-specific arguments.
+    pub fn with_extra_args<I, S>(mut self, args: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<String>,
+    {
+        self.extra_args = args.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Transport mode used to communicate with the CLI server. See [`Transport`].
+    pub fn with_transport(mut self, transport: Transport) -> Self {
+        self.transport = transport;
+        self
+    }
+
+    /// GitHub token for authentication. The SDK passes the token to the
+    /// CLI via `--auth-token-env COPILOT_SDK_AUTH_TOKEN`.
+    pub fn with_github_token(mut self, token: impl Into<String>) -> Self {
+        self.github_token = Some(token.into());
+        self
+    }
+
+    /// Whether the CLI should fall back to the logged-in `gh` user when
+    /// no token is provided. See the field docs for default semantics.
+    pub fn with_use_logged_in_user(mut self, use_logged_in: bool) -> Self {
+        self.use_logged_in_user = Some(use_logged_in);
+        self
+    }
+
+    /// Log level passed to the CLI server via `--log-level`.
+    pub fn with_log_level(mut self, level: LogLevel) -> Self {
+        self.log_level = Some(level);
+        self
+    }
+
+    /// Server-wide idle timeout for sessions (seconds). Pass `0` to leave
+    /// sessions running indefinitely (the CLI default).
+    pub fn with_session_idle_timeout_seconds(mut self, seconds: u64) -> Self {
+        self.session_idle_timeout_seconds = Some(seconds);
+        self
+    }
+
+    /// Override [`Client::list_models`] with a caller-supplied handler.
+    /// The handler is wrapped in `Arc` internally.
+    pub fn with_list_models_handler<H>(mut self, handler: H) -> Self
+    where
+        H: ListModelsHandler + 'static,
+    {
+        self.on_list_models = Some(Arc::new(handler));
+        self
+    }
+
+    /// Custom session filesystem provider configuration.
+    pub fn with_session_fs(mut self, config: SessionFsConfig) -> Self {
+        self.session_fs = Some(config);
+        self
+    }
+
+    /// Set the [`TraceContextProvider`] used to inject W3C Trace Context
+    /// headers on outbound `session.create` / `session.resume` /
+    /// `session.send` requests. The provider is wrapped in `Arc` internally.
+    pub fn with_trace_context_provider<P>(mut self, provider: P) -> Self
+    where
+        P: TraceContextProvider + 'static,
+    {
+        self.on_get_trace_context = Some(Arc::new(provider));
+        self
+    }
+
+    /// OpenTelemetry config forwarded to the spawned CLI process.
+    pub fn with_telemetry(mut self, config: TelemetryConfig) -> Self {
+        self.telemetry = Some(config);
+        self
+    }
+}
+
 /// Validate a [`SessionFsConfig`] before sending `sessionFs.setProvider`.
 fn validate_session_fs_config(cfg: &SessionFsConfig) -> Result<(), Error> {
     if cfg.initial_cwd.trim().is_empty() {
@@ -1619,6 +1759,37 @@ mod tests {
         assert!(!err.is_transport_failure());
     }
 
+    #[test]
+    fn client_options_builder_composes() {
+        let opts = ClientOptions::new()
+            .with_program(CliProgram::Path(PathBuf::from("/usr/local/bin/copilot")))
+            .with_prefix_args(["node"])
+            .with_cwd(PathBuf::from("/tmp"))
+            .with_env([("KEY", "value")])
+            .with_env_remove(["UNWANTED"])
+            .with_extra_args(["--quiet"])
+            .with_github_token("ghp_test")
+            .with_use_logged_in_user(false)
+            .with_log_level(LogLevel::Debug)
+            .with_session_idle_timeout_seconds(120);
+        assert!(matches!(opts.program, CliProgram::Path(_)));
+        assert_eq!(opts.prefix_args, vec![std::ffi::OsString::from("node")]);
+        assert_eq!(opts.cwd, PathBuf::from("/tmp"));
+        assert_eq!(
+            opts.env,
+            vec![(
+                std::ffi::OsString::from("KEY"),
+                std::ffi::OsString::from("value")
+            )]
+        );
+        assert_eq!(opts.env_remove, vec![std::ffi::OsString::from("UNWANTED")]);
+        assert_eq!(opts.extra_args, vec!["--quiet".to_string()]);
+        assert_eq!(opts.github_token.as_deref(), Some("ghp_test"));
+        assert_eq!(opts.use_logged_in_user, Some(false));
+        assert!(matches!(opts.log_level, Some(LogLevel::Debug)));
+        assert_eq!(opts.session_idle_timeout_seconds, Some(120));
+    }
+
     #[test]
     fn is_transport_failure_rejects_other_protocol_errors() {
         let err = Error::Protocol(ProtocolError::CliStartupTimeout);

rust/src/types.rs

@@ -333,6 +333,84 @@ fn is_false(b: &bool) -> bool {
     !*b
 }
 
+impl Tool {
+    /// Construct a new [`Tool`] with the given name and otherwise default
+    /// values. The struct is `#[non_exhaustive]`, so external callers
+    /// cannot use struct-literal syntax — use this builder or
+    /// [`Default::default`] plus mut-let.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use github_copilot_sdk::types::Tool;
+    /// # use serde_json::json;
+    /// let tool = Tool::new("greet")
+    ///     .with_description("Say hello to a user")
+    ///     .with_parameters(json!({
+    ///         "type": "object",
+    ///         "properties": { "name": { "type": "string" } },
+    ///         "required": ["name"]
+    ///     }));
+    /// # let _ = tool;
+    /// ```
+    pub fn new(name: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            ..Default::default()
+        }
+    }
+
+    /// Set the namespaced name for declarative filtering (e.g.
+    /// `"playwright/navigate"` for MCP tools).
+    pub fn with_namespaced_name(mut self, namespaced_name: impl Into<String>) -> Self {
+        self.namespaced_name = Some(namespaced_name.into());
+        self
+    }
+
+    /// Set the human-readable description of what the tool does.
+    pub fn with_description(mut self, description: impl Into<String>) -> Self {
+        self.description = description.into();
+        self
+    }
+
+    /// Set optional instructions for how to use this tool effectively.
+    pub fn with_instructions(mut self, instructions: impl Into<String>) -> Self {
+        self.instructions = Some(instructions.into());
+        self
+    }
+
+    /// Set the JSON Schema for the tool's input parameters.
+    ///
+    /// Accepts anything that converts into a JSON object, including a
+    /// `serde_json::Value` produced by `json!({...})`. Non-object values
+    /// are stored as an empty parameter map; callers that need direct
+    /// control over the field can construct a `HashMap<String, Value>`
+    /// and assign it to [`Tool::parameters`] via [`Default::default`].
+    pub fn with_parameters(mut self, parameters: Value) -> Self {
+        self.parameters = parameters
+            .as_object()
+            .map(|m| m.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+            .unwrap_or_default();
+        self
+    }
+
+    /// Mark this tool as overriding a built-in tool of the same name.
+    /// E.g. supplying a custom `grep` that the agent uses in place of the
+    /// CLI's built-in implementation.
+    pub fn with_overrides_built_in_tool(mut self, overrides: bool) -> Self {
+        self.overrides_built_in_tool = overrides;
+        self
+    }
+
+    /// When `true`, the CLI will not request permission before invoking
+    /// this tool. Use with caution — the tool is responsible for any
+    /// access control.
+    pub fn with_skip_permission(mut self, skip: bool) -> Self {
+        self.skip_permission = skip;
+        self
+    }
+}
+
 /// Context passed to a [`CommandHandler`] when a registered slash command
 /// is executed by the user.
 #[non_exhaustive]
@@ -2323,9 +2401,37 @@ mod tests {
     use super::{
         Attachment, AttachmentLineRange, AttachmentSelectionPosition, AttachmentSelectionRange,
         ConnectionState, DeliveryMode, GitHubReferenceType, ResumeSessionConfig, SessionConfig,
-        SessionId, ensure_attachment_display_names,
+        SessionId, Tool, ensure_attachment_display_names,
     };
 
+    #[test]
+    fn tool_builder_composes() {
+        let tool = Tool::new("greet")
+            .with_description("Say hello")
+            .with_namespaced_name("hello/greet")
+            .with_instructions("Pass the user's name")
+            .with_parameters(json!({
+                "type": "object",
+                "properties": { "name": { "type": "string" } },
+                "required": ["name"]
+            }))
+            .with_overrides_built_in_tool(true)
+            .with_skip_permission(true);
+        assert_eq!(tool.name, "greet");
+        assert_eq!(tool.description, "Say hello");
+        assert_eq!(tool.namespaced_name.as_deref(), Some("hello/greet"));
+        assert_eq!(tool.instructions.as_deref(), Some("Pass the user's name"));
+        assert_eq!(tool.parameters.get("type").unwrap(), &json!("object"));
+        assert!(tool.overrides_built_in_tool);
+        assert!(tool.skip_permission);
+    }
+
+    #[test]
+    fn tool_with_parameters_handles_non_object_value() {
+        let tool = Tool::new("noop").with_parameters(json!(null));
+        assert!(tool.parameters.is_empty());
+    }
+
     #[test]
     fn session_config_default_enables_permission_flow_flags() {
         let cfg = SessionConfig::default();