SessionStartParams
session/start params.
Fields and variants
Section titled “Fields and variants”approvalModeapprovalRules— ExperimentalcommandIdconfiglimits— ExperimentalmodelIdpermissionProfilepreviousSessionIdproviderIdrecoveryModesessionIdspawnedByswitchPolicy— ExperimentalworkspaceRootworkspaceRootsworktree— Experimental
Source
schema/msp/experimental/msp.schema.json#/types/SessionStartParams
{ "description": "`session/start` params.", "properties": { "approvalMode": { "anyOf": [ { "$ref": "#/$defs/ApprovalMode" }, { "type": "null" } ], "description": "The session's starting approval mode; server default when omitted or\nexplicit `null` — both spellings select the default.\nSelect, never create — the value names a mode the host's configuration\nalready defines. This is the only surface that\ndeclares a non-interactive run's policy." }, "approvalRules": { "description": "The session's client-supplied shell prefix allow-rules: `{argvPrefix}` objects in the\n`ShellPrefixSuggestion.argv_prefix` shape. Omitted means no client\nrules. Explicit `null` is invalid params; an empty array is an explicit\nempty set. Until the served-handler slice, a host refuses any spelled\n`approvalRules` on `session/start`/`fork`/`resume` with `-32602`;\nclients omit it.\n**Experimental** (`session/start.approvalRules`).", "items": { "$ref": "#/$defs/ClientApprovalRule" }, "type": "array", "x-msp-descriptor": "session/start.approvalRules", "x-msp-stability": "experimental" }, "commandId": { "description": "The idempotency handle (UUIDv7). Required; the server never\nmints one.", "type": "string" }, "config": { "$ref": "#/$defs/SessionConfig", "description": "Reserved for future per-session overrides; only its `mcpServers` member\nis admitted." }, "limits": { "$ref": "#/$defs/SessionLimitsChoice", "description": "The per-session restriction: the axes this session chooses, each at or below\nthe host ceiling. **Experimental, socket-only** (`session/start.limits`;\nunopted callers are refused `-32602`, as are opted callers on hosts\nwith no limits regime). Absent means the default on every axis —\nthe daemon default for trust (untrusted, except trusted under\n`--trust-workspace --listen`, ADR 59770 D4a), the daemon's own\nposture for the sandbox axes (the ceiling, unless\n`--allow-session-posture` widens the ceiling above it). A choice\nwider than the ceiling on any axis refuses the\nstart `-32028 limitsAboveMax` naming every too-wide axis. An equal or\ntighter choice is what the session runs and reports, with two\nexceptions refused `-32602`: on a daemon whose default sandbox is\noff, a start naming `sandboxEnabled: true` without `sandboxNetwork`,\nor a network restriction (`restricted` or `proxy-only`) without\nnaming `sandboxEnabled`, until settles how a session turns the\nsandbox on there, and a network restriction beside an explicit\n`sandboxEnabled: false`, which never turns it on and stays refused\nwhile is open: drop the restriction, since a sandbox-off\nsession has no network to restrict\n(`data.reason: \"tighterSandboxUnserved\"` for all three); and under\n`--trust-workspace --listen` without `--allow-session-posture`, an\nexplicit `workspaceTrusted: false`, naming the axis. Elsewhere a\nnetwork restriction beside `sandboxEnabled: false` restricts nothing:\nwith the sandbox off the network is not sandboxed (`sandboxNetwork`\nreports `enabled`).", "x-msp-descriptor": "session/start.limits", "x-msp-stability": "experimental" }, "modelId": { "description": "Initial model; server default when omitted.", "type": "string" }, "permissionProfile": { "description": "The new session's initial permission profile: a profile id the host catalog already\nadmits — the rows `permissionProfile/list` serves without\n`sessionId`. Select, never create. Omitted means today's behavior: the\nhost's configured default under native admission, unchanged. An id\nthe catalog does not carry, or one it serves unavailable, refuses the\nstart `commandRejected` (-32030; `permission_profile_unknown` /\n`permission_profile_unavailable`) before any durable byte, and an\nephemeral host refuses any id (`permission_profile_ephemeral_fixed`).\n`session/fork` does not admit the member; `session/resume` admits it\nas the launch pick. Explicit `null` is invalid\nparams: the set of members that tolerate `null` is\nclosed and excludes this one, exactly as it excludes `workspaceRoots`.", "type": "string" }, "previousSessionId": { "description": "The `/new` predecessor link:\nthe outgoing session this start succeeds. Any syntactically valid\nsession UUID; there is no existence check, so a link to a session that\nis gone still commits. Omitted means a true root. Explicit `null` is\ninvalid params.", "type": "string" }, "providerId": { "description": "Initial provider routing; server default when omitted or explicit\n`null` — both spellings select the default.", "type": [ "string", "null" ] }, "recoveryMode": { "$ref": "#/$defs/RecoveryMode", "description": "Recovery choice for this construction; omission keeps legacy behavior.\nExplicit null is invalid." }, "sessionId": { "description": "Exact identity for this new root session. When omitted the server\nmints a UUIDv7. This field never selects an existing session: a\nretained or reserved id is rejected `commandRejected` with reason\n`session_id_conflict`.", "type": "string" }, "spawnedBy": { "$ref": "#/$defs/SessionSpawnedBy", "description": "The session that opens this one,\nin the `Session.spawnedBy` shape: a spawner that starts a worker\nsession over MSP names its own session here. The host writes it once\ninto the new session's creation record, as a worker process records\nits environment hand-over, and `session/list` / `session/read` serve it\nback as `Session.spawnedBy`; `session/resume` never takes it.\n**Additive-optional** and **provenance only**. A value the\nhost cannot use (a `parentSessionId` that is not a session id, a\nmalformed member) records nothing and never refuses the start; an\nunusable `project` or `thread` is dropped on its own. Hosts that\npredate the member ignore it." }, "switchPolicy": { "$ref": "#/$defs/SwitchPolicy", "description": "What happens to the `previousSessionId` predecessor's unfinished\nbackground work. **Experimental** (`session/start.switchPolicy`; unopted\ncallers are refused `-32602`). `kill` cancels the predecessor's\nunfinished work once the new start is durable, as the gate-off\n`/new` does; `keep` ends its persistent monitors only. A policy\nwithout the link is invalid params, and so is explicit `null`.\nOmitted means no policy: the start records `keep`, exactly as\ntoday.", "x-msp-descriptor": "session/start.switchPolicy", "x-msp-stability": "experimental" }, "workspaceRoot": { "description": "Absolute path, folded into the first metadata record.", "type": "string" }, "workspaceRoots": { "description": "The session's initial runtime workspace-root set: ordered absolute\ncanonical existing directory paths; the first root is the CWD and\nplays the primary-root role; every root receives the ADR 11237\n`:workspace_roots` rules; extra roots grant no Project Trust. When\n`workspaceRoot` is also present the two must name the same folder,\ncompared on canonical forms (the raw `workspaceRoot` is\ncanonicalized first; ADR 37313 D9), or the request is invalid\nparams, and so is explicit `null`. Omitted preserves single-root\nbehavior.", "items": { "type": "string" }, "type": "array" }, "worktree": { "$ref": "#/$defs/WorktreeStartRequest", "description": "Ask for a created worktree or attach an existing one. **Experimental**\n(`session/start.worktree`; unopted callers are refused `-32602`). Absent\nmeans no worktree — the start proceeds exactly as today.", "x-msp-descriptor": "session/start.worktree", "x-msp-stability": "experimental" } }, "required": [ "commandId" ], "type": "object"}