Skip to main content

Module msp

Module msp 

Source
Expand description

Stable Muse Session Protocol (MSP) wire types.

Serde names equal the stable schema names; use these types and never rename an MSP field or variant by hand.

Structs§

AbnormalEnd
abnormalEnd on session/resume: the load found the session’s latest serve segment without a clean end and recorded (or had already recorded) the crash_inferred backstop.
AdmissionResolutionSummary
Winning terminal returned to a losing admission/decide command: resolvedBy is omitted on timeout.
ApprovalAmendment
The policy rule a decision created, in display form; the full rule is not included.
ApprovalChange
The change an approval/updated event reports. kind says what happened, and only the fields for that kind are present.
ApprovalChoice
One option the server offers for deciding an approval. Clients pick one and send its choiceId in approval/decide; they never build their own.
ApprovalCuaCardFacts
One Computer Use card’s facts. Empty collections and absent rows are omitted, never null.
ApprovalCuaDataFact
One piece of data the call would send. An open union on kind (secret, or other for a row the host can’t word); a client shows other and any kind it doesn’t know as a generic data row.
ApprovalCuaMask
A secret’s mask: a vendor token’s prefix and last 4 characters (ghp_…3f9a), a named value’s name and length (password=… (12 chars)), or the length alone; all absent names the kind only.
ApprovalCuaPage
The page’s full host, no path or query.
ApprovalCuaPoint
A point in the model’s 0–1000 coordinates.
ApprovalCuaStep
One consequential step. A client renders “Step N: “
ApprovalDecideParams
approval/decide params: the decision. A standard command — requires the session loaded on this host, requires commandId, durable intake before ack, value-identical replay.
ApprovalDecideResult
approval/decide result. Admission-ack rules still apply: the authoritative outcome is approval/resolved / approval/updated on the view stream.
ApprovalListPendingParams
approval/listPending params: the pull dual of the re-issued requests. A log-fold read — no lease, works on loaded and unloaded sessions, never subscribes.
ApprovalListPendingResult
approval/listPending result. Ordering is by opening viewCursor; empty arrays when nothing is pending. The result is point-in-time — to act on it race-safely, approval/decide carries the requirementId guard regardless of how the client learned the state.
ApprovalOrigin
What triggered a tool action, shown so the user can judge it. It is display-only and untrusted, and policy rules never match on it.
ApprovalRequestParams
Full params shared by approval/request and approval/requested.
ApprovalRequirementRef
Identifies one requirement of an approval: for a shell approval, one stage. A client sends it back as requirementId in approval/decide, and a stale-requirement error names the current one.
ApprovalResolutionSummary
Winning terminal returned to a losing approval/decide command.
ApprovalResolvedParams
approval/resolved params: the first durable terminal decision.
ApprovalStage
One stage of a shell approval: a single command from the pipeline or command list, approved separately from the others.
ApprovalStageEvidence
How one stage of a shell approval was resolved when the decision became final.
ApprovalStageResolution
Whether a shell stage still needs a decision, or how it was satisfied. Satisfied stages are included so a client can show progress.
ApprovalSubagentOrigin
Child (native subagent) provenance for an approval projected onto the PARENT session’s approval plane: identifies the originating child run/agent so a client can attribute the prompt. Omitted (skip_serializing_if) on the parent’s own approvals, so pre-existing parent frames stay byte-identical.
ApprovalSubject
Open approval subject union. Unknown kinds are rendered generically and never auto-approved by clients.
ApprovalSuggestedPrefix
A suggested always-allow rule for a shell stage: commands starting with argvPrefix would run in this workspace without asking.
ApprovalUpdatedParams
approval/updated params: the refreshed pending view plus one change.
AutoRecovery
autoRecovery on session/resume (amendment 26387/68619, owner decision G-23): the outcome of this resume’s own load when it ran with the resume_auto_recover gate on (G-37: whatever the session’s recoveryMode). A resume’s autoRecover: false is reported here as refused with reason optedOut.
BackgroundStatus
The backgrounded-row payload for a running toolCall item: the presentation state plus the live status text the row body renders. Experimental — stable clients ignore the member.
BackgroundTarget
One call’s live background-target record: exactly the runtime snapshot’s four facts, no new nouns.
BackgroundTerminalCompletion
backgroundTerminalCompletion: the facts the Finished cell renders. The fold reads them from the inbox terminal record and the backgrounded call it names; every member is required (empty output serializes as "", never absent) except exit_code and reason, each absent when the terminal carries none.
BlockedPrompt
The cold recall seed on session/resume and session/read results: at most one, the latest blocked Main prompt — exactly the host’s mirror of prompt_recovery::replay::ReplayInput’s choice.
BodyCompletionMembers
bodyCompletion: the facts one receipt row renders. The fold reads them from the inbox terminal record and the backgrounded call it names. status, result_summary, and correlation are required; origin_call_id is absent exactly when the join is unresolved.
BranchState
The latest branch observation in the snapshot.
CheckpointBoundary
A served checkpoint-prune boundary: through_item_id names the last first-opened item that opened strictly before the boundary checkpoint event.
ClientApprovalRule
One client-supplied shell prefix allow-rule: argv tokens in the ShellPrefixSuggestion.argv_prefix shape. An object, not a bare array, so the element can grow additively later.
ClientApprovalRuleState
One listed client-supplied rule in EffectivePermissionState: the prefix plus its origin.
ClientCapabilities
The client’s requested capability posture. Every member defaults; an absent capabilities object means all defaults.
ClientInfo
Client identification inside initialize params. Diagnostics and telemetry attribution only; never an authority claim.
ClientRef
A client’s own name for an image part: 1 to 256 bytes of UTF-8, returned verbatim. Open, so a later optional member decodes on an older client.
CodeModeOutputSpan
One public-output span inside the item’s visibleOutput.
CodeModeReceipt
Code Mode’s details payload.
CommandAcceptedResult
The uniform command acknowledgement: admission only, never an outcome. session/compact alone may answer "noop"; every other command answers "accepted".
ComputerUseApp
One row of the Settings apps list.
ComputerUseAppPatch
One per-app choice to set in computerUseSettings/update.
ComputerUseBlockedApp
One row of the Settings blocked-apps list.
ComputerUseInstalledApp
One installed or running app, for Settings’ app picker.
ComputerUseLockHolder
The Computer Use lock’s holder as a computerUseTakeover approval shows it: never its app, window, target or current action.
ComputerUseSettings
computerUseSettings/read result, also answered by computerUseSettings/update.
ComputerUseSettingsReadParams
computerUseSettings/read params.
ComputerUseSettingsUpdateParams
computerUseSettings/update params: a patch. Omitted members are left alone; the whole patch applies or none of it does.
ComputerUseSetupChanged
computerUseSetup/changed params.
ComputerUseSetupReadParams
computerUseSetup/read params.
ComputerUseSetupStartParams
computerUseSetup/start params: a human command.
ComputerUseSetupState
The session’s setup state: the result of both methods and the computerUseSetup/changed payload’s state.
ContextUsage
The snapshot contextUsage block: the latest (windowTokens, usedTokens, pressure) triple; the snapshot member is null until the fold’s generation chain holds a tracked anchor AND the current basis is present (absent is never fabricated).
ContinuePausedSource
the governing rules explicit continuation object on session/resume: requests explicit continuation of the named loaded actor, subject to ordinary drive authorization and actual successful acceptance.
CronQuarantine
cronQuarantine on session/resume: this resume’s own load opened the session cron store and quarantined a corrupt database.
CronReceipt
Cron’s details payload.
CronReceiptJob
One row of the Cron list receipt’s jobs array.
CumulativeCost
Server-computed session cost member of CumulativeTokenUsage.
CumulativeTokenUsage
Session running totals of counted-once usage.
DamagedRange
damagedRange: what one damaged range of the session log cost. The reader finds the range in the log bytes; no log record is written for it, so every member is derived from the readable records around it.
DeliveredInput
One input the read session’s log delivered to a subagent: the queue-note summary (never the body) plus the queue and drain record sequences, the order and re-read dedupe keys, plus the join ids clients adopt already-rendered rows by.
EarlierHistory
earlierHistory: the boundary checkpoint’s transcript tail, served in place of every item that opened in its pruned prefix. No log record carries it; the host derives it from the checkpoint.
EarlierHistoryMessage
One transcript-tail message of an EarlierHistory item.
EffectiveApprovalModeState
The effective approval-mode projection: the same object session/setApprovalMode returns as effectiveMode and the Session object carries as approvalMode.
EffectiveModel
The latest effective-model fact in the snapshot.
EffectivePermissionState
The effective permission-state projection: the committed native permission snapshot (profile identity, reviewer authority) plus the live per-session runtime’s attachment evidence. The same object session/setPermissionProfile returns and the Session object carries as permissionState. Served values must be coherent: a read never combines an old profile with a newer runtime’s attachment claim.
ErrorData
The optional error.data object. All members additive-optional; kind is always present when data is.
ErrorObject
The error member of an error response.
ErrorResponse
An error response frame. Exactly one of result or error appears on a response; this type is the error half.
ExternalWaitView
The live host-declared external wait as served on a Session object (Session.externalWait): present exactly while a declaration is live for the loaded session, absent otherwise. Absence is never fabricated — an unloaded row carries no member.
FeedbackSubmitParams
feedback/submit params: mirrors the TUI confirm-time FeedbackRequest. The call itself is the explicit confirm.
FeedbackSubmitResult
feedback/submit result: the upload receipt.
ForkCutPoint
Where a fork cuts the source history. Turn ids are used instead of counts because ids stay stable across compaction and concurrent appends while indices do not.
ForkProvenance
Fork provenance folded from the durable session.fork.created record.
Goal
The session goal block. status and percentComplete are carried verbatim — out-of-contract status strings and >100 percents pass through; display clamping is the renderer’s job.
GoalClearParams
goal/clear params. An objective here is an unknown field and rejects -32602 invalidParams — the bare verbs carry exactly this pair.
GoalCommandResult
The shared goal ack, admission-only: all five verbs answer this one shape, differing only in when turnId is present.
GoalEditParams
goal/edit params: replace the current goal’s objective. Same shape as goal/set; the verbs differ in their missing_goal precondition, not their payload.
GoalPauseParams
goal/pause params; shape as goal/clear.
GoalResumeParams
goal/resume params; shape as goal/clear.
GoalSetParams
goal/set params: set the session’s goal objective.
HookCatalogEntry
One installed handler.
HookListParams
hook/list params. Per-session because hook scope follows the session’s workspace and plugin state.
HookListResult
hook/list result: one row per installed handler per event — a ResolvedHookHandler carries one event, and grouping would lose matcher/command identity.
InitializeParams
initialize request params.
InitializeResult
The initialize result.
Item
One transcript item at one revision. item/started, item/updated, and item/completed carry the full object; item/delta appends to it by field path.
ItemCompletedParams
item/completed params: the item reached its terminal state — the authoritative final object. Always cites a durable sourceRange. Clients MUST accept item/completed for an itemId they never saw item/started for.
ItemDeltaParams
item/delta params: a UTF-8-safe streaming append to an open item’s field. Ephemeral-sourced by definition: this params object has no sourceRange member at all. Deltas never bump revision.
ItemReadOutputParams
item/readOutput params: byte-ranged fetch of stored full output that the view truncated, via the item’s outputRef. Read-only; works on loaded and unloaded sessions; no lease.
ItemReadOutputResult
item/readOutput result: one stored-byte page.
ItemStartedParams
item/started params: a new item opened on the transcript. sourceRange is absent when the item opens on an ephemeral record (the delta-streamed kinds); the item’s authoritative open is re-stated by its durable-sourced item/completed.
ItemUpdatedParams
item/updated params: an open item changed non-terminally in a way deltas cannot express — the full item re-emitted at a higher revision (apply rule: replace iff higher).
LastTurn
The last turn/completed the session-view fold applied, restated on session/resume and session/read so a reopened session can report a failed last turn.
LaunchContext
InitializeResult.launchContext: the two launcher variables of the serve process’s environment, verbatim, read once at process start; one value for every connection and session the process hosts. Each member is null when its variable is unset.
LimitsAboveMaxAxis
One too-wide axis in a -32028 limitsAboveMax refusal: every too-wide axis is listed, never the first only. requested/max carry the axis’s own JSON values.
MediaUploadParams
media/upload params: one chunk of a client-minted upload. All members required.
MediaUploadResult
media/upload result: echoes the client-minted id, on every chunk and replay.
MessageAttachment
userMessage image attachment metadata: metadata only — the durable bytes live in the log and are reachable on the raw altitude.
MissingPredecessor
missingPredecessor on session/resume: this resume’s own load found the session’s committed SessionStarted naming a predecessor whose retained log is not in the session store.
ModelCancelParams
model/cancel params: the commandId of the call to cancel, not a retry id of its own.
ModelCancelResult
model/cancel result: always empty, for a call in flight and for an id no call holds alike; model/completed reports the outcome.
ModelCatalogEntry
One visible catalog row. Catalog rows marked hidden never reach the wire, so a client cannot select one.
ModelCompleteMessage
One model/complete message.
ModelCompleteParams
model/complete params: the retry id, 1 to 32 messages (the first and the last user), an optional system text and the output bound. No session and no model: the host picks the model. The host answers an unknown field with invalidParams; the type itself accepts it.
ModelCompleteResult
model/complete result: admission only — the ack is never the completion.
ModelCompleteUsage
The provider’s token counts for one completed call: real counts only, never an estimate.
ModelCompletedParams
model/completed params. text, stopReason, modelId and usage ride completed (usage only when the provider reported counts); message rides failed; cancelled and timedOut carry neither. The struct marks the conditional members optional; the SS prose pins the per-outcome rule. text is untrusted model output.
ModelCost
Per-1M-token catalog cost, carried verbatim for display and never rounded or re-formatted by the host. Cost arithmetic stays client-local view math.
ModelDescribedReasoningEffort
One described reasoning-effort tier of a model/list row: a selectable tier plus the catalog’s display string for it when declared.
ModelIdRefusal
modelIdRefusal on session/resume: the host refused this resume’s modelId, so the session opened on its recorded model.
ModelListParams
model/list params: the discovery half of the model-picker gesture. A query, not a command — no commandId, no durable intake record, no view event.
ModelListResult
model/list result. A snapshot at call time: v1 has no catalog subscription. models MAY be empty — a build shipped with no bundled models is a supported configuration.
ModelSelection
A model selection. Empty strings are normalized to absent.
ModelVisibleContent
Rich content the model saw beyond text: metadata only — fetch bytes via item/readOutput when an outputRef exists.
MonitorInboxItemAdmittedParams
monitor/inboxItemAdmitted params: one monitor inbox admission — the fold keys gate-off consumes.
MonitorInboxItemDrainedParams
monitor/inboxItemDrained params: one monitor inbox drain — a consumption marker with its recorded stamp.
MonitorInboxItemVoidedParams
monitor/inboxItemVoided params: one wake-missed void — count-only, no transcript row.
MonitorInboxSnapshotEntry
One snapshot monitorInbox entry: a retained admission in the monitor/inboxItemAdmitted shape, envelope-stripped, plus the newest drain and void stamps folded for it. The entry is still awaiting delivery when drainedAt is absent, or when voidedAt is strictly newer than it.
NoticeSubject
systemNotice: the durable thing the notice is about. id is required whenever the object is present; label is the producer’s sanitized, already-capped display value, omitted when it is empty, never "".
Notification
A notification frame, either direction. No id; a notification is never answered.
OutputRef
Stored-output reference: the camelCased fold of the durable ToolOutputRef. The fetch path is item/readOutput.
PatchSummary
Server-authored edit-family diff summary: files counts the stored patch document’s file entries; added and removed are the total +/- prefixed LINE counts summed over the stored patch’s hunks across all files — line counts, never hunk or byte counts. Rides the toolCall item beside patchRef; the body is fetched via item/readOutput with patchRef.id.
PeerMessage
peerMessage: the four facts the consumed card renders. The fold reads them from the drained inbox record’s delivery snapshot; senderLabel already ran the gate-off label rule host-side, so the client renders it verbatim. Stable from day one (the scheduledFire precedent): no x-msp-stability marker.
PendingApprovalPointer
A pending approval in the snapshot: the pointer shape plus the gated itemId when one exists.
PendingRequestPointer
A late-joiner pointer at an unsettled server-initiated request. The full payloads arrive as re-issued server-to-client requests right after a session/resume response; session/read never re-issues them.
PendingUserInputPointer
A pending user-input prompt in the snapshot.
PermissionAxes
A committed profile’s effective four axis values: the resolved filesystem, network, approval, and reviewer the YOLO predicate reads. The reviewer member reuses ReviewerAuthority, so its spelling never drifts from the served reviewerAuthority.
PluginCatalogEntry
One installed plugin record.
PluginChangedParams
plugin/changed params: an install landed; clients re-issue plugin/list (plus hook/list and skill/list).
PluginInstallLocalPathTarget
The plugin/install local-path arm.
PluginInstallMarketplaceTarget
The plugin/install marketplace arm.
PluginInstallParams
plugin/install params. Per-session params plus a client-generated commandId (UUIDv7) with the uniform idempotency contract.
PluginInstallResult
plugin/install result: the ack envelope plus the installed receipt.
PluginInstallTarget
The one structured install target: a flat object with two optional arms, exactly one present — the TurnInputPart convention, since the v1 schema model names no object-variant union. Both arms or neither is -32602 invalidParams.
PluginListParams
plugin/list params. Per-session params; rows are the installed plugin records.
PluginListResult
plugin/list result: one row per installed plugin record; the spec promises the set, not an order.
PluginMarketplaceAddParams
plugin/marketplaceAdd params. Per-session params plus a client-generated commandId (UUIDv7).
PluginMarketplaceChangedParams
plugin/marketplaceChanged params: a marketplace was added, updated, or removed.
PluginMarketplaceRecordResult
The stored marketplace record both add and update answer: the ack envelope plus the record.
PluginMarketplaceRemoveParams
plugin/marketplaceRemove params. Per-session params plus a client-generated commandId (UUIDv7).
PluginMarketplaceRemoveResult
plugin/marketplaceRemove result: the ack envelope plus the removed name.
PluginMarketplaceSkippedEntry
One skipped marketplace entry.
PluginMarketplaceSourceShape
The normalized stored marketplace source.
PluginMarketplaceUpdateParams
plugin/marketplaceUpdate params. Per-session params plus a client-generated commandId (UUIDv7).
PrunedSubagent
One child session pruned below a checkpoint boundary: the restored row’s key, text, and stoppability — never pruned transcript.
QueuedInput
One input still queued for delivery to a session: the full message body plus its log record sequence, the delivery-order and re-read dedupe key, plus the run-log record id clients join served entries against record-seeded rows by.
QuotaDetail
Typed quota-exhaustion detail: the limit kind plus the provider’s reset instant.
ReasoningEffortState
The snapshot’s standing session-default reasoning effort: the fold of the latest completed runtime.reasoning_effort_reconfigure fact — the same pair session/reasoningEffortChanged carries.
RecapCancelParams
recap/cancel params: the session plus the cancel’s own retry id. No target — one in-flight slot per session makes the target unambiguous.
RecapCancelResult
recap/cancel result: admission only. In flight → the recap settles cancelled; idle → accepted no-op.
RecapCompletedParams
recap/completed params: the settlement, delivered to the requesting connection outside the view stream — no viewCursor, no sourceRange. text is required on completed; reason is required on failed; neither rides cancelled/timedOut. The struct marks the conditional members optional; the SS prose pins the per-outcome rule, the turn/completed usage/error convention.
RecapRequestParams
recap/request params: the session plus the client-minted UUIDv7 retry id. No other param; unknown fields are invalidParams.
RecapRequestResult
recap/request result: admission only — the ack is never the recap.
RecordPosition
One end of a SourceRange: a record’s event id and its sequence number within the stream.
RecoveryObservation
One coherent producer snapshot; all members are required and non-null.
ReplayHint
The first-tree-transition hint verdict plus anchor: rowKinds is the open lowercase row-kind vocabulary the client formats through its shared kind-noun constructor; afterItemId is the item id after whose rows the hint renders. Both members always ride when the object does.
Request
A request frame, either direction.
RequestReceipt
The presentation receipt — the client’s response to a server-initiated request (approval/request, userInput/request).
RestartReceipt
One restartReceipts entry on session/resume: a copy of the runtime ManualCompactionReceipt in its own serde vocabulary — display event ids, StreamRef streams, and the runtime’s snake-case status/reason/outcome words.
RunningElsewhere
The runningElsewhere member of a Session: another live process on this machine runs the session.
RuntimeWorktree
The runtime-owned git worktree a child session runs in, mirrored from the subagent.worktree.* records on its parent’s log. The four enums are open: clients treat an unknown value as unknown.
ScheduledFireMembers
scheduledFire members, flattened into the item row.
SchemaInfo
The schema pair in InitializeResult. version is the wire envelope schema version — distinct from the session-view schemaVersion, the raw-log schema_version, and the 0.x/1.0 stability posture, which is not on the wire at all.
ServerInfo
Server identification inside InitializeResult.
Session
The session object every lifecycle method returns or lists.
SessionApprovalModeChangedParams
session/approvalModeChanged params: the fold of the durable approval-mode reconfigure audit fact — every accepted change writes one; a mode flip without an audit fact is a runtime bug by design.
SessionBranchChangedParams
session/branchChanged params: a durable workspace-branch observation landed.
SessionClearExternalWaitParams
session/clearExternalWait params.
SessionClearExternalWaitResult
session/clearExternalWait result: no declaration is live.
SessionClosedParams
session/closed params: a loaded session was unloaded from this host, broadcast to every initialized connection. After it, the session is notLoaded; the log remains on disk and session/resume reloads it. A crash emits nothing — only the orderly unload paths do (idle unload, host shutdown and a released session/leave), and each writes the durable SessionEnd record first.
SessionCompactParams
session/compact params: manually compact the session’s conversation context — the /compact gesture. Compaction runs asynchronously; the ack is admission only.
SessionCompactResult
session/compact result. Failures after admission (summarizer_failed, install_rejected, cancelled) are not wire errors — they arrive as the compaction’s terminal view event.
SessionConfig
The open configuration extension object shared by session/start and session/resume.
SessionContextUsageParams
session/contextUsage params: context-window pressure — the counted-once occupancy at the latest provider-reported durable fact, joined with the host’s pressure basis. Replace wholesale; emitted only when the (windowTokens, usedTokens, pressure) triple changes value (identical adoptions emit nothing).
SessionDeclareExternalWaitParams
session/declareExternalWait params.
SessionDeclareExternalWaitResult
session/declareExternalWait result: the declaration is live.
SessionEndpointProviderOverride
One provider’s endpoint: the top level’s transport fields, under the same wire names, without allowOpenai. Closed: an unknown field fails the decode.
SessionEndpointProviders
AC-D5: providers of the transport override. Closed: a provider this version does not name fails the decode.
SessionForkParams
session/fork params.
SessionForkResult
session/fork result: the session/resume envelope for the new session, whose session.forkedFrom carries the provenance.
SessionGoalChangedParams
session/goalChanged params: the projected goal block’s value changed — identical adoptions emit nothing (the change gate), and an explicit null clears. Replace wholesale; null never means unchanged.
SessionHistory
The history envelope shared by session/resume, session/fork, and session/read.
SessionLeaveCompletedParams
Params of the protected, non-view leave terminal notification.
SessionLeaveFailureReason
Current producer failure reasons for session/leaveCompleted; receiver-open for additive future reasons.
SessionLeaveOutcome
Current producer outcomes for session/leaveCompleted; receiver-open.
SessionLeaveParams
session/leave params.
SessionLeaveResult
The admission-only session/leave result.
SessionLimits
A five-axis limits report: every maxLimits / currentLimits member is this one definition, and every member is required — reporting always fills all five, so readers never see an absence.
SessionLimitsChoice
The session/start limits choice: every member is optional — a start names only the axes it chooses, and an omitted axis reads the daemon default: the daemon’s own posture on the sandbox axes, and on trust untrusted unless the daemon serves trusted by default. On a daemon whose default sandbox is off, turning the sandbox on takes both sandboxEnabled: true and sandboxNetwork; naming sandboxEnabled: true without sandboxNetwork, or a network restriction (restricted or proxy-only) without naming sandboxEnabled, is refused -32602 (data.reason: "tighterSandboxUnserved") until a tracked change settles how a session turns the sandbox on there; a network restriction beside an explicit sandboxEnabled: false, which never turns it on, is refused the same way while a tracked change is open, so drop the restriction. Where the ceiling allows the sandbox off over a sandbox-on default, a network restriction beside sandboxEnabled: false is admitted and restricts nothing: with the sandbox off the network is not sandboxed, so the session runs and reports sandboxNetwork: "enabled". Reports use SessionLimits, whose members are always present. A session/resume names only workspaceTrusted here.
SessionListBranchFilter
Exact branch selection.
SessionListChangedParams
session/listChanged params: one changed row of the session/list shape — the full Session object as the answering host’s list face serves it at emission, a replace, never a delta. Emitted only on connections that negotiated the sessionListStream capability at initialize; row birth stays on session/started, unload pairs with session/closed.
SessionListFilter
The session/list filter. Members are ANDed with each other and with the top-level workspaceRoot and updatedAfter; values inside each anyOf are ORed. The canonical form the server echoes deduplicates and sorts every set, spells session IDs as canonical UUIDs, lowercases text terms, and orders text.fields name then title.
SessionListParams
session/list params. Read-only; never touches leases.
SessionListResult
session/list result. The default order is content activity: lastActivityAt descending, then sessionId ascending. The order is the session index’s key, so a row’s displayed timestamps do not always show its position: a row the index has not yet derived keeps its updatedAt position, a derived row with no content orders by createdAt, and a loaded row can show newer values. Do not re-sort or validate a page from them. updatedAfter still filters on updatedAt.
SessionListSessionIdFilter
Exact session-ID selection.
SessionListTextFilter
Name/title token-prefix search. Each term is trimmed, lowercased with ordinary Unicode lowercase, then NFC- normalized, and matches the beginning of an alphanumeric token, accent-sensitively (check matches Checkout; eck does not). NFC means a decomposed and a precomposed spelling of one term are the same term, and the echo returns the composed form. Matching never reorders rows.
SessionLoadWarning
One session/start or session/resume result warning. Experimental. The command succeeded; the warning names what the host did not apply.
SessionLoadWarningItem
One selection_unavailable item. Experimental.
SessionModelChangedParams
session/modelChanged params: a durable model-selection record landed.
SessionModelEndpointTransportOverride
the governing rules: the per-session model endpoint transport override, mirroring the EndpointTransportConfig fields under MSP camelCase wire names (base_url->baseUrl, http_headers->httpHeaders`, and so on; the mTLS path fields travel as strings, paths being a host concern). Every field is optional; all absent is the default transport. Resolution against managed egress policy is a later slice.
SessionModelRouteUnservedParams
session/modelRouteUnserved params: an accepted login.credential_update installed a provider that cannot serve the session’s STANDING model route. Disclosure only — the standing selection is unchanged (no session/modelChanged fires) and the repair path is a routable session/setModel. Folded from the durable runtime.provider_reconfigure.standing_route_unserved record; additive — clients that predate it skip the unknown method.
SessionNameChangedParams
session/nameChanged params: the fold of ANY durable session-name record — the FIRST-NAMING automatic allocate as well as an accepted session/rename (or the same in-process runtime command). Replace-wholesale like every sibling.
SessionReadParams
session/read params: read one stored session without attaching — no writer lease, no load, no subscription, no SessionResumed record.
SessionReadResult
session/read result. The viewCursor is the fold head at read time — a point-in-time read, immediately stale if a foreign host is appending.
SessionReasoningEffortChangedParams
session/reasoningEffortChanged params: a durable reasoning-effort reconfigure record landed. Replace wholesale, latest wins; the snapshot carries the latest value.
SessionRenameParams
session/rename params: set or change the durable allocated session name through the runtime session_name command. One writer; withheld under the ephemeral profile.
SessionRenameResult
session/rename result: name is the canonical (normalized) name the durable record settled.
SessionResumeParams
session/resume params.
SessionResumeResult
session/resume result.
SessionSetApprovalModeParams
session/setApprovalMode params: switch the session’s approval enforcement mode mid-session. A standard command.
SessionSetApprovalModeResult
session/setApprovalMode result. Applies next-action — an in-flight tool action’s pending approval is not retroactively decided by a mode change.
SessionSetModelParams
session/setModel params: the model-picker gesture. The selection is durable and applies to subsequent model calls.
SessionSetModelResult
session/setModel result. If a turn is running the selection is admitted now and applied at the next model-call boundary; the ack does not wait for that boundary.
SessionSetReasoningEffortParams
session/setReasoningEffort params: set the session’s standing reasoning-effort default. A turn carrying its own reasoningEffort overrides it for that turn only; the default overrides the host’s configured default. Same accept/reject and commandId idempotency shape as session/setModel.
SessionSetReasoningEffortResult
session/setReasoningEffort result. The default is durable on ack and applies to turns launched after admission; a running turn keeps the request options it already resolved.
SessionSettingsOverrides
the governing rules: a flat settings patch for one session — dotted key paths in file spelling verbatim (the settings/* key-path vocabulary) mapped to their new absolute scalar values. null clears the member to absent, exactly as a settings/writeValue edit does.
SessionSideChatParams
session/sideChat params.
SessionSideChatResult
session/sideChat result: the session/resume envelope for the new side session, whose session.sideFrom carries the provenance. The side opens empty.
SessionSpawnedBy
Who opened a session.
SessionStartNode
One node a session/start names: where the session’s tool calls run. The host validates the three strings; this shape only carries them.
SessionStartNodeRoster
The roster a session started with, echoed on the session/start result. A client that named nodes and reads no echo sends no turn: the host did not attach them, or no longer holds the roster it started with.
SessionStartParams
session/start params.
SessionStartResult
session/start result.
SessionStartRosterNode
One attached node of a SessionStartNodeRoster.
SessionStartedParams
session/started params: a session became newly loaded on this host via session/start, session/fork, or session/sideChat, broadcast to every initialized connection.
SessionStatusChangedParams
session/statusChanged params: a loaded session’s projected (status, attention, needsInputReasons) value flipped. A command-plane broadcast — delivered to every connection regardless of its view subscription set, never gated, no sourceRange; the same facts live on the Session object, which is how a client seeds its table (no initial burst on connect).
SessionTodoListChangedParams
session/todoListChanged params: a TodoSnapshotUpdated record landed. Replace the whole list on every event; an empty items array is a cleared list, not a no-op.
SessionTokenUsageParams
session/tokenUsage params: one per model completion that reports usage. Carries the raw counters verbatim plus the server-derived counted-once promptTokens/totalTokens and the session cumulative block. Accumulate-only: cumulative never goes backward.
SessionUserShellParams
session/userShell params: run a user-initiated shell command in the session’s workspace — the TUI’s ! escape hatch. Capability-gated: the connection must negotiate userShell at initialize, and the whole justification is the spawn boundary.
SessionUserShellResult
session/userShell result: immediate. The shell runs off the command worker so a long command cannot stall the command plane; the output arrives as the userShell item’s terminal view event.
SessionViewHealthChangedParams
session/viewHealthChanged params: the named session’s live view stream became unavailable, and why, or it is back after the host re-loaded the view, so the client re-reads and re-subscribes.
SessionWorktree
The Session worktree member: path and origin only — the branch stays in the existing branch member.
SideProvenance
Side provenance folded from the durable side provenance.
SkillCatalogEntry
One typed-invocable shortcut spelling. A plugin skill may contribute two rows: its bare-name winner and its qualified <pluginId>:<skillId> form.
SkillChangedParams
skill/changed params: the session’s user-invocable set changed; clients re-issue skill/list. Advisory — the host may coalesce bursts and guarantees no ordering relative to view events.
SkillImportCounts
The four receipt-list lengths: a client renders counts without walking lists.
SkillImportFailure
One import candidate that could neither install nor quarantine: recorded so the run continues past it. id is null when the candidate never yielded one — present-but-null, never omitted.
SkillImportParams
skill/import params: import foreign skills through the single SkillsService::import_skills seam.
SkillImportQuarantine
One quarantined import candidate: kept, not loaded.
SkillImportResult
skill/import result: the ack envelope plus the service receipt projection.
SkillListParams
skill/list params. Per-session because skill scope follows the session’s workspace and plugin state.
SkillListResult
skill/list result: one row per typed-invocable shortcut spelling — exactly the invocations the first-party typed dispatch accepts.
SkillSetActivationParams
skill/setActivation params: turn one skill on or off in any scope through the single SkillsService::set_activation seam.
SkillSetActivationResult
skill/setActivation result: the ack envelope plus the applied state.
SnapshotAnchor
The compaction boundary an anchored snapshot is anchored at.
SnapshotState
The complete folded view at the snapshot cursor.
SourceRange
The inclusive raw-record range a durable-sourced view event folded from — the reconciliation token: re-folding the cited records from the canonical fold state immediately before first — appended host-death terminals seed from the end-of-records state — reproduces the event. In v1 it is an opaque provenance token: no wire method reads what it points at.
StatusAttempt
toolCall.statusAttempt: the latest TaskExternalAttemptDetail, field-for-field — countdown inputs the client renders the tick from, so no event spam.
StatusChildren
toolCall.statusChildren: the latest TaskChildSummaryDetail, field-for-field.
StatusHealth
toolCall.statusHealth: the latest TaskHealthDetail, field-for-field.
StatusProgress
toolCall.statusProgress: the latest TaskProgressDetail, field-for-field.
StatusStep
toolCall.statusStep: the latest TaskActiveStepDetail, field-for-field.
StreamRef
One raw stream named by a SourceRange.
SubagentInputParams
Params for subagent/sendMessage and subagent/followupTask: a child target plus the input body.
SubagentListParams
subagent/list params: the session whose subagent roster to read. A read-only query in the skill/list mold: no commandId, no durable record, no view event. Served by the loaded parent’s runtime control records, so its refusals (-32020/-32021/-32022/-32024, plus a retryable -32603 when the runtime source declines) are the task/list split.
SubagentListResult
subagent/list result: the session’s roster rows. Empty only when the parent’s control records name no durable child; a declined source refuses typed instead of answering empty.
SubagentMembers
subagent members, flattened beside the other optional members.
SubagentOwnerReasonParams
Params for subagent/interrupt, subagent/stop, and subagent/close: a child target plus an optional human-readable reason that is preserved on the durable effect record.
SubagentResult
A subagent’s result envelope.
SubagentRosterEntry
One roster row: a durable child’s identity, place, and state, projected from its control records. Rows carry no result content — the transcript stays on the child session / subagent/readResult.
SubagentTargetParams
Params for subagent/resume, subagent/reopen, and subagent/readResult: the bare child target.
SubscriptionUsage
The one usage payload shape: the usage/read result’s usage member and the usage/changed params. The numbers are point-in-time — observedAtMs is the host’s arrival stamp, so a client renders “as of”, never implies live data.
SubscriptionUsageWeekly
The rolling weekly block: same semantics as SubscriptionUsageWindow without a duration.
SubscriptionUsageWindow
The current usage window (the provider’s 5-hour-class block): verbatim provider percentages with the reset stamp normalized to epoch milliseconds.
SuccessResponse
A success response frame.
TaskBackgroundParams
task/background params: durably send a running foreground tool task to the background.
TaskCommandResult
The task/background / task/stop ack: admission-only, echoing the targeted task.
TaskListEntry
One task inventory row. The row is the stable contract: kind and status stay open so a future state extends them without breaking clients.
TaskListParams
task/list params: the session whose background-task inventory to read. A read-only query in the skill/list mold: no commandId, no durable record, no view event.
TaskListResult
task/list result: one row per live workload, background and foreground, oldest first; empty when nothing is running.
TaskStopAllParams
task/stopAll params: stop every stoppable background workload live at admission.
TaskStopAllResult
The task/stopAll ack: always accepted, including over an empty set — a blanket stop over nothing is a satisfied gesture. The ack deliberately carries no stopped-task list; count the kills from the view.
TaskStopParams
task/stop params: stop one named background task. Required target, never “whichever is loudest” — is the blanket verb.
TodoItem
One todo entry.
TodoListState
The latest todo-list fact in the snapshot.
TokenUsage
Raw token counters, verbatim from the durable record. Not directly summable across providers — sum the counted-once derivations instead.
ToolCallMembers
toolCall members, flattened into the item row.
ToolDisplayLabel
toolCall.displayLabel: the call’s words in three forms, each one line of plain text, always present together. The item’s status picks the form.
ToolReceipt
The shared toolReceipt container.
TraceContext
Optional W3C trace context, on requests in both directions only — never on responses or notifications.
TurnCancelParams
turn/cancel params: plain cancellation on the normal command lane. Same shape as turn/interrupt, without retract — pairing a retract with a plain cancel is durably rejected not_paired_interrupt.
TurnCancelResult
turn/cancel result: identical envelope to turn/interrupt.
TurnCompletedParams
turn/completed params: the run’s durable terminal record landed.
TurnError
The settled turn-failure object: {kind, message, retryable}.
TurnForegroundCompletedParams
turn/foregroundCompleted params: the turn’s foreground work is done and named background reminder checks hold the turn open. Explicitly non-terminal: the turn ends only at turn/completed / turn/unqueued.
TurnInputPart
One ordered content part of a turn submission. File mentions are text, not a part type: write @relative/path in a text part. A structured mention part is reserved and currently rejected, and an unknown part type is invalidParams — which is what closes TurnInputPartType.
TurnInterruptParams
turn/interrupt params: the “user pressed stop” gesture, on the runtime’s priority lane.
TurnInterruptResult
turn/interrupt result. Acceptance means the interrupt was admitted, not that the turn is already stopped: the turn is over when you fold its turn/completed with terminal cancelled.
TurnModelAttemptStartedParams
turn/modelAttemptStarted params: a turn’s model provider task recorded its opening status — one model attempt is starting (before the provider dials), retries and later model steps included. Clients raise their thinking state here, the point a switch-off TUI flips on model-task activity. Non-terminal: it never resolves a turn-wait. sourceRange cites the session stream’s mirror of the task-lifecycle record.
TurnModelRetryScheduledParams
turn/modelRetryScheduled params: a durable model-stream retry-scheduled fact folded — the provider backoff behind one model attempt is observable BEFORE the turn terminates, so a streaming client can render “system words · retrying in Ss · attempt N/M” instead of dead air. Non-terminal: it never resolves a turn-wait. The sibling turn/retryScheduled shape at the model layer: same member names and semantics (attempt/nextAttempt/maxAttempts/ retryDelayMs/system/errorKind/httpStatus), minus reason — the row’s words derive from errorKind through the shared gate-off mapping, and the recorded machine message is not user text. The delay is the recorded scheduled backoff, never an absolute fire time — clients derive any countdown locally. sourceRange cites the session stream’s mirror of the task-lifecycle record.
TurnRef
A turn named by the snapshot’s active/queued lists.
TurnRetractedParams
turn/retracted params: an interrupt-paired retract durably settled, accepted or declined. On "accepted" the retracted user-message item is re-emitted via item/updated with retracted: true; on "declined" the client folds the legacy declined rollback instead and no item is re-emitted.
TurnRetryScheduledParams
turn/retryScheduled params: a durable turn retry-scheduled fact folded — the failing model attempt’s scheduled retry is observable BEFORE the turn terminates, so a streaming client can render “attempt N/M · retrying in Ss · reason” instead of dead air. Non-terminal: it never resolves a turn-wait. The delay is the recorded scheduled backoff, never an absolute fire time — clients derive any countdown locally. sourceRange cites the session stream’s mirror of the task-lifecycle record.
TurnStartParams
turn/start params.
TurnStartResult
turn/start result.
TurnStartedParams
turn/started params: a foreground turn began running — fresh submits immediately, queued submits at their launch boundary, never steered submits.
TurnSteerParams
turn/steer params: exact-target steering into the currently running turn.
TurnSteerResult
turn/steer result.
TurnUnqueueParams
turn/unqueue params: reclaim a queued submit before it launches. It is not a stop — a reclaim that arrives after its target launched is durably rejected, never silently upgraded into a cancel.
TurnUnqueueResult
turn/unqueue result. Admission only — but for this command admission is the race: an admitted reclaim implies the turn will not launch. The authoritative removal is the turn/unqueued view event.
TurnUnqueuedParams
turn/unqueued params: a queued submit’s reclaim durably won; its pre-minted turn never runs. Carries the reclaimed turnId and the commandId of the turn/start that queued it, so a client can restore the submission’s text exactly as for turn/retracted. No turn/started/turn/completed is ever emitted for this turnId. sourceRange cites the SESSION stream’s reclaim record — a reclaimed turn never had a run stream.
TurnUserShell
The queued ! shell action a turn/start carries: the !cmd typed while a turn runs. The shell’s command id derives from the carrying turn’s commandId, exactly as the app’s own queued submit does; the params’ sibling displayText carries the !… presentation form.
UnavailableInputAsset
One retained input image a report load replaced with a marker. It names no run: each digest is listed once.
UnframedViewNotification
One element of a view/page result’s events array: an unframed view notification — the nested pair {"method", "params"}, which is the live notification minus jsonrpc and emittedAtMs, with nothing lifted out of params and nothing spliced into it. view/page and muse exec --json share this one definition, so the two surfaces cannot drift.
UnframedViewNotificationParams
The params of an unframed view notification.
UsageReadResult
usage/read result: {usage?} — omitted, never null, when the host has observed nothing.
UserInputAnswer
One question’s answer, as sent in userInput/answer or userInput/interrupt and as recorded in userInput/settled.
UserInputAnswerParams
userInput/answer params: answer every question.
UserInputAnswerResult
userInput/answer result.
UserInputCancelParams
userInput/cancel params: decline to answer; the tool call resolves with a cancelled result the model sees.
UserInputCancelResult
userInput/cancel result.
UserInputClarification
A free-form reply the user gives instead of choosing from the options; the model reads it and decides again.
UserInputClarifyParams
userInput/clarify params: answer with a free-form clarification instead of the structured options — the “let me explain” path; the model receives the clarification text and re-decides.
UserInputClarifyResult
userInput/clarify result.
UserInputEngagedParams
userInput/engaged params: a fire-and-forget engagement note — the user started interacting with a timed prompt, so the host disarms that prompt’s auto-resolution countdown. No result, no errors, no commandId, no ledger row.
UserInputInterruptParams
userInput/interrupt params: interrupt the named prompt carrying confirmed partial answers, then stop the turn.
UserInputInterruptResult
userInput/interrupt result.
UserInputOption
One option offered for a question.
UserInputOptionPreview
Rich content a client can show for an option. Only single-select questions carry previews.
UserInputQuestion
One question in a user-input prompt.
UserInputRequestParams
Full params shared by userInput/request and userInput/requested.
UserInputSelection
How many options the user may pick for a question.
UserInputSettledParams
userInput/settled params: the first durable prompt settlement.
UserInputSettlementSummary
Winning terminal returned to a late user-input command.
ViewGapParams
view/gap params: push delivery dropped events, and this names the hole.
ViewPageParams
view/page params: cursor-paged reads of the session view.
ViewPageResolvedAnchor
The resolvedAnchor echo: subsequent pages pass ordinary cursors, so the anchor never needs re-resolving.
ViewPageResult
view/page result.
ViewSnapshot
The snapshot object returned by session/resume / session/read.
ViewSubscribeParams
view/subscribe params: attach this connection’s live view subscription for a session at an explicit cursor — the fine-grained counterpart of the auto-subscribe, and the gap-free re-attachment path after view/unsubscribe. It never loads a session, takes no lease, writes nothing.
ViewSubscribeResult
view/subscribe result.
ViewUnsubscribeParams
view/unsubscribe params: remove this connection from the session’s view subscription set — the protocol’s single unsubscribe operation, at the altitude that owns subscriptions. It does not unload the session; unloading is the idle policy.
ViewUnsubscribeResult
view/unsubscribe result: the empty object. Idempotent — unsubscribing while not subscribed returns {}.
WebSearchHit
webSearch: one typed result hit — result schema v1.
WorkflowCancelParams
workflow/cancel params: cancel a live workflow run.
WorkflowChild
One workflow child’s folded state, keyed by (childId, attempt).
WorkflowChildControlParams
workflow/childControl params: skip or retry one workflow child, keyed by the (childId, attempt) pair the workflow item’s children[] carries.
WorkflowControlResult
The shared admission-only ack: deliberately bare {commandId, status} — settlement arrives as the workflow item’s view events, never through the ack.
WorkflowPauseParams
workflow/pause params: pause a live workflow run, shaped exactly like workflow/cancel.
WorkflowResumeParams
workflow/resume params: resume a paused workflow run, host-driven.
WorkflowResumeResult
workflow/resume result: admission-only plus the driven turn — always present, since resume always drives (idle fresh turn or busy steer).
WorkflowTokenBudget
workflow: the run’s launch token budget.

Enums§

ApprovalAmendmentDurability
How long a rule created by an approval decision lasts. The set is open, so newer hosts may send other values.
ApprovalChoiceScope
How long a grant made by a choice lasts. The set is open, so newer hosts may send other values.
ApprovalDecision
The kind of decision a choice applies or an approval received. The set is open, so newer hosts may send values this version does not list.
ApprovalMode
The approval enforcement modes. Closed by design: a client selects a preconfigured mode and can never construct one; widening this enum is a deliberate, gate-visible protocol change.
ApprovalModeApplyOutcome
Whether a mode change did anything, mirroring ApprovalReconfigureApplyOutcome. Apply failures are commandRejected.
ApprovalModeSource
How an approval mode took effect. Open.
ApprovalPersistenceStatus
The result of saving a granted rule to the local policy store. The set is open, so newer hosts may send other values.
ApprovalPolicyResult
Whether an approval’s final decision lets the action run. The set is open, so newer hosts may send other values.
ApprovalResolvedBy
Who or what made an approval’s final decision. The set is open, so newer hosts may send other values.
AttentionFlag
One attention flag: a pending server-initiated request class parked on the session. Open on the wire — clients MUST ignore unknown values; future attention kinds are additive.
AutoRecoveryOutcome
The autoRecovery outcome (the amendment’s decision table). Open enum.
AutoRecoveryReason
Why autoRecovery was refused. Open enum.
BackgroundInitiator
Who durably backgrounded a task. Open — runtime vocabulary.
BackgroundState
Presentation state of a backgrounded running tool item. Open — new states are additive. Asserts presentation only, never durable backgrounding (that claim stays Item::background, set only behind a durable TaskBackgrounded).
BodyCompletionCorrelation
Whether the origin call join held at delivery.
CapabilityName
A grantable capability name. Open: the experimental-only rawLog entry joins the stable domain as an additive open-enum extension when it graduates — closed would make that a retype.
CodeModeLanguage
The language a Code Mode cell ran in. Open: values are lowercase VS Code language identifiers, and only javascript (the V8 engine) is minted today.
CodeModeOutputStream
What a Code Mode output span’s bytes are. Open: each engine mints its own values.
CommandAckStatus
The ack-status vocabulary: "accepted" for every admitted command; session/compact alone may answer "noop". Closed: the protocol defines exactly these two values, so SDK clients get a discriminated type and validation catches a wrong status — and a client that received a third value would have been told nothing it can act on, unlike [TurnStartDisposition], where “acked, not otherwise classified” is a usable reading.
CommandStatus
The ack status: accepted for every admitted command. session/compact is the one method that may additionally answer noop (crate::msp::method::runtime::CompactStatus); no other command uses another status.
CompactStatus
session/compact’s ack status: the one method that may answer noop in addition to the accepted. A noop is a success, not an error, and it is durably settled like any other outcome.
CompactionOutcome
Compaction outcome. Open.
CompactionTrigger
What initiated a compaction. Open.
ComputerUseAppChoice
A per-app choice. Open, like ComputerUseChoice.
ComputerUseAppLock
Why Settings can’t change a row. Open.
ComputerUseChoice
A capability dropdown’s value. Open: the read result carries it, so an older client tolerates a value it does not know.
ComputerUsePermission
One macOS permission as setup last saw it. Open, like the phase.
ComputerUseSetupPhase
Where the session’s setup stands: cua_setup’s state codes, camelCase. Open: a result vocabulary, so an older client tolerates a new state.
ContextPressureLevel
Context pressure level: hard threshold first, both inclusive >=. Open.
ErrorKind
A stable error.data.kind category: camelCase, the value clients branch on. Open: new kinds are added as their methods land, and a new kind is additive only because this domain is declared open.
FeedbackClassification
feedback/submit classification: the four TUI classes in camelCase wire spelling. Closed: a client-selected param vocabulary.
FeedbackSubmitOutcome
feedback/submit result outcome: how one confirmed submit resolved, mirroring the TUI FeedbackSubmitOutcome taxonomy. Open: a server-produced result vocabulary — an older client reading a newer value it does not know follows the open-enum tolerance rule instead of rejecting it.
HeldFor
What holds a tool call before it is admitted to execute. Open: a client reads an unknown value as held by something it does not know, never as released.
HistoryMode
What history a lifecycle result actually served. Open on the client side: report-what-was-served means a client treats an unknown mode as “page it yourself”.
HistoryNoneReason
Why a result served history.mode: "none" — the server’s typed reason for serving no history, with one push-only exception: projectionRebuildFailed rides only a session/viewHealthChanged notification; no resume or read result carries it (see its variant doc). Open on the client side: an absent (older server) or unknown (newer server) value decodes conservatively as an unknown reason, and viewCursor text never substitutes for it.
HistoryPreference
The history request preference of session/resume. The forced values downgrade anchored → inline → snapshot → none; under auto the full rung order is anchoredSnapshot → anchored pending cut → inline → snapshot → pending cut → elided snapshot → elided pending cut → none, a pending cut being the snapshot with its monitorInbox cut to the entries still awaiting delivery.
HookEventName
Hook event names: the lowercase-first-letter spelling of every HookEventKind::all() variant. Open: a future event value is additive.
HookHandlerKind
A hook row’s origin: the config HookSourceKind values plus plugin-contributed. Open: a future origin is additive.
HookRunStatus
hookRun durable outcome. Open: new outcomes are additive, and clients MUST render unknown values generically.
IfBusy
Disposition when a turn is already running. The wire default is queue: an SDK caller who has not looked at session state should not silently mutate an in-flight turn.
ItemKind
The eleven v1 item kinds plus post-v1 kinds. Open: a new kind is additive evolution, and clients MUST render unknown kinds generically.
ItemReadOutputEncoding
The item/readOutput content encoding. Closed: text media is ALWAYS utf8 and binary media base64; a third value would change the client’s decode contract.
ItemStatus
Item status. Open; terminal = anything other than "inProgress", and unknown values are terminal-unknown, rendered generically.
JsonRpcVersion
The literal "2.0" every frame carries.
LimitKind
Quota limit kinds: open for evolution.
LimitsAxisValue
One axis value in a limits refusal: a boolean on the four boolean axes, the mode string on sandboxNetwork. Closed: exactly the two shapes, never another — named in the governing rules closed untagged-union list (CLOSED_WITHOUT_MARKER), since the untagged shape carries no schema marker. Untagged so the wire carries the bare JSON value; untagged also keeps the shape the schema builder requires (a bare serde_json::Value renders no type and is rejected).
LimitsNetworkMode
The sandbox-network axis values. Closed: a client selects one of the three serve spellings and can never construct another; the socket promise is same-version, so the result use needs no unknown arm.
MessagePhase
agentMessage.messagePhase: the phase the model declared, never inferred from position. Set on every completed item, and on item/started when the host knows the phase: absent or unknown there means not yet known, and the completed value wins. A failed item carries none, and its missing value does not read as "finalAnswer". Open: a client reads an absent or unknown value on a completed item as "finalAnswer" and still decodes the item. Not a turn-done signal; turn/completed is.
MissingInputAssets
What a cold load does when a retained input image file is missing or corrupt. Omitted means fail.
ModelCatalogSource
Where a model catalog came from. Open: an unrecognized value is an unknown source, not an error.
ModelChangeSource
What drove a model selection. Open.
ModelCompleteOutcome
How a model/complete call settled. Open: a server-produced result vocabulary, so a word a newer host adds decodes to Unknown.
ModelCompleteRole
Who said one model/complete message. Closed: a client-produced input the host validates, so an unknown role is invalidParams.
ModelCompleteStopReason
Why the model stopped on a completed call. Open: a server-produced word, so a word a newer host adds decodes to Unknown.
ModelReasoningEffortVariants
A complete ordered effort set, or an explicit unknown capability.
NeedsInputReason
One needsInputReasons reason: why a loaded session’s input is needed. Open on the wire — clients MUST ignore unknown values; future reasons are additive. The reasons are a pure projection of the pending-request fold’s answer in PR 1 (the same read that derives attention); admissionPending is deliberately not a reason.
NoticeOrigin
systemNotice: the producing family, so a client routes a notice without parsing its text. Open. The v1 vocabulary is the Monitor notice and the three system-chrome producers plus the hook-run producer, the paused-Workflow checkpoint producer and the continued-child tools producer; absent means the server named no origin, and a client never infers one.
NoticeSeverity
systemNotice: the notice’s level. Open; an unknown value is an unknown-but-present level, rendered generically.
OutputRefAvailability
Whether a stored output’s bytes are servable. Open — durable runtime vocabulary may grow additively.
PendingRequestKind
The pendingRequests discriminator. Open enum, v1 values approval and userInput.
PermissionApprovalAxis
A profile’s effective approval axis. Open: the vocabulary can widen.
PermissionFilesystemAxis
A profile’s effective filesystem axis. Open: the vocabulary can widen.
PermissionNetworkAxis
A profile’s effective local-command network axis. Open: the vocabulary can widen.
PlatformFamily
The server runtime’s platform family; may differ from the client’s. Closed: the protocol fixes the value set, so widening it is a deliberate, gate-visible protocol change rather than a silent addition (a later Closed→Open flip is itself additive).
PlatformOs
The server’s operating system. Closed, for the same reason as PlatformFamily.
PluginInstallScope
The plugin/install local-path scope. Closed: an unknown scope is -32602 invalidParams.
PluginMarketplaceChange
What happened to a marketplace. Closed: an unknown change is a contract violation, never tolerated.
PluginSource
A plugin row’s source provenance: camelCase of PluginSourceProvenance. Open: a future provenance is additive.
PolicyRuleOrigin
Where a session policy rule came from.
ProbeDegradedReason
Why a workspace status probe produced no fresh reading.
ReasoningEffort
The reasoning-effort tier sampled at submission. The same closed tier vocabulary on both the fresh-turn and steer lanes, spelled identically; invalid tiers are invalid params. none is a tier of the vocabulary (ask for no reasoning), not a way to say “unset”.
ReasoningEffortChangeSource
What drove a reasoning-effort default change. Open; v1’s only producer is user (an accepted session/setReasoningEffort).
RecapFailureReason
recap/completed failure reason: post-ack failures fold to the single initial value. Open: later splits stay additive.
RecapOutcome
recap/completed outcome: the terminal vocabulary, in camelCase. Open: a server-produced result vocabulary.
RecoveryEffectiveSource
Proven effective-choice provenance, independently of input presence.
RecoveryMode
A requested construction choice; omission is distinct from explicit OFF.
RecoveryObservedMode
A proven mode or unknown; future strings cannot establish OFF.
RecoveryQualification
This construction’s assessment, never an operation acceptance receipt.
RequestId
A request id: client-chosen string or integer. 1 and "1" do not compare equal; each direction owns its own id space.
RetractOutcome
A turn/retracted settlement outcome. Open enum: decode is tolerant — a value outside the list reads as Accepted (the event’s historical meaning — pre-feature hosts emit it only for accepted retracts), never fails. The bundle keeps enumerating the known values for codegen and docs.
ReviewerAuthority
A profile’s selected reviewer authority. Open: the reviewer vocabulary can widen.
RunningElsewhereOrigin
Which kind of process runs a session elsewhere on this machine.
RuntimeWorktreeCleanupPolicy
How a session’s worktree is cleaned up. The set is open, so newer hosts may send other values.
RuntimeWorktreeCleanupReason
Why a session’s worktree cleanup kept the worktree or failed. The set is open, so newer hosts may send other values.
RuntimeWorktreeCleanupState
Where a session’s worktree cleanup stands. The set is open, so newer hosts may send other values.
RuntimeWorktreeOwnership
Who owns a session’s worktree. The set is open, so newer hosts may send other values.
SandboxAvailability
Whether this host can enforce the sandbox. A property of the host process, probed once at construction and identical for every session and every connection it serves — never requested, granted, or negotiated, which is why it is not a capability. Open: a future enforcement posture arrives as a new value, read by older clients as unknown.
SandboxUnavailableReason
Why sandbox enforcement is impossible on this host. Sent only when SandboxAvailability is unavailable; a client MUST NOT infer a reason when none is sent. Open: a future reason arrives as a new value, read by older clients as unknown.
SessionClosedReason
The closed-reason vocabulary. Server-produced and published OPEN by owner ruling — the menu-B pick, which settles that this notification reason enum publishes open rather than resting on the result-vocabulary rule by analogy. A crash is deliberately not a reason, because a crash emits no notification at all.
SessionDurability
Whether this host writes its sessions to disk. A property of the host process, fixed at construction and identical for every session and every connection it serves — never requested, granted, or negotiated, which is why it is not a capability. Open: the unrepresented degraded state has candidate resolutions that add a third value here, so closed would make that a breaking change.
SessionEndpointTransportAuthMode
How a request to the overridden endpoint authenticates, mirroring the TransportAuthMode` spellings. Closed: an undeclared mode fails the decode rather than degrading to a default.
SessionKind
What kind of session this is.
SessionListTextField
A served session field session/list text search reads. The client selects it, so the set is closed.
SessionMcpServerConfig
One native MCP server supplied at session construction.
SessionMcpServerMode
Startup failure posture for a session MCP server.
SessionMcpStdioFraming
Stdio framing choices exposed by session MCP configuration.
SessionNameOrigin
How the served session name was set. Open enum (x-msp-openness: open): v1 serves automatic and custom; a client MUST read absent — and any value it does not recognize — as unknown, never fabricated. Open: a future source such as conversation-generated names adds a value here, so closed would make that a breaking change.
SessionSettingsOverrideValue
One SessionSettingsOverrides leaf: exactly the settings/* write value domain — a string, a boolean, or null for clear-to-absent.
SessionStatus
A session’s load state.
SessionViewHealth
The view-health state. Open enum (x-msp-openness: open): a client MUST ignore an unrecognized value. Healthy is the re-arm value reserved by the governing rules, emitted after a host re-load; openness still reserves additive room for the durable-degraded axis.
SkillActivationScope
skill/setActivation activation target. Closed: a client-selected write vocabulary — a write must fail a scope the host does not implement rather than record activation against an unknown target. Contrast the open read-side SkillSource.
SkillActivationState
The three-state skill activation. Closed: a client-selected write vocabulary.
SkillImportSource
skill/import foreign ecosystem. Closed: a client-selected write vocabulary — a write must fail an ecosystem the host does not implement rather than import from an unknown dir. The host resolves its own foreign dir (the foreign_skills_sources derivation); no client paths cross the wire.
SkillInvocationSource
A skill input part’s picked-copy source: the catalog-row source enum values, sent by the TUI on every skill submit so the host resolves the exact (selector, source) row. Closed: a client-selected write vocabulary — an unknown value is invalidParams, never a fall-through to the bare row. Contrast the open read-side SkillSource.
SkillSource
A skill row’s source scope: the projection of the skills crate’s SkillsSourceScope. Open: a future scope value is additive.
StatusHealthLevel
toolCall.statusHealth.level: the durable TaskHealthLevel vocabulary verbatim. Open — runtime vocabulary may grow additively, and clients MUST render unknown levels generically.
SubagentControlStatus
Subagent control status. Open; the generic item status is the terminal authority.
SubagentInputPhase
subagentInput.inputPhase: the record the item stands for. Open: a client ignores an item whose phase it does not know.
SubagentResultStatus
subagentResult.resultStatus: the consumed attempt’s outcome. Absent when the host had not seen that attempt’s result envelope at the drain; a client then shows the child’s current outcome. Open: a client treats a value it does not know as an absent member.
SwitchPolicy
What happens to the previousSessionId predecessor’s unfinished background work. Closed: the client selects one of the two policies the host applies.
TaskExecutionMode
A task row’s execution mode. Open: clients MUST ignore unknown modes.
TaskListStatus
A task row’s status. Open: a future state is additive, and clients MUST ignore unknown statuses.
TodoStatus
Todo status: closed in the runtime, wire-open.
ToolReceiptBody
The family-selected body of a receipt: the family discriminator and the one details object whose shape that discriminator chooses.
ToolReceiptOperation
Which operation within the family the receipt describes. Open — registered per family, never derived from the tool name.
ToolReceiptOutcome
What the operation did. Open, and a single shared vocabulary: a value appearing in two families means the same thing in both, which is why the permitted status values are bound to the value here rather than per family.
TurnErrorKind
Turn failure classes. Open.
TurnInputPartType
The type discriminator of a turn input part. Closed: an unknown part type is invalidParams.
TurnStartDisposition
What turn/start did with the input. Resolves OQ-H in v1: since queue is the default ifBusy, clients need to distinguish these without folding history.
TurnTerminal
Turn terminal vocabulary: exactly the runtime’s RunTerminalKind — closed in the runtime, wire-open for evolution.
UnavailableInputAssetReason
Why the image was replaced. Open: a newer host’s word decodes to Unknown.
UnknownModelReasoningEffortVariants
The only scalar alternative to a known effort array. Kept as a closed singleton so arbitrary strings and uppercase spellings fail decoding.
UserInputOutcome
How a user-input prompt settled. More values may be added, so handle values you do not recognize.
UserInputSelectionMode
Whether a question takes one option or several.
Vcs
Version-control system of a branch observation. Open.
ViewPageAnchor
The view/page request-mode anchor. Declared open: the protocol spells it “open string enum, v1 value latestCompaction”.
ViewPageDirection
The view/page paging direction. Closed: the protocol spells exactly two values and a third would change the paging contract.
WorkflowChildAction
Which control to apply to the child’s current attempt. Closed on the wire: an unknown value is -32602 invalidParams.
WorkspacePlacement
A subagent child’s workspace placement: shared when the spawn requested no worktree isolation, isolated when it did. Open; unknown values read as unknown. Experimental.
WorktreeOrigin
Where a session’s worktree came from: created means the host allocated it for the session, attached means the host bound a caller-provided worktree.
WorktreeStartRequest
session/start worktree param: absent means no worktree — the start proceeds exactly as today. Adjacently tagged on mode: a create carries an optional baseRef, an existing carries a required path (omitted path fails decode — the pre-existing invalid-params class, never a new message).

Constants§

GENERATED_FINGERPRINT
Fingerprint of the stable schema these types were generated from, derived from its bytes at build time; the byte-equality gate keeps the committed copy honest.