Struct SessionConfig 

#[non_exhaustive]
pub struct SessionConfig {

    pub session_id: Option<SessionId>,
    pub model: Option<String>,
    pub allowed_models: Option<Vec<String>>,
    pub client_name: Option<String>,
    pub reasoning_effort: Option<String>,
    pub reasoning_summary: Option<ReasoningSummary>,
    pub context_tier: Option<String>,
    pub streaming: Option<bool>,
    pub system_message: Option<SystemMessageConfig>,
    pub ask_user_variant: Option<AskUserVariant>,
    pub tools: Option<Vec<Tool>>,
    pub canvases: Option<Vec<CanvasDeclaration>>,
    pub canvas_handler: Option<Arc<dyn CanvasHandler>>,
    pub request_canvas_renderer: Option<bool>,
    pub request_extensions: Option<bool>,
    pub extension_sdk_path: Option<String>,
    pub extension_info: Option<ExtensionInfo>,
    pub canvas_provider: Option<CanvasProviderIdentity>,
    pub available_tools: Option<Vec<String>>,
    pub excluded_tools: Option<Vec<String>>,
    pub excluded_builtin_agents: Option<Vec<String>>,
    pub included_builtin_skills: Option<Vec<String>>,
    pub mcp_servers: Option<IndexMap<String, McpServerConfig>>,
    pub mcp_oauth_token_storage: Option<String>,
    pub auth_client_id_metadata_url: Option<String>,
    pub enable_config_discovery: Option<bool>,
    pub skip_embedding_retrieval: Option<bool>,
    pub embedding_cache_storage: Option<String>,
    pub organization_custom_instructions: Option<String>,
    pub enable_on_demand_instruction_discovery: Option<bool>,
    pub enable_file_hooks: Option<bool>,
    pub enable_host_git_operations: Option<bool>,
    pub enable_session_store: Option<bool>,
    pub enable_skills: Option<bool>,
    pub enable_mcp_apps: Option<bool>,
    pub github_mcp_tool_config: Option<GitHubMcpToolConfig>,
    pub skill_directories: Option<Vec<PathBuf>>,
    pub instruction_directories: Option<Vec<PathBuf>>,
    pub plugin_directories: Option<Vec<PathBuf>>,
    pub large_output: Option<LargeToolOutputConfig>,
    pub tool_search: Option<ToolSearchConfig>,
    pub disabled_skills: Option<Vec<String>>,
    pub disabled_mcp_servers: 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 capi: Option<CapiSessionOptions>,
    pub providers: Option<Vec<NamedProviderConfig>>,
    pub models: Option<Vec<ProviderModelConfig>>,
    pub enable_session_telemetry: Option<bool>,
    pub enable_citations: Option<bool>,
    pub enable_file_change_tracking: Option<bool>,
    pub session_limits: Option<SessionLimitsConfig>,
    pub model_capabilities: Option<ModelCapabilitiesOverride>,
    pub memory: Option<MemoryConfiguration>,
    pub config_directory: Option<PathBuf>,
    pub working_directory: Option<PathBuf>,
    pub additional_directories: Option<Vec<PathBuf>>,
    pub github_token: Option<String>,
    pub github_token_provider: Option<Arc<dyn GitHubTokenProvider>>,
    pub remote_session: Option<RemoteSessionMode>,
    pub cloud: Option<CloudSessionOptions>,
    pub include_sub_agent_streaming_events: Option<bool>,
    pub commands: Option<Vec<CommandDefinition>>,
    pub feature_flags: Option<HashMap<String, bool>>,
    pub enable_managed_settings: Option<bool>,
    pub managed_settings: Option<ManagedSettings>,
    pub session_fs_provider: Option<Arc<dyn SessionFsProvider>>,
    pub permission_handler: Option<Arc<dyn PermissionHandler>>,
    pub elicitation_handler: Option<Arc<dyn ElicitationHandler>>,
    pub mcp_auth_handler: Option<Arc<dyn McpAuthHandler>>,
    pub user_input_handler: Option<Arc<dyn UserInputHandler>>,
    pub exit_plan_mode_handler: Option<Arc<dyn ExitPlanModeHandler>>,
    pub auto_mode_switch_handler: Option<Arc<dyn AutoModeSwitchHandler>>,
    pub hooks_handler: Option<Arc<dyn SessionHooks>>,
    pub system_message_transform: Option<Arc<dyn SystemMessageTransform>>,
    pub skip_custom_instructions: Option<bool>,
    pub custom_agents_local_only: Option<bool>,
    pub enable_experimental_mode: Option<bool>,
    pub coauthor_enabled: Option<bool>,
    pub manage_schedule_enabled: Option<bool>,
    pub event_buffer_capacity: Option<usize>,
    /* 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); the wire protocol uses camelCase (availableTools, systemMessage). The mapping happens inside SessionConfig::into_wire (crate-private), which builds a separate SessionCreateWire payload. This config struct is no longer itself serializable — the trait-object handler fields (e.g. permission_handler) could never round-trip through serde, so the only legitimate serialization path is now into_wire. 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").

allowed_models: Option<Vec<String>>

Exact model IDs this session may use. When unset, the host imposes no model restriction. The runtime validates configured IDs, rejects an explicit empty list, and intersects the list with applicable model policies.

client_name: Option<String>

Application name sent as User-Agent context.

reasoning_effort: Option<String>

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

reasoning_summary: Option<ReasoningSummary>

Reasoning summary mode for models that support configurable reasoning summaries. Use ReasoningSummary::None to suppress summary output regardless of whether reasoning is enabled.

context_tier: Option<String>

Context window tier for models that support it. Use "long_context" to pin the session to the long-context tier.

streaming: Option<bool>

Enable streaming token deltas via assistant.message_delta events.

system_message: Option<SystemMessageConfig>

Custom system message configuration.

ask_user_variant: Option<AskUserVariant>

Selects the model-facing shape of the built-in ask_user tool.

When omitted, the runtime uses AskUserVariant::Legacy. To use AskUserVariant::Elicitation, also install an ElicitationHandler.

tools: Option<Vec<Tool>>

Client-defined tool declarations to expose to the agent.

canvases: Option<Vec<CanvasDeclaration>>

Canvas declarations this connection provides to the runtime.

canvas_handler: Option<Arc<dyn CanvasHandler>>

Provider-side canvas lifecycle handler. The SDK routes inbound canvas.open / canvas.close / canvas.action.invoke requests to this handler. Use with_canvas_handler to install one.

request_canvas_renderer: Option<bool>

Request canvas renderer tools for this connection.

request_extensions: Option<bool>

Request extension tools and dispatch for this connection.

extension_sdk_path: Option<String>

Optional override path to a copilot-sdk/ folder to inject into extension subprocesses for this session. Invalid paths fall back to the bundled SDK; takes precedence over the host’s default.

extension_info: Option<ExtensionInfo>

Stable extension identity for canvas/tool providers on this connection.

canvas_provider: Option<CanvasProviderIdentity>

Stable identity for a host/SDK connection that supplies built-in canvases, so they survive reconnect and CLI restart.

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.

excluded_builtin_agents: Option<Vec<String>>

Names of built-in agents to exclude from the session.

Excluded built-in agents are hidden from discovery and cannot be selected or invoked unless a custom agent with the same name is configured.

included_builtin_skills: Option<Vec<String>>

Built-in skill names to include in the session. In ClientMode::Empty, None excludes all runtime-bundled skills; Some opts the named built-ins back in.

mcp_servers: Option<IndexMap<String, McpServerConfig>>

MCP server configurations passed through to the CLI.

mcp_oauth_token_storage: Option<String>

Controls how MCP OAuth tokens are stored for this session.

• "persistent" — tokens are stored in the OS keychain (shared across sessions).
• "in-memory" — tokens are stored in memory and discarded when the session ends.

Defaults to "in-memory" when the client is in crate::ClientMode::Empty, applied automatically at session creation/resume time. None means no explicit value is set and the runtime default takes effect.

auth_client_id_metadata_url: Option<String>

URL identifying this host’s OAuth client metadata document.

Authorization servers that support client ID metadata documents can use this URL as the MCP OAuth client ID. When unset, the SDK does not supply a first-party host identity and the runtime uses its generic, session-isolated OAuth client behavior.

enable_config_discovery: Option<bool>

Enables runtime discovery of supported configuration. Explicitly supplied configuration takes precedence over discovered values.

skip_embedding_retrieval: Option<bool>

When true, skips embedding retrieval for this session.

embedding_cache_storage: Option<String>

Controls how the embedding cache is stored for this session. "persistent" caches on disk; "in-memory" discards when session ends.

organization_custom_instructions: Option<String>

Organization-level custom instructions to apply to this session.

enable_on_demand_instruction_discovery: Option<bool>

When true, enables on-demand instruction discovery for this session.

enable_file_hooks: Option<bool>

When true, enables file hooks for this session.

enable_host_git_operations: Option<bool>

When true, allows host Git operations for this session.

enable_session_store: Option<bool>

When true, enables the session store for this session.

enable_skills: Option<bool>

When true, enables skills for this session.

enable_mcp_apps: Option<bool>

Experimental. This option is part of an experimental wire-protocol surface (SEP-1865) and may change or be removed in a future release.

Enable MCP Apps (SEP-1865) UI passthrough on this session.

When true and the runtime has MCP Apps enabled (via the MCP_APPS feature flag or COPILOT_MCP_APPS=true environment override), the runtime adds the mcp-apps capability to the session, which causes it to advertise the extensions.io.modelcontextprotocol/ui extension to MCP servers (so they expose _meta.ui.resourceUri on tools) and to expose the session.rpc.mcp.apps.{listTools,callTool,readResource,setHostContext, getHostContext,diagnose} JSON-RPC methods.

If the runtime gate is off, the opt-in is silently dropped server-side (the runtime logs a warning); the session is created normally but the MCP Apps surface is unavailable. Inspect the runtime’s capabilities.ui.mcpApps on the create/resume response to detect this.

SDK consumers MUST set this to true only when they have an iframe renderer that can display ui:// MCP App bundles. Setting it without a renderer will cause MCP servers to register UI-enabled tool variants the consumer cannot display.

Defaults to None (treated as false).

github_mcp_tool_config: Option<GitHubMcpToolConfig>

Configuration for the built-in GitHub MCP server.

disable_form_deferral only applies to that server and only has an effect when MCP Apps and form-backed GitHub tools are enabled.

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.

plugin_directories: Option<Vec<PathBuf>>

Open Plugin directory paths passed through to the CLI.

large_output: Option<LargeToolOutputConfig>

Configuration for large tool output handling, forwarded to the CLI.

tool_search: Option<ToolSearchConfig>

Overrides the runtime’s built-in tool-search behavior, which defers rarely used tools behind a searchable index. When unset, the runtime default applies.

disabled_skills: Option<Vec<String>>

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

disabled_mcp_servers: Option<Vec<String>>

Exact MCP server names to disable for this session. Disabled servers are not started or authenticated on create or cold resume; a resident resume cannot stop servers that are already running.

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.

capi: Option<CapiSessionOptions>

Provider-scoped CAPI session options.

Use this to opt out of the default WebSocket transport for CAPI Responses API calls, equivalent to setting COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES.

providers: Option<Vec<NamedProviderConfig>>

Experimental. This field is part of an experimental multi-provider BYOK surface and may change or be removed in a future release.

Named BYOK provider connections. Additive to the default Copilot routing — unlike provider, these do not switch the whole session to BYOK. Referenced by models.

models: Option<Vec<ProviderModelConfig>>

Experimental. This field is part of an experimental multi-provider BYOK surface and may change or be removed in a future release.

BYOK model definitions, each referencing a providers entry by name. Selectable under the id provider/id.

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.

enable_citations: Option<bool>

Experimental. Enables native model citations for supported providers.

enable_file_change_tracking: Option<bool>

Opts in to capturing file changes from the first turn for session rewind and cumulative session diff.

session_limits: Option<SessionLimitsConfig>

Experimental. Limits applied to this session’s current accounting window.

model_capabilities: Option<ModelCapabilitiesOverride>

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

memory: Option<MemoryConfiguration>

Per-session configuration for the runtime memory feature.

config_directory: 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.

additional_directories: Option<Vec<PathBuf>>

Additional directories the agent may access beyond the working directory. Relative paths resolve against the session working directory. Re-supply them when resuming a session.

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.

github_token_provider: Option<Arc<dyn GitHubTokenProvider>>

Provider used to acquire rotating GitHub tokens for this session.

Mutually exclusive with github_token. The callback receives the effective host, optional assigned session ID, and acquisition reason; its opaque registration ID is never exposed.

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.

feature_flags: Option<HashMap<String, bool>>

Feature-flag values resolved by the host for this session.

Re-supply these values through ResumeSessionConfig::feature_flags when resuming after a CLI process restart. Set via with_feature_flags.

enable_managed_settings: Option<bool>

Opt-in: when Some(true), the runtime self-fetches enterprise managed settings (bypass-permissions policy) at session bootstrap using the session’s static github_token or github_token_provider. Requires one of those credentials; if both are omitted, the runtime is expected to reject session creation (fail-closed). When None, behaves exactly as before. Set via with_enable_managed_settings.

managed_settings: Option<ManagedSettings>

Optional managed-settings layer injected at session bootstrap. Currently carries a permissions object that composes restrictively with any server- or device-level managed settings. This layer is startup-only and is not persisted: it must be re-supplied on resume to remain in effect. Can be combined with enable_managed_settings. Serialized on the wire as managedSettings. Set via with_managed_settings.

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.

permission_handler: Option<Arc<dyn PermissionHandler>>

Optional permission-request handler. When None, the SDK sends requestPermission: false on the wire so the runtime does not emit permission.requested broadcasts to this client.

elicitation_handler: Option<Arc<dyn ElicitationHandler>>

Optional elicitation-request handler. When None, requestElicitation: false goes on the wire.

mcp_auth_handler: Option<Arc<dyn McpAuthHandler>>

Optional MCP OAuth request handler. When set, the SDK can satisfy MCP server OAuth requests with host-acquired token data or cancellation.

user_input_handler: Option<Arc<dyn UserInputHandler>>

Optional handler for the legacy question-and-answer ask_user variant. When None, requestUserInput: false goes on the wire, so this client cannot handle legacy user-input requests.

exit_plan_mode_handler: Option<Arc<dyn ExitPlanModeHandler>>

Optional exit-plan-mode handler. When None, requestExitPlanMode: false goes on the wire.

auto_mode_switch_handler: Option<Arc<dyn AutoModeSwitchHandler>>

Optional auto-mode-switch handler. When None, requestAutoModeSwitch: false goes on the wire.

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.

system_message_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_system_message_transform to install one.

skip_custom_instructions: Option<bool>

Whether to skip loading custom-instruction sources for this session. Applied via session.options.update after create/resume. Defaults to true in crate::ClientMode::Empty when unset.

custom_agents_local_only: Option<bool>

Whether to constrain custom agents to local-only execution. Sent with the initial create request and maintained via session.options.update. Defaults to true in crate::ClientMode::Empty when unset.

enable_experimental_mode: Option<bool>

Controls whether the session enables experimental features.

Defaults to false in crate::ClientMode::Empty when unset; in copilot-cli mode, leaving this unset lets the runtime decide.

coauthor_enabled: Option<bool>

Whether to include the Co-authored-by trailer in commit messages. Applied via session.options.update after create/resume. Defaults to false in crate::ClientMode::Empty when unset.

manage_schedule_enabled: Option<bool>

Whether to expose the manage_schedule tool. Applied via session.options.update after create/resume. Defaults to false in crate::ClientMode::Empty when unset.

event_buffer_capacity: Option<usize>

Capacity of the per-session broadcast buffer backing Session::subscribe and PreparedSession::subscribe.

Runtime-only — never sent on the wire. Defaults to DEFAULT_EVENT_BUFFER_CAPACITY when unset. Must be non-zero; Some(0) is rejected with ErrorKind::InvalidConfig by Client::prepare_session.

The buffer is finite: subscribers that fall behind observe Lagged rather than applying backpressure to the event loop. Raise this when a consumer needs a lossless view of a large startup burst without draining concurrently.

Implementations

impl SessionConfig

pub fn with_permission_handler( self, handler: Arc<dyn PermissionHandler>, ) -> Self

Install a PermissionHandler for this session. When omitted, the SDK sends requestPermission: false on the wire and the runtime short-circuits permission prompts for this client.

pub fn with_elicitation_handler( self, handler: Arc<dyn ElicitationHandler>, ) -> Self

Install an ElicitationHandler. When omitted, the SDK sends requestElicitation: false on the wire.

pub fn with_mcp_auth_handler(self, handler: Arc<dyn McpAuthHandler>) -> Self

Install an McpAuthHandler for host-provided MCP OAuth tokens.

pub fn with_user_input_handler(self, handler: Arc<dyn UserInputHandler>) -> Self

Install a UserInputHandler for the legacy question-and-answer ask_user variant.

pub fn with_ask_user_variant(self, variant: AskUserVariant) -> Self

Select the model-facing shape of the built-in ask_user tool.

pub fn with_exit_plan_mode_handler( self, handler: Arc<dyn ExitPlanModeHandler>, ) -> Self

Install an ExitPlanModeHandler.

pub fn with_auto_mode_switch_handler( self, handler: Arc<dyn AutoModeSwitchHandler>, ) -> Self

Install an AutoModeSwitchHandler.

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_system_message_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

Auto-approve every permission request on this session. Stored as a policy that’s applied at Client::create_session time, so order with with_permission_handler is irrelevant.

pub fn deny_all_permissions(self) -> Self

Auto-deny every permission request on this session. See approve_all_permissions.

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

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

Apply a closure-based permission policy: predicate returns true to approve, false to deny. See approve_all_permissions for ordering 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_allowed_models<I, S>(self, models: I) -> Self

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

Restrict this session to the provided exact model IDs.

Passing an empty iterator sends an explicit empty list, which the runtime rejects.

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_reasoning_summary(self, summary: ReasoningSummary) -> Self

Set reasoning_summary.

pub fn with_context_tier(self, tier: impl Into<String>) -> Self

Set the context window tier (e.g. "default", "long_context").

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_canvases<I: IntoIterator<Item = CanvasDeclaration>>( self, canvases: I, ) -> Self

Set canvas declarations for this connection. The runtime advertises these to the agent; install a CanvasHandler via with_canvas_handler to receive the resulting provider callbacks.

pub fn with_canvas_handler(self, handler: Arc<dyn CanvasHandler>) -> Self

Install the provider-side CanvasHandler for this session.

pub fn with_request_canvas_renderer(self, request: bool) -> Self

Request host canvas renderer tools for this connection.

pub fn with_request_extensions(self, request: bool) -> Self

Request extension tools and dispatch for this connection.

pub fn with_extension_sdk_path(self, path: impl Into<String>) -> Self

Override the bundled @github/copilot-sdk drop injected into extension subprocesses for this session. Invalid paths fall back to the bundled SDK silently.

pub fn with_extension_info(self, extension_info: ExtensionInfo) -> Self

Set stable extension identity metadata for this connection.

pub fn with_canvas_provider( self, canvas_provider: CanvasProviderIdentity, ) -> Self

Set the canvas provider identity for this connection so host-supplied canvases survive reconnect and CLI restart.

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_excluded_builtin_agents<I, S>(self, agents: I) -> Self

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

Set the built-in agent names to exclude from the session.

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

Set MCP server configurations passed through to the CLI.

pub fn with_mcp_oauth_token_storage(self, mode: impl Into<String>) -> Self

Set MCP OAuth token storage mode.

• "persistent" — tokens stored in the OS keychain.
• "in-memory" — tokens discarded when the session ends.

Defaults to "in-memory" when the client is in crate::ClientMode::Empty, applied automatically at session creation/resume time.

pub fn with_auth_client_id_metadata_url(self, url: impl Into<String>) -> Self

Set the URL identifying this host’s OAuth client metadata document.

pub fn with_embedding_cache_storage( self, embedding_cache_storage: impl Into<String>, ) -> Self

Set embedding cache storage mode.

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

Enables runtime discovery of supported configuration. Explicitly supplied configuration takes precedence over discovered values.

pub fn with_skip_embedding_retrieval(self, value: bool) -> Self

Set Self::skip_embedding_retrieval.

pub fn with_organization_custom_instructions( self, instructions: impl Into<String>, ) -> Self

Set Self::organization_custom_instructions.

pub fn with_enable_on_demand_instruction_discovery(self, value: bool) -> Self

Set Self::enable_on_demand_instruction_discovery.

pub fn with_enable_file_hooks(self, value: bool) -> Self

Set Self::enable_file_hooks.

pub fn with_enable_host_git_operations(self, value: bool) -> Self

Set Self::enable_host_git_operations.

pub fn with_enable_session_store(self, value: bool) -> Self

Set Self::enable_session_store.

pub fn with_enable_skills(self, value: bool) -> Self

Set Self::enable_skills.

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

Experimental. This method is part of an experimental wire-protocol surface (SEP-1865) and may change or be removed in a future release.

Enable MCP Apps (SEP-1865) UI passthrough on this session. Defaults to None (treated as false). See SessionConfig::enable_mcp_apps.

pub fn with_github_mcp_tool_config(self, config: GitHubMcpToolConfig) -> Self

Set the built-in GitHub MCP server configuration.

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_included_builtin_skills<I, S>(self, names: I) -> Self

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

Set the runtime-bundled skill allowlist.

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_plugin_directories<I, P>(self, paths: I) -> Self

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

Set Open Plugin directory paths passed through to the CLI on session create.

pub fn with_large_output(self, config: LargeToolOutputConfig) -> Self

Set the LargeToolOutputConfig forwarded to the CLI on session create.

pub fn with_tool_search(self, config: ToolSearchConfig) -> Self

Set the ToolSearchConfig overriding the runtime’s built-in tool-search behavior on session create.

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_disabled_mcp_servers<I, S>(self, names: I) -> Self

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

Set exact MCP server names to disable for this session.

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_capi(self, capi: CapiSessionOptions) -> Self

Configure provider-scoped CAPI session options.

pub fn with_providers(self, providers: Vec<NamedProviderConfig>) -> Self

Experimental. This method is part of an experimental multi-provider BYOK surface and may change or be removed in a future release.

Set the named BYOK provider connections (additive multi-provider registry). Attach models referencing these with Self::with_models.

pub fn with_models(self, models: Vec<ProviderModelConfig>) -> Self

Experimental. This method is part of an experimental multi-provider BYOK surface and may change or be removed in a future release.

Set the BYOK model definitions, each referencing a named provider supplied via Self::with_providers.

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_enable_citations(self, enable: bool) -> Self

Experimental. Enable native model citations for supported providers.

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

Opt in to capturing file changes from the first turn for session rewind and cumulative session diff.

pub fn with_session_limits(self, limits: SessionLimitsConfig) -> Self

Experimental. Set limits for this session’s current accounting window.

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

Set per-property overrides for model capabilities.

pub fn with_memory(self, memory: MemoryConfiguration) -> Self

Configure the runtime memory feature for this session.

pub fn with_config_directory(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_additional_directories<I, P>(self, paths: I) -> Self

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

Set directories the agent may access beyond the working 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_github_token_provider( self, provider: Arc<dyn GitHubTokenProvider>, ) -> Self

Install a rotating GitHub token provider for this session.

The provider must return a positive remaining lifetime in seconds when its callback completes. Production GitHub tokens typically last eight hours. This option is mutually exclusive with with_github_token.

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.

pub fn with_skip_custom_instructions(self, value: bool) -> Self

Set Self::skip_custom_instructions.

pub fn with_custom_agents_local_only(self, value: bool) -> Self

Set Self::custom_agents_local_only.

pub fn with_enable_experimental_mode( self, enable_experimental_mode: bool, ) -> Self

Set enable_experimental_mode.

pub fn with_coauthor_enabled(self, value: bool) -> Self

Set Self::coauthor_enabled.

pub fn with_manage_schedule_enabled(self, value: bool) -> Self

Set Self::manage_schedule_enabled.

pub fn with_feature_flags(self, feature_flags: HashMap<String, bool>) -> Self

Set feature-flag values resolved by the host for this session.

pub fn with_event_buffer_capacity(self, capacity: usize) -> Self

Set Self::event_buffer_capacity.

A capacity of 0 is rejected with ErrorKind::InvalidConfig by Client::prepare_session and Client::create_session; the value is never clamped.

pub fn with_enable_managed_settings(self, enabled: bool) -> Self

Opt the runtime into self-fetching enterprise managed settings (bypass-permissions policy) at session bootstrap using the session’s static github_token or github_token_provider. Requires one of those credentials; if both are omitted, the runtime is expected to reject session creation (fail-closed).

pub fn with_managed_settings(self, managed_settings: ManagedSettings) -> Self

Inject a managed-settings layer (currently permission rules) at session bootstrap. This layer is startup-only and is not persisted, so it must be re-supplied on resume to remain in effect. Can be combined with with_enable_managed_settings.

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

All wire-level “request” flags and handler fields start unset. Install a PermissionHandler via with_permission_handler and the SDK derives requestPermission: true on the wire at Client::create_session time.