session/start

Creates a brand-new session, loads it on this host, durably records the start, and auto-subscribes this connection.

Parameters

Type: SessionStartParams

session/start params.

Field	Type	Stability	Presence	Description
approvalMode	ApprovalMode | null		optional	The session’s starting approval mode; server default when omitted or explicit null — both spellings select the default. Select, never create — the value names a mode the host’s configuration already defines. This is the only surface that declares a non-interactive run’s policy.
approvalRules	ClientApprovalRule[]	Experimental	optional	The session’s client-supplied shell prefix allow-rules: {argvPrefix} objects in the ShellPrefixSuggestion.argv_prefix shape. Omitted means no client rules. Explicit null is invalid params; an empty array is an explicit empty set. Until the served-handler slice, a host refuses any spelled approvalRules on session/start/fork/resume with -32602; clients omit it. Experimental (session/start.approvalRules).
commandId	string		required	The idempotency handle (UUIDv7). Required; the server never mints one.
config	SessionConfig		optional	Reserved for future per-session overrides; only its mcpServers member is admitted.
limits	SessionLimitsChoice	Experimental	optional	The per-session restriction: the axes this session chooses, each at or below the host ceiling. Experimental, socket-only (session/start.limits; unopted callers are refused -32602, as are opted callers on hosts with no limits regime). Absent means the default on every axis — the daemon default for trust (untrusted, except trusted under --trust-workspace --listen, ADR 59770 D4a), the daemon’s own posture for the sandbox axes (the ceiling, unless --allow-session-posture widens the ceiling above it). A choice wider than the ceiling on any axis refuses the start -32028 limitsAboveMax naming every too-wide axis. An equal or tighter choice is what the session runs and reports, with two exceptions refused -32602: on a daemon whose default sandbox is off, a start naming sandboxEnabled: true without sandboxNetwork, or a network restriction (restricted or proxy-only) without naming sandboxEnabled, until settles how a session turns the sandbox on there, and a network restriction beside an explicit sandboxEnabled: false, which never turns it on and stays refused while is open: drop the restriction, since a sandbox-off session has no network to restrict (data.reason: "tighterSandboxUnserved" for all three); and under --trust-workspace --listen without --allow-session-posture, an explicit workspaceTrusted: false, naming the axis. Elsewhere a network restriction beside sandboxEnabled: false restricts nothing: with the sandbox off the network is not sandboxed (sandboxNetwork reports enabled).
modelId	string		optional	Initial model; server default when omitted.
permissionProfile	string		optional	The new session’s initial permission profile: a profile id the host catalog already admits — the rows permissionProfile/list serves without sessionId. Select, never create. Omitted means today’s behavior: the host’s configured default under native admission, unchanged. An id the catalog does not carry, or one it serves unavailable, refuses the start commandRejected (-32030; permission_profile_unknown / permission_profile_unavailable) before any durable byte, and an ephemeral host refuses any id (permission_profile_ephemeral_fixed). session/fork does not admit the member; session/resume admits it as the launch pick. Explicit null is invalid params: the set of members that tolerate null is closed and excludes this one, exactly as it excludes workspaceRoots.
previousSessionId	string		optional	The /new predecessor link: the outgoing session this start succeeds. Any syntactically valid session UUID; there is no existence check, so a link to a session that is gone still commits. Omitted means a true root. Explicit null is invalid params.
providerId	string | null		optional	Initial provider routing; server default when omitted or explicit null — both spellings select the default.
recoveryMode	RecoveryMode		optional	Recovery choice for this construction; omission keeps legacy behavior. Explicit null is invalid.
sessionId	string		optional	Exact identity for this new root session. When omitted the server mints a UUIDv7. This field never selects an existing session: a retained or reserved id is rejected commandRejected with reason session_id_conflict.
spawnedBy	SessionSpawnedBy		optional	The session that opens this one, in the Session.spawnedBy shape: a spawner that starts a worker session over MSP names its own session here. The host writes it once into the new session’s creation record, as a worker process records its environment hand-over, and session/list / session/read serve it back as Session.spawnedBy; session/resume never takes it. Additive-optional and provenance only. A value the host cannot use (a parentSessionId that is not a session id, a malformed member) records nothing and never refuses the start; an unusable project or thread is dropped on its own. Hosts that predate the member ignore it.
switchPolicy	SwitchPolicy	Experimental	optional	What happens to the previousSessionId predecessor’s unfinished background work. Experimental (session/start.switchPolicy; unopted callers are refused -32602). kill cancels the predecessor’s unfinished work once the new start is durable, as the gate-off /new does; keep ends its persistent monitors only. A policy without the link is invalid params, and so is explicit null. Omitted means no policy: the start records keep, exactly as today.
workspaceRoot	string		optional	Absolute path, folded into the first metadata record.
workspaceRoots	string[]		optional	The session’s initial runtime workspace-root set: ordered absolute canonical existing directory paths; the first root is the CWD and plays the primary-root role; every root receives the ADR 11237 :workspace_roots rules; extra roots grant no Project Trust. When workspaceRoot is also present the two must name the same folder, compared on canonical forms (the raw workspaceRoot is canonicalized first; ADR 37313 D9), or the request is invalid params, and so is explicit null. Omitted preserves single-root behavior.
worktree	WorktreeStartRequest	Experimental	optional	Ask for a created worktree or attach an existing one. Experimental (session/start.worktree; unopted callers are refused -32602). Absent means no worktree — the start proceeds exactly as today.

Source

schema/msp/experimental/msp.schema.json#/methods/session~2Fstart

{
  "description": "Creates a brand-new session, loads it on this host, durably records the start, and auto-subscribes this connection.",
  "params": {
    "$ref": "#/$defs/SessionStartParams"
  },
  "result": {
    "$ref": "#/$defs/SessionStartResult"
  }
}