#[non_exhaustive]pub struct Session {Show 26 fields
pub session_id: String,
pub path: String,
pub status: SessionStatus,
pub active_turn_id: Option<String>,
pub created_at: String,
pub updated_at: String,
pub workspace_root: Option<String>,
pub provider_id: Option<String>,
pub model_id: Option<String>,
pub approval_mode: Option<EffectiveApprovalModeState>,
pub permission_state: Option<EffectivePermissionState>,
pub attention: Option<Vec<AttentionFlag>>,
pub last_activity_at: Option<String>,
pub turn_count: u64,
pub forked_from: Option<ForkProvenance>,
pub side_from: Option<SideProvenance>,
pub name: Option<String>,
pub name_origin: Option<SessionNameOrigin>,
pub generated_name: Option<String>,
pub title: Option<String>,
pub first_user_prompt: Option<String>,
pub branch: Option<String>,
pub kind: Option<SessionKind>,
pub parent_session_id: Option<String>,
pub created_by_client: Option<ClientInfo>,
pub worktree: Option<SessionWorktree>,
}Expand description
The session object every lifecycle method returns or lists.
Additive-optional evolution applies: clients must ignore unknown fields.
Fields (Non-exhaustive)§
This struct is marked as non-exhaustive
Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.session_id: StringThe session identity.
path: StringAbsolute path of the session’s durable log; non-nullable. Under the ephemeral session profile it is the empty string, meaning “no durable log exists” — the one value a client must not hand to a filesystem call.
status: SessionStatusLoad state as this host knows it; session/list reports notLoaded for
sessions loaded by other hosts.
active_turn_id: Option<String>The turnId of the current foreground turn when status is running,
and null when the session is idle.
**Required-nullable, per the owner ruling on a tracked change. Both
production writers hard-code "activeTurnId": null and nothing strips
it, so this is what the binary emits and what the protocol spec example
spells. The optional-absent shape published it as plain string and
REJECTED every idle Session frame the host sent — the defect class
this PR exists to close.
The original evidence for optional-absent (“every committed transcript
shows the omission”) was wrong: those transcripts are hand-authored
fixtures, not host recordings. They are corrected in the same change
under the ruling’s regenerationJustification.
created_at: StringRFC3339. For a fork this is the fork session id’s UUIDv7 mint instant.
updated_at: StringRFC3339; never precedes createdAt.
workspace_root: Option<String>The winning metadata fold’s workspace root; null when that record
omits it — absent is never fabricated.
provider_id: Option<String>The winning metadata fold’s provider; null when that record omits it.
model_id: Option<String>The winning metadata fold’s model; null when that record omits it.
approval_mode: Option<EffectiveApprovalModeState>The folded effective approval mode. Additive-optional: a Session
object that omits it means the host has not folded a mode, which is why
the index-derived session/list entry may legitimately omit it.
permission_state: Option<EffectivePermissionState>The folded effective permission state. Additive-optional: a
"notLoaded" row omits it (no live evidence, matching the attention
precedent) and an older host omits it everywhere; absent is unknown,
never active. approvalMode stays the effective-mode answer; this never
restates it.
attention: Option<Vec<AttentionFlag>>Attention flags. Additive-optional, present only when at least one
flag is set; absence is a NON-assertion (nothing pending, or the loaded
session’s pending source declined to answer). Loaded sessions only: a
notLoaded row omits it even while its durable pending set is
non-empty.
last_activity_at: Option<String>Content-activity recency, RFC3339. Additive-optional: omitted when
no content record exists. Never advanced by lifecycle bookkeeping (the
resume marker, re-stamps) or a fork’s copied seed-replay records, and
never precedes createdAt.
turn_count: u64Completed-turn count from the session view fold.
forked_from: Option<ForkProvenance>null for root sessions; fork provenance otherwise.
side_from: Option<SideProvenance>null for root sessions and forks; side provenance otherwise. A session
carries at most one of forkedFrom and sideFrom.
name: Option<String>The durable allocated session name. Additive-optional: present when
the serving path holds an allocated name, omitted otherwise — absent is
never fabricated. Authoritative and renameable via session/rename.
name_origin: Option<SessionNameOrigin>How the served name was set. Additive-optional, fold-only: the
snapshot fold (session/read, the resume/start/fork-ack snapshot)
derives and carries it from the log; session/list rows never carry it.
Absent — and any value the client does not recognize — reads as unknown,
never fabricated.
generated_name: Option<String>The served generated short title. Additive-optional, fold-only:
the snapshot fold derives the latest retained generated pair’s short
title from the log; session/list rows never carry it. Omitted when no
pair was ever published — absent reads as unpublished, never fabricated,
never inferred from the name text. name stays the canonical name it
always was.
title: Option<String>Derived display title: a heuristic that may evolve — its carriage, not its derivation, is the contract. Additive-optional, omitted when underivable.
first_user_prompt: Option<String>Derived first-user-prompt preview. Additive-optional, omitted when underivable.
branch: Option<String>Derived workspace branch — the index’s last derived value; the
live-change signal stays session/branchChanged. Additive-optional,
omitted when underivable.
kind: Option<SessionKind>What kind of session this is. Open enum, v1 values "root" and
"subagent"; a client treats an unknown value as an unknown-but-present
kind and renders it, never rejecting the row. Additive-optional:
absence asserts nothing — the host could not determine the home shape,
or the value is not yet available to serve.
parent_session_id: Option<String>The containing session’s id when kind is "subagent" — the id of the
TOP-LEVEL session whose home holds this child, which is not
necessarily the session that spawned it: native-child homes are
physical siblings under the outer session’s subagent/ directory, so a
subagent spawned by another subagent resolves to the outer session, not
to its spawner. A client building a tree from this field gets one level,
not a chain. Flat rather than nested: there is exactly one fact to
carry, unlike forkedFrom’s four-field ForkProvenance.
Additive-optional; a root carries none.
created_by_client: Option<ClientInfo>The handshake ClientInfo recorded when the session was opened, echoed
verbatim — provenance, never an interpretation, and never a visibility
gate. Additive-optional; absence has four indistinguishable causes:
an in-process open; an earlier record; a half stamp where only one of
name/version was recorded and ClientInfo requires both; and a session
with no admitting handshake of its own — a fork child or a subagent —
which never carries a stamp to begin with.
worktree: Option<SessionWorktree>a tracked change: the worktree this session runs in — path and origin
only. Experimental (Session.worktree; stripped per-connection for
unopted callers). Omitted when the session runs in no worktree.