Struct SessionConfig 

#[non_exhaustive]
pub struct SessionConfig {

    pub session_id: Option<SessionId>,
    pub model: Option<String>,
    pub client_name: Option<String>,
    pub reasoning_effort: Option<String>,
    pub streaming: Option<bool>,
    pub system_message: Option<SystemMessageConfig>,
    pub tools: Option<Vec<Tool>>,
    pub available_tools: Option<Vec<String>>,
    pub excluded_tools: Option<Vec<String>>,
    pub mcp_servers: Option<HashMap<String, McpServerConfig>>,
    pub enable_config_discovery: Option<bool>,
    pub request_user_input: Option<bool>,
    pub request_permission: Option<bool>,
    pub request_exit_plan_mode: Option<bool>,
    pub request_auto_mode_switch: Option<bool>,
    pub request_elicitation: Option<bool>,
    pub skill_directories: Option<Vec<PathBuf>>,
    pub instruction_directories: Option<Vec<PathBuf>>,
    pub disabled_skills: Option<Vec<String>>,
    pub hooks: Option<bool>,
    pub custom_agents: Option<Vec<CustomAgentConfig>>,
    pub default_agent: Option<DefaultAgentConfig>,
    pub agent: Option<String>,
    pub infinite_sessions: Option<InfiniteSessionConfig>,
    pub provider: Option<ProviderConfig>,
    pub enable_session_telemetry: Option<bool>,
    pub model_capabilities: Option<ModelCapabilitiesOverride>,
    pub config_dir: Option<PathBuf>,
    pub working_directory: Option<PathBuf>,
    pub github_token: Option<String>,
    pub remote_session: Option<RemoteSessionMode>,
    pub cloud: Option<CloudSessionOptions>,
    pub include_sub_agent_streaming_events: Option<bool>,
    pub commands: Option<Vec<CommandDefinition>>,
    pub session_fs_provider: Option<Arc<dyn SessionFsProvider>>,
    pub handler: Option<Arc<dyn SessionHandler>>,
    pub hooks_handler: Option<Arc<dyn SessionHooks>>,
    pub transform: Option<Arc<dyn SystemMessageTransform>>,
    /* private fields */
}

Configuration for creating a new session via the session.create RPC.

All fields are optional — the CLI applies sensible defaults.

Construction

Two equivalent shapes are supported:

1. Chained builder (preferred for compile-time-known values):

   let cfg = SessionConfig::default()
       .with_client_name("my-app")
       .with_streaming(true)
       .with_enable_config_discovery(true);

2. Direct field assignment (preferred when forwarding Option<T> from upstream code, since with_<field> setters take the inner T, not Option<T>):

   let mut cfg = SessionConfig::default()
       .with_client_name("my-app")
       .with_streaming(true);
   cfg.model = upstream_model;
   cfg.system_message = upstream_system_message;

   Mixing the two is fine: chain the fields you know at compile time, then assign the Option<T> pass-through fields directly. All fields on this struct are pub. This pattern matches the http::request::Parts / hyper::Body::Builder convention in the wider Rust ecosystem.

Field naming across SDKs

Rust field names are snake_case (available_tools, system_message); they round-trip to the camelCase wire protocol via #[serde(rename_all = "camelCase")]. When porting code from the TypeScript, Go, Python, or .NET SDKs — or reading the raw JSON-RPC traces — fields appear as availableTools, systemMessage, etc.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

session_id: Option<SessionId>

Custom session ID. When unset, the CLI generates one.

model: Option<String>

Model to use (e.g. "gpt-4", "claude-sonnet-4").

client_name: Option<String>

Application name sent as User-Agent context.

reasoning_effort: Option<String>

Reasoning effort level (e.g. "low", "medium", "high").

streaming: Option<bool>

Enable streaming token deltas via assistant.message_delta events.

system_message: Option<SystemMessageConfig>

Custom system message configuration.

tools: Option<Vec<Tool>>

Client-defined tool declarations to expose to the agent.

available_tools: Option<Vec<String>>

Allowlist of built-in tool names the agent may use.

excluded_tools: Option<Vec<String>>

Blocklist of built-in tool names the agent must not use.

mcp_servers: Option<HashMap<String, McpServerConfig>>

MCP server configurations passed through to the CLI.

enable_config_discovery: Option<bool>

When true, the CLI runs config discovery (MCP config files, skills, plugins).

request_user_input: Option<bool>

Enable the ask_user tool for interactive user input. Defaults to Some(true) via SessionConfig::default.

request_permission: Option<bool>

Enable permission.request JSON-RPC calls from the CLI. Defaults to Some(true) via SessionConfig::default; the default NoopHandler leaves requests pending for the consumer to resolve.

request_exit_plan_mode: Option<bool>

Enable exitPlanMode.request JSON-RPC calls for plan approval. Defaults to Some(true) via SessionConfig::default.

request_auto_mode_switch: Option<bool>

Enable autoModeSwitch.request JSON-RPC calls. When true, the CLI asks the handler whether to switch to auto model when an eligible rate limit is hit. Defaults to Some(true) via SessionConfig::default. Without this flag, the CLI surfaces the rate-limit error directly without offering the auto-mode switch.

request_elicitation: Option<bool>

Advertise elicitation provider capability. When true, the CLI sends elicitation.requested events that the handler can respond to. Defaults to Some(true) via SessionConfig::default.

skill_directories: Option<Vec<PathBuf>>

Skill directory paths passed through to the GitHub Copilot CLI.

instruction_directories: Option<Vec<PathBuf>>

Additional directories to search for custom instruction files. Forwarded to the CLI; not the same as skill_directories.

disabled_skills: Option<Vec<String>>

Skill names to disable. Skills in this set will not be available even if found in skill directories.

hooks: Option<bool>

Enable session hooks. When true, the CLI sends hooks.invoke RPC requests at key lifecycle points (pre/post tool use, prompt submission, session start/end, errors).

custom_agents: Option<Vec<CustomAgentConfig>>

Custom agents (sub-agents) configured for this session.

default_agent: Option<DefaultAgentConfig>

Configures the built-in default agent. Use excluded_tools to hide tools from the default agent while keeping them available to custom sub-agents that reference them in their tools list.

agent: Option<String>

Name of the custom agent to activate when the session starts. Must match the name of one of the agents in Self::custom_agents.

infinite_sessions: Option<InfiniteSessionConfig>

Configures infinite sessions: persistent workspace + automatic context-window compaction. Enabled by default on the CLI.

provider: Option<ProviderConfig>

Custom model provider (BYOK). When set, the session routes requests through this provider instead of the default Copilot routing.

enable_session_telemetry: Option<bool>

Enables or disables internal session telemetry for this session.

When Some(false), disables session telemetry. When None or Some(true), telemetry is enabled for GitHub-authenticated sessions. When a custom provider is configured, session telemetry is always disabled regardless of this setting. This is independent of ClientOptions::telemetry.

model_capabilities: Option<ModelCapabilitiesOverride>

Per-property overrides for model capabilities, deep-merged over runtime defaults.

config_dir: Option<PathBuf>

Override the default configuration directory location. When set, the session uses this directory for storing config and state.

working_directory: Option<PathBuf>

Working directory for the session. Tool operations resolve relative paths against this directory.

github_token: Option<String>

Per-session GitHub token. Distinct from ClientOptions::github_token, which authenticates the CLI process itself; this token determines the GitHub identity used for content exclusion, model routing, and quota checks for this session.

remote_session: Option<RemoteSessionMode>

Per-session remote behavior control:

• Off — local only, no remote export (default)
• Export — export session events to GitHub without enabling remote steering
• On — export to GitHub AND enable remote steering

cloud: Option<CloudSessionOptions>

Creates a remote session in the cloud instead of a local session. The optional repository is associated with the cloud session.

include_sub_agent_streaming_events: Option<bool>

Forward sub-agent streaming events to this connection. When false, only non-streaming sub-agent events and subagent.* lifecycle events are delivered. Defaults to true on the CLI.

commands: Option<Vec<CommandDefinition>>

Slash commands registered for this session. When the CLI has a TUI, each command appears as /name for the user to invoke and the associated CommandHandler is called when executed.

session_fs_provider: Option<Arc<dyn SessionFsProvider>>

Custom session filesystem provider for this session. Required when the Client was started with ClientOptions::session_fs set. See SessionFsProvider.

handler: Option<Arc<dyn SessionHandler>>

Session-level event handler. The default is NoopHandler — permission requests and external tool calls are left pending for the consumer to resolve. Use with_handler to install a custom handler.

hooks_handler: Option<Arc<dyn SessionHooks>>

Session lifecycle hook handler (pre/post tool use, session start/end, etc.). When set, the SDK auto-enables the wire-level hooks flag. Use with_hooks to install one.

transform: Option<Arc<dyn SystemMessageTransform>>

System-message transform. When set, the SDK injects the matching action: "transform" sections into the system message and routes systemMessage.transform RPC callbacks to it during the session. Use with_transform to install one.

Implementations

impl SessionConfig

pub fn with_handler(self, handler: Arc<dyn SessionHandler>) -> Self

Install a custom SessionHandler for this session.

pub fn with_commands(self, commands: Vec<CommandDefinition>) -> Self

Register slash commands for this session. Each command appears as /name in the CLI’s TUI; the handler is invoked when the user executes the command. Replaces any commands previously set on this config. See CommandDefinition.

pub fn with_session_fs_provider( self, provider: Arc<dyn SessionFsProvider>, ) -> Self

Install a SessionFsProvider backing the session’s filesystem. Required when the Client was started with ClientOptions::session_fs.

pub fn with_hooks(self, hooks: Arc<dyn SessionHooks>) -> Self

Install a SessionHooks handler. Automatically enables the wire-level hooks flag on session creation.

pub fn with_transform(self, transform: Arc<dyn SystemMessageTransform>) -> Self

Install a SystemMessageTransform. The SDK injects the matching action: "transform" sections into the system message and routes systemMessage.transform RPC callbacks to it during the session.

pub fn approve_all_permissions(self) -> Self

Wrap the configured handler so every permission request is auto-approved. Forwards every non-permission event to the inner handler unchanged.

If no handler has been installed via with_handler, wraps a NoopHandler, so declaration-only tools remain pending for manual resolution.

Order-independent: with_handler(...).approve_all_permissions() and approve_all_permissions().with_handler(...) are NOT equivalent — the second form discards the wrap because with_handler overwrites the handler field. Always call approve_all_permissions after with_handler.

pub fn deny_all_permissions(self) -> Self

Wrap the configured handler so every permission request is auto-denied. See approve_all_permissions for ordering and default-handler semantics.

pub fn approve_permissions_if<F>(self, predicate: F) -> Self

where F: Fn(&PermissionRequestData) -> bool + Send + Sync + 'static,

Wrap the configured handler with a closure-based permission policy: predicate is called for each permission request; true approves, false denies. See approve_all_permissions for ordering and default-handler semantics.

pub fn with_session_id(self, id: impl Into<SessionId>) -> Self

Set a custom session ID (when unset, the CLI generates one).

pub fn with_model(self, model: impl Into<String>) -> Self

Set the model identifier (e.g. "claude-sonnet-4").

pub fn with_client_name(self, name: impl Into<String>) -> Self

Set the application name sent as User-Agent context.

pub fn with_reasoning_effort(self, effort: impl Into<String>) -> Self

Set the reasoning effort level (e.g. "low", "medium", "high").

pub fn with_streaming(self, streaming: bool) -> Self

Enable streaming token deltas via assistant.message_delta events.

pub fn with_system_message(self, system_message: SystemMessageConfig) -> Self

Set a custom system message configuration.

pub fn with_tools<I: IntoIterator<Item = Tool>>(self, tools: I) -> Self

Set the client-defined tools to expose to the agent.

pub fn with_available_tools<I, S>(self, tools: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Set the allowlist of built-in tool names the agent may use.

pub fn with_excluded_tools<I, S>(self, tools: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Set the blocklist of built-in tool names the agent must not use.

pub fn with_mcp_servers(self, servers: HashMap<String, McpServerConfig>) -> Self

Set MCP server configurations passed through to the CLI.

pub fn with_enable_config_discovery(self, enable: bool) -> Self

Enable or disable CLI config discovery (MCP config files, skills, plugins).

pub fn with_request_user_input(self, enable: bool) -> Self

Enable the ask_user tool. Defaults to Some(true) via Self::default.

pub fn with_request_permission(self, enable: bool) -> Self

Enable permission.request JSON-RPC calls. Defaults to Some(true).

pub fn with_request_exit_plan_mode(self, enable: bool) -> Self

Enable exitPlanMode.request JSON-RPC calls. Defaults to Some(true).

pub fn with_request_auto_mode_switch(self, enable: bool) -> Self

Enable autoModeSwitch.request JSON-RPC calls. Defaults to Some(true).

pub fn with_request_elicitation(self, enable: bool) -> Self

Advertise elicitation provider capability. Defaults to Some(true).

pub fn with_skill_directories<I, P>(self, paths: I) -> Self

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Set skill directory paths passed through to the CLI.

pub fn with_instruction_directories<I, P>(self, paths: I) -> Self

where I: IntoIterator<Item = P>, P: Into<PathBuf>,

Set additional directories to search for custom instruction files. Forwarded to the CLI on session create; not the same as with_skill_directories.

pub fn with_disabled_skills<I, S>(self, names: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Set the names of skills to disable (overrides skill discovery).

pub fn with_custom_agents<I: IntoIterator<Item = CustomAgentConfig>>( self, agents: I, ) -> Self

Set the custom agents (sub-agents) configured for this session.

pub fn with_default_agent(self, agent: DefaultAgentConfig) -> Self

Configure the built-in default agent.

pub fn with_agent(self, name: impl Into<String>) -> Self

Activate a named custom agent on session start. Must match the name of one of the agents in Self::custom_agents.

pub fn with_infinite_sessions(self, config: InfiniteSessionConfig) -> Self

Configure infinite sessions (persistent workspace + automatic context-window compaction).

pub fn with_provider(self, provider: ProviderConfig) -> Self

Configure a custom model provider (BYOK).

pub fn with_enable_session_telemetry(self, enable: bool) -> Self

Enable or disable internal session telemetry.

See Self::enable_session_telemetry for default and BYOK behavior.

pub fn with_model_capabilities( self, capabilities: ModelCapabilitiesOverride, ) -> Self

Set per-property overrides for model capabilities.

pub fn with_config_dir(self, dir: impl Into<PathBuf>) -> Self

Override the default configuration directory location.

pub fn with_working_directory(self, dir: impl Into<PathBuf>) -> Self

Set the per-session working directory. Tool operations resolve relative paths against this directory.

pub fn with_github_token(self, token: impl Into<String>) -> Self

Set the per-session GitHub token. Distinct from ClientOptions::github_token; this token determines the GitHub identity used for content exclusion, model routing, and quota checks for this session only.

pub fn with_include_sub_agent_streaming_events(self, include: bool) -> Self

Forward sub-agent streaming events to this connection. Defaults to true on the CLI when unset.

pub fn with_remote_session(self, mode: RemoteSessionMode) -> Self

Set per-session remote behavior.

pub fn with_cloud(self, cloud: CloudSessionOptions) -> Self

Create a remote session in the cloud instead of a local session.

Trait Implementations

impl Clone for SessionConfig

fn clone(&self) -> SessionConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SessionConfig

fn default() -> Self

Permission and elicitation flows are enabled by default. When no handler is provided, the SDK installs NoopHandler, so permission and external tool requests remain pending until the consumer responds out-of-band. Callers that want the wire surface fully disabled set these explicitly to Some(false).

impl<'de> Deserialize<'de> for SessionConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SessionConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.