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 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 tools 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 DenyAllHandler refuses all requests so the wire surface is safe out-of-the-box.

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.

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 DenyAllHandler — permission requests are denied; other events are no-ops. 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 DenyAllHandler — useful when you only care about permission policy and want the trait fallback responses for everything else.

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.

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. With Rust’s trait-based handlers, the SDK installs DenyAllHandler when no handler is provided, so these flags being Some(true) means the wire surface advertises the capabilities — and the default handler safely refuses requests. 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.