Session records

`session`

The header is line 1 of every stream (ASR-003). It identifies the session, says who wrote the stream and how, and declares the stream’s capabilities and content level.

{
  "type": "session",
  "seq": 0,
  "id": "h",
  "formatVersion": "0.1",
  "agent": {"name": "claude-code", "version": "2.1.305"},
  "namespace": null,
  "sessionId": "0f3c2a7e-91b4-4d6a-8c2e-5a7b3d1e9f04",
  "producer": {
    "name": "example-converter",
    "version": "1.4.0",
    "method": "converter",
    "instance": "conv-7f1",
    "source": {"format": "claude-code-jsonl"},
    "lossy": ["reasoning.signature"]
  },
  "authority": "local",
  "startedAt": "2026-10-26T14:02:11.204Z",
  "lineage": {"root": true},
  "scope": "primary",
  "workspace": {
    "roots": [
      {
        "id": "app",
        "path": "/work/acme-app",
        "vcs": {"type": "git", "branch": "main"}
      }
    ]
  },
  "environment": {"os": "linux", "shell": "bash"},
  "profiles": ["core", "coding", "lineage", "usage"],
  "contentLevel": "full",
  "extensions": []
}

Field	Type	Req	Meaning
`formatVersion`	string	yes	ASR format version, `MAJOR.MINOR`. This specification defines `"0.1"`.
`agent`	object	yes	`{name, version?}`: the agent whose session this is. `name` is a registered short name or a reverse-DNS name (ASR-056). `version` is the agent’s version at the start of the session, verbatim.
`namespace`	string or null	no	Session key namespace (see Identity). Absent and `null` both mean none.
`sessionId`	string	yes	Native session ID, verbatim (ASR-051).
`producer`	object	yes	Who wrote this stream and how (see Producer).
`authority`	string, open	no	`local` (the local data is authoritative), `remote_cache` (a local copy of a session whose authoritative copy is remote), `remote_export` (exported from a remote service), or `mirror` (a copy, kept by another program, of the one session that `lineage.executedBy` names; see Lineage).
`startedAt`	Timestamp	no	When the session started, from the source.
`trigger`	object	no	What started the session, when the source records it (for example a scheduled job that created it). Same shape as a turn’s `trigger`.
`client`	object	no	`{name, version?}`: the client surface that drove the session (a terminal UI, a desktop app, an IDE extension, an SDK), as the source names it. A `declaration` can change it for later records.
`lineage`	object	no	Lineage facets (see Lineage). Absent means unknown; it does not mean the session is a root.
`scope`	string, open	no	`primary` or `subagent` (see Lineage).
`workspace`	object	no	`{roots: Root[]}`: the workspace roots (see Roots).
`environment`	object	no	`{os?, osVersion?, arch?, shell?, timezone?}`, as recorded by the source. A `declaration` can change it for later records.
`participants`	array	no	The people, agents and bots in the session’s conversations (see Participants).
`conversations`	array	no	The chat conversations the session serves (see Conversations).
`conversationKey`	string	no	The source’s key for a conversation that outlives several sessions (OpenClaw’s `session_key`), verbatim.
`profiles`	string[]	yes	Profiles claimed (see Extensibility).
`contentLevel`	string	yes	`full`, `redacted` or `metadata` (see Privacy).
`extensions`	array	no	`[{id, version, required}]` (see Extensibility). Absent means `[]`.
`derivedFrom`	object	no	Set on a stream produced from another stream by redaction (see Privacy).

ASR-150 The header MUST contain formatVersion, agent with name, sessionId, producer, profiles and contentLevel. ASR-151 formatVersion MUST match ^[0-9]+\.[0-9]+$. Streams written to this specification MUST use "0.1". ASR-152 profiles MUST include "core". Every other value MUST be a profile defined in Extensibility or a vendor profile name beginning with _. ASR-153 contentLevel MUST be full, redacted or metadata. ASR-154 Header times (startedAt) follow the same rules as ts: taken from the source, never fabricated (ASR-103, ASR-104).

Producer

Field	Type	Req	Meaning
`name`	string	yes	Name of the software that wrote the stream.
`version`	string	yes	Its version.
`method`	string, open	yes	How the data was obtained (below).
`instance`	string	yes	An opaque identifier for this writer instance (ASR-006).
`source`	object	depends	`{format, formatVersion?, agentVersion?}`: the native format read, its version if known, and the agent version that wrote it if known.
`lossy`	string[]	depends	Categories of known loss (see Missing data and revisions). `[]` means the producer knows of none.

method values:

Value	Meaning
`native`	The agent wrote the stream itself, as its log or through its own export command.
`converter`	Separate software translated the agent’s native logs.
`decoded`	A converter that first decoded an opaque container (a binary database blob, protobuf, a compressed store) with an adapter the vendor does not publish.
`recorder`	Captured from a live harness protocol: an Agent Client Protocol (ACP) connection (see ACP mapping), the Codex app-server protocol, the Claude Agent SDK stream. `source.format` names the protocol.
`observer`	Captured from outside the agent (hooks, a proxy, a wrapper) without reading its logs.
`import`	Translated from another interchange format (ATIF, UAS, Entire).

ASR-155 producer MUST contain name, version, method and instance. ASR-156 When method is anything other than native, producer MUST contain source.format and lossy. ASR-157 producer.lossy MUST name every category of loss the producer knows it introduced or inherited for this stream. An empty array is a claim that the producer knows of none.

Design note. There is no trust or fidelity label. A consumer can check where the data came from using producer.method, capture states for each field and lineage evidence for each facet. A producer’s own labels do not establish trust or fidelity (see Missing data and revisions).

Roots

A root is a directory that paths are expressed relative to (see Coding). Roots are declared in the header and, when discovered later, in declaration records.

Field	Type	Req	Meaning
`id`	string	yes	Root ID, unique in the stream. Matches the record ID pattern (ASR-018).
`path`	string or null	yes	Absolute path of the root, with `/` separators (see Coding). `null` when unknown or redacted.
`pathDigest`	Digest	no	Digest of the original path, for a redacted root (see Privacy).
`nativePath`	string	no	The native spelling when it differs from `path` (for example a Windows path).
`vcs`	object	no	`{type, remote?, head?, branch?, dirty?}`: version control state at the time of declaration, as recorded. `type` is `git`, `jj`, `hg`, `svn` or `other` (open). `head` is a full commit ID.

ASR-158 Root IDs MUST be unique across the header and all declaration records of a stream. A root’s path MUST be either null or an absolute path in the form Coding defines. ASR-159 Root vcs members MUST be recorded only from the source. A producer MUST NOT fill head, remote or dirty from the current state of the file system at conversion time.

Participants

participants lists the people, agents and bots that take part in the session’s conversations, when the source records them: the members of a group chat, a guest on a shared thread, another agent that sends messages. A declaration can add participants later. Messages name their sender with an actor reference to a participant (see Messages).

{
  "type": "session",
  "seq": 0,
  "id": "h",
  "formatVersion": "0.1",
  "agent": {"name": "openclaw", "version": "2026.10.7"},
  "sessionId": "3f9e2a71-6c0d-4b85-a1e4-0d7c5b9f2e63",
  "producer": {
    "name": "example-converter",
    "version": "1.4.0",
    "method": "converter",
    "instance": "conv-5d2",
    "source": {"format": "openclaw-agent-sqlite", "formatVersion": "37"},
    "lossy": []
  },
  "startedAt": "2026-10-26T07:30:02.114Z",
  "conversationKey": "agent:main:whatsapp:group:120363041122334455",
  "participants": [
    {
      "id": "p1",
      "kind": "human",
      "role": "owner",
      "displayName": "Dana",
      "ids": [
        {"scheme": "whatsapp", "value": "+15125550147", "basis": "profile"}
      ]
    },
    {
      "id": "p2",
      "kind": "unknown",
      "displayName": "Sam",
      "ids": [
        {
          "scheme": "whatsapp",
          "value": "+15125550198",
          "basis": "observation"
        }
      ]
    },
    {"id": "p3", "kind": "agent", "self": true, "displayName": "Molty"}
  ],
  "conversations": [
    {
      "id": "c1",
      "channel": "whatsapp",
      "kind": "group",
      "nativeId": "120363041122334455@g.us"
    }
  ],
  "profiles": ["core", "messaging", "usage"],
  "contentLevel": "full"
}

This header comes from an OpenClaw session in a WhatsApp group. OpenClaw records how it knows each sender (profile, observation); ASR keeps that word in basis and does not turn it into a verified or unverified flag.

Field	Type	Req	Meaning
`id`	string	yes	Participant ID, unique in the stream. Matches the record ID pattern (ASR-018).
`kind`	string, open	no	`human`, `agent`, `bot` or `unknown` (the source itself records that it does not know). Absent means not recorded.
`role`	string, open	no	`owner`, `member` or `guest`.
`displayName`	string	no	The name the source shows for the participant.
`ids`	array	no	`[{scheme, value, basis?}]`: native identities. `scheme` names the identity system (`whatsapp`, `telegram`, `slack`, `email`, an account system); `value` is the identity, verbatim; `basis` is the source’s own word for how it knows the identity, verbatim.
`self`	boolean	no	`true` for the participant that is this session’s own agent or the account it speaks as.

Conversations

conversations lists the chat conversations the session serves: a direct chat, a group, a channel, a thread. One session can serve several (OpenClaw’s main session collects direct messages from several apps). A declaration can add conversations later. Messages name their conversation by ID (see Messages).

Field	Type	Req	Meaning
`id`	string	yes	Conversation ID, unique in the stream. Matches the record ID pattern (ASR-018).
`channel`	string, open	yes	The messaging app or channel: `whatsapp`, `telegram`, `slack`, `discord`, `imessage`, `signal`, `email`, `sms` or `web`. Unmapped native names stay in `native` or `_meta` (ASR-619).
`kind`	string, open	no	`direct`, `group`, `channel` or `thread`.
`nativeId`	string	no	The platform’s ID for the conversation, verbatim.
`parent`	string	no	The ID of the conversation this one belongs to (the channel of a thread).

conversationKey is the source’s key for the lane of conversation that several sessions continue (OpenClaw rotates a session_key through many windows, each a session). It is not session identity. ASR-175 Each participant MUST contain id, and each conversation MUST contain id and channel. Each identity in a participant’s ids MUST contain scheme and value. ASR-176 Participant IDs MUST be unique across the header and all declaration records of a stream, and so MUST conversation IDs. A declaration adds only participants and conversations with new IDs. A conversation’s parent MUST name a conversation declared at or before it. ASR-177 Participants, conversations and identities MUST come from the source. basis MUST be the source’s own value, verbatim: producers MUST NOT turn it into a verified or unverified judgment, and readers MUST NOT treat it as a trust label (ASR-521). A producer MUST set kind: "human" only when the source records that the participant is a person. ASR-178 conversationKey MUST be the source’s key, verbatim. Streams with the same conversationKey are different sessions (ASR-050). Readers MAY group them for display. Identity values (displayName, ids[].value, a conversation’s nativeId) are personal data. They are content-bearing for redaction (see Privacy).

`session_info`

session_info carries session metadata that may change: the title and who set it, the current heads, tags, flags, the project, and a later session that continues this one.

{
  "type": "session_info",
  "seq": 1,
  "id": "r1",
  "title": "Fix failing parser test",
  "titleSource": "model"
}

{"type": "session_info", "seq": 200, "id": "r200", "heads": ["r187"]}

{
  "type": "session_info",
  "seq": 216,
  "id": "r216",
  "flags": ["archived"],
  "continuedIn": "claude-code:6e1b0d4a-2f7c-4a39-8d5e-1c9b7a3f0e28"
}

Field	Type	Req	Meaning
`title`	string or null	no	Session title.
`titleSource`	string or null, open	no	Who set the effective title: `model` (generated), `user` or `harness`.
`heads`	(Ref or null)[] or null	no	The current leaves of the conversation (see Structure). The first element is the primary head. A null first element explicitly selects no primary head; later elements remain lane heads.
`tags`	string[] or null	no	Labels.
`flags`	string[] or null	no	Session states the source records, open values: `pinned`, `archived`, `deleted`. `deleted` means the source marked the session deleted and kept its data; the stream’s records remain.
`project`	object or null	no	`{id, name?}`: the project the source files the session under.
`continuedIn`	SessionRef or null	no	A later session that continues this one, when this session’s source records the forward link (Claude Code’s `continued-in`). The later session’s own `lineage.continues` is the matching backward link.

ASR-160 Each field of session_info is a patch: a member that is present replaces the effective value, a member set to null clears it, and an absent member leaves it unchanged. Readers MUST compute the effective value of each field from the last session_info record (in seq order) that contains it. ASR-161 heads follows the reference-resolution table. Each target MUST be a context-participating record. ASR-180 continuedIn MUST be a session reference without a # part. ASR-181 A session_info record that contains title and no titleSource makes the effective titleSource unknown. Readers MUST NOT carry an earlier titleSource over to a new title. Several sources write the same metadata again at every exit or turn (Claude Code re-stamps its title and leaf). A repeated identical value is not a change; producers write session_info only when a value changes.

`declaration`

A declaration amends the header’s declarations as the session proceeds. A native writer often learns only during the session that it needs another profile, has dropped some data, has entered a new root, or has met a new participant. Sometimes a different writer takes over.

{
  "type": "declaration",
  "seq": 57,
  "id": "r57",
  "profiles": ["_dev.example/review"],
  "lossy": ["tool_result.raw"],
  "roots": [
    {
      "id": "lib",
      "path": "/work/acme-lib",
      "vcs": {"type": "git", "branch": "main"}
    }
  ]
}

Field	Type	Req	Meaning
`profiles`	string[]	no	Profiles added.
`extensions`	array	no	Extensions added, as in the header.
`lossy`	string[]	no	Loss categories added.
`contentLevel`	string	no	A stricter content level for later records.
`roots`	Root[]	no	New roots.
`participants`	array	no	New participants.
`conversations`	array	no	New conversations.
`executedBy`	array	no	New entries of the `lineage.executedBy` facet (see Lineage).
`agentVersion`	string	no	The agent’s version from this point on (for example after an upgrade and resume).
`client`	object	no	The client surface from this point on.
`environment`	object	no	A patch to the environment from this point on (for example a new working directory or shell).
`producer`	object	no	`{instance, name?, version?}`: a writer handover (ASR-006).

Most merge rules only add (nothing is removed or loosened):

profiles, extensions, lossy and executedBy are set unions. Nothing can be removed.
contentLevel can only tighten (full → redacted → metadata), and only for later records.
roots, participants and conversations only add entries with new IDs.
agentVersion, client, environment and producer apply to later records.

ASR-162 A declaration MUST contain at least one of the members above. ASR-163 The effective profiles and extensions at a record are those of the header plus every declaration with a lower seq. The effective loss categories of the stream are the union over the header and all declarations. Extensions are merged by id and version; an extension is effectively required if any declaration of it says so. ASR-164 A declaration’s contentLevel MUST be at least as strict as the effective content level before it. A declaration that would loosen it is invalid. ASR-165 A contentLevel declaration applies only to records with a higher seq. Readers MUST NOT read it as reclassifying earlier records. ASR-166 Roots in a declaration MUST have IDs not used before in the stream (ASR-158). Records MUST NOT refer to a root before the record that declares it. ASR-167 Validators MUST evaluate each record against the effective declarations at that record’s seq. ASR-179 A declared agentVersion, client or environment applies only to records with a higher seq. Each member of a declared environment replaces that member of the effective environment; members it does not contain are unchanged. session_info remains the record for titles, heads and tags. The two record types merge differently (last value per field versus a union that only grows) and are kept apart for that reason.

`state`

state records changes in session or turn status that the source records: a turn queued, starting or finishing, the agent waiting for the user, or the session resuming or ending. It follows ACP v2’s state_update, with turn details that harnesses record beyond ACP.

{
  "type": "state",
  "seq": 88,
  "id": "r88",
  "ts": "2026-10-26T14:31:07.552Z",
  "turnId": "turn_7",
  "state": "idle",
  "stopReason": "end_turn"
}

{
  "type": "state",
  "seq": 341,
  "id": "r341",
  "ts": "2026-10-26T18:04:51.230Z",
  "turnId": "run:thread:5b2f0c4e-1111-4a2b-9c3d-000000000001:ordinal:12",
  "state": "error",
  "error": {
    "message": "Usage limit reached",
    "class": "usage_limit",
    "retryable": true,
    "resetAt": "2026-10-26T21:00:00Z",
    "retry": {"attempt": 1, "maxAttempts": 3, "delayMs": 30000}
  }
}

{
  "type": "state",
  "seq": 342,
  "id": "r342",
  "ts": "2026-10-26T21:00:04.017Z",
  "turnId": "run:thread:5b2f0c4e-1111-4a2b-9c3d-000000000001:ordinal:13",
  "state": "running",
  "attempt": {"n": 1, "reason": "initial"},
  "continuationOf": "turnId=run:thread:5b2f0c4e-1111-4a2b-9c3d-000000000001:ordinal:12",
  "executedBy": {
    "session": "codex:019a3c2e-7b1f-7d40-9e2a-5c8b1d3f6e70",
    "turnId": "019a3c3d-4e21-7f08-b6a3-2d9c0e1f5a84"
  }
}

The second and third records come from a T3 Code thread: a turn failed on a usage limit, and a later turn continued it once the limit reset. T3 ran the turn through a Codex session and recorded Codex’s own turn ID.

Field	Type	Req	Meaning
`state`	string, open	yes	`queued`, `running`, `idle`, `requires_action`, `error`, `resumed` or `ended`.
`stopReason`	string, open	no	Why work stopped: `end_turn`, `max_tokens`, `max_turn_requests`, `refusal`, `cancelled` or `error` (ACP’s values), or a vendor value.
`error`	object	no	The error, as the source recorded it (below).
`attempt`	object	no	`{n, reason?}`: which attempt at the turn this is. `n` starts at 1. `reason` (open) is `initial`, `steering_restart`, `retry` or `provider_recovery`.
`continuationOf`	Ref	no	A turn ref (`turnId=<id>`, ASR-075) to the turn in this session that this turn continues (after a usage limit, a restart, a manual continue).
`parentTurn`	object	no	`{session?, turnId}`: the turn that caused this one, in this session or another (Codex `parent_turn_id`).
`rootTurn`	object	no	`{session?, turnId}`: the originating turn of a run that spans sessions (Codex `root_turn_id`).
`executedBy`	object	no	`{session, turnId?}`: the session that ran this turn for this session, and its native turn ID (see Lineage).

session in parentTurn and rootTurn is a session reference without a # part; absent means this session. State meanings:

queued: the turn was accepted and waits to start (behind another turn, or held).
running: the agent is working.
idle: the agent stopped working and is waiting for input. A turn that failed after its input was accepted is idle with stopReason: "error", as in ACP v2.
requires_action: the agent is waiting for the user (a permission request, a question).
error: the agent reported a fault that stopped it, where the source distinguishes this from an idle stop.
resumed: the session was resumed in a new process or connection.
ended: the session was closed or its process exited.

error fields:

Field	Type	Meaning
`message`	string	The error message.
`code`	string or integer	The error code, as the source records it.
`class`	string, open	The kind of failure: `usage_limit`, `provider_error`, `transport_error`, `permission_error`, `validation_error` or `unknown` (T3 Code’s classes). Preserve an unmapped native class in `native` or `_meta` (ASR-619).
`retryable`	boolean	The source says that retrying can succeed.
`resetAt`	Timestamp	When the limit that caused the error resets.
`retry`	object	`{attempt, maxAttempts?, delayMs?}`: the retry the source made or scheduled.

ASR-168 state MUST be present. stopReason SHOULD appear only when state is idle, error or ended. ASR-169 A producer MUST write state records only for transitions the source records. It MUST NOT synthesize them from message boundaries or timing. ASR-170 ended is not final: a later resumed and further records may follow. Readers MUST NOT assume that no records follow an ended state. ASR-182 attempt, continuationOf, parentTurn, rootTurn and executedBy MUST appear only on a state record that has turnId. continuationOf MUST be a turn ref (ASR-075). attempt.n MUST be an integer of at least 1. parentTurn and rootTurn MUST contain turnId, and executedBy MUST contain session. ASR-183 Turn links (continuationOf, parentTurn, rootTurn, executedBy), attempts and error details MUST come from the source. A producer MUST NOT infer them from timing or order. It MUST NOT omit session for a turn of another session; when it cannot name that session, it MUST NOT write the link, and keeps the native identifier where the registry documents (for example in _meta).

Turns and triggers

A turn is the work the agent does in response to one input or activation. ASR groups a turn’s records with the envelope field turnId when the source records a turn ID or a turn boundary (ASR-110): Claude Code’s promptId, Codex’s turn_id, T3 Code’s run ID, OpenClaw’s runId. The turn’s status changes are state records with that turnId.

`trigger`

trigger says what started a turn when it was not an ordinary prompt: a schedule, a heartbeat, a webhook, background work finishing, a message from another agent, the harness continuing on its own. It is an envelope member of the turn’s first record, whatever that record’s type, except that it never goes on a compaction record: compaction.trigger says what caused the compaction (see Structure). When a turn begins with a compaction, its trigger goes on the turn’s first other record.

{
  "type": "message",
  "seq": 602,
  "id": "r602",
  "ts": "2026-10-27T13:00:00.418Z",
  "turnId": "5d2c9e10-7a4b-4f3e-b1c8-9e0a2d6f4b17",
  "trigger": {
    "kind": "schedule",
    "native": "scheduled",
    "id": "8c41d2e7",
    "runId": "8c41d2e7-1761570000",
    "schedule": "0 8 * * *"
  },
  "messageId": "6a9f0c31-2e4d-4b7a-9c15-7d3e8f2a1b60",
  "role": "user",
  "author": "harness",
  "origin": "injected",
  "content": [
    {
      "type": "text",
      "text": "Check last night's build and report any failures."
    }
  ]
}

This record comes from a Claude Code session in which a scheduled task fired. Claude Code records the turn’s origin as scheduled (kept in native), the task ID and the fire ID. The prompt was inserted by the harness, so its author and origin say so; the trigger does not change them.

Field	Type	Req	Meaning
`kind`	string, open	one of	What started the turn (below).
`native`	string	one of	The source’s own value for what started the turn, verbatim (Claude Code `turnOrigin`, Codex `turn_trigger`, OpenClaw `provenance.sourceTool`).
`id`	string	no	The native ID of what fired: a scheduled task, a job, a webhook endpoint, a standing instruction.
`runId`	string	no	The native ID of this firing.
`schedule`	string or object	no	The schedule as the source records it: cron text, or the native schedule object.
`reason`	string	no	The reason for firing the source records, verbatim.
`source`	Actor	no	The actor that caused the activation, when the source records one: the sending session, a participant.

Kinds:

Value	Meaning
`schedule`	A scheduled or recurring job fired.
`heartbeat`	A periodic wake-up of the same session.
`event`	An outside event other than a webhook call: mail arrived, a pull request changed, a standing instruction matched.
`webhook`	An HTTP request reached a configured endpoint.
`task_completion`	Background work finished: a background command, a subagent, a delegated task.
`peer`	Another agent or session sent input that started the turn.
`auto_continuation`	The harness continued on its own (a goal loop, a continue after a limit).
`recovery`	The harness restarted work after a crash, restart or lost connection.
`manual`	A person started an automation by hand (for example “run now” on a scheduled task).

The header’s trigger has the same shape and says what started the session (Codex records thread_source: automation; OpenClaw creates a session per cron run). ASR-184 A turn’s trigger MUST appear only on a record that has turnId, and only on the record with the lowest seq among the records with that turnId other than compaction records. At most one record per turn carries it. ASR-185 A trigger MUST contain kind or native, or both. source, when present, MUST be an actor reference (ASR-076). ASR-186 Trigger values MUST come from the source. A producer MUST set kind from a native value only by a mapping the agent’s registry entry documents, and keeps the native value in native. A trigger does not change who wrote a message or how it entered: a producer MUST set author and origin as the source records them, and MUST NOT write author: "human" for a scheduled prompt because a person created the schedule.

`config_change`

config_change records configuration the source recorded: a change of model, reasoning effort, mode, permission mode, sandbox, agent profile, other options, or a capability (a skill, plugin or tool server) being installed, connected or removed. With snapshot: true it records the configuration values the source recorded at a point, rather than a change.

{
  "type": "config_change",
  "seq": 30,
  "id": "r30",
  "ts": "2026-10-26T14:08:40.117Z",
  "model": {"provider": "anthropic", "id": "claude-sonnet-5-5"},
  "actor": "user"
}

{
  "type": "config_change",
  "seq": 33,
  "id": "r33",
  "ts": "2026-10-26T14:09:02.871Z",
  "permissionMode": "acceptEdits",
  "actor": "user"
}

{
  "type": "config_change",
  "seq": 44,
  "id": "r44",
  "ts": "2026-10-26T14:10:19.006Z",
  "capability": {
    "kind": "mcp_server",
    "name": "github",
    "op": "needs_auth"
  },
  "actor": "harness"
}

A Codex session records the configuration in force at the start of every turn. Each becomes a snapshot:

{
  "type": "config_change",
  "seq": 3,
  "id": "r3",
  "ts": "2026-10-26T09:12:40.512Z",
  "turnId": "019a3c2f-0b6e-7c11-a2d4-8e5f1c3b9a07",
  "snapshot": true,
  "model": {"provider": "openai", "id": "gpt-6-codex"},
  "effort": "high",
  "permissionMode": "on-request",
  "sandbox": {
    "mode": "workspace-write",
    "network": false,
    "writableRoots": [{"root": "repo", "path": "."}]
  },
  "options": {"approvals_reviewer": "user"}
}

Field	Type	Req	Meaning
`model`	object	no	`{provider?, id}`: the model selected for later calls, as the source names it.
`effort`	string	no	Reasoning effort level.
`mode`	string	no	Agent mode (for example plan, act, review, coordinator). The permission mode is `permissionMode`.
`permissionMode`	string	no	The approval or permission mode, as the source names it: Claude Code `permissionMode`, Codex `approval_policy`, T3 Code runtime mode, OpenClaw `permissionMode`.
`sandbox`	object	no	`{mode?, network?, writableRoots?}`: the sandbox for later commands. `mode` is the source’s name for the policy; `network` says whether network access is allowed; `writableRoots` is a PathRef array.
`agent`	string	no	Agent profile or persona selected (for example an OpenCode agent).
`options`	object	no	Other configuration options, keyed by option ID, with JSON values (ACP config options).
`capability`	object	no	`{kind, name, op}`: a capability changed (below).
`snapshot`	boolean	no	`true`: the record states configuration values the source recorded at this point, not a change.
`actor`	string, open	no	Who changed it: `user`, `harness`, `model` or `policy`.

capability.kind (open) is skill, plugin, mcp_server, connector or tool. capability.op (open) is install, remove, enable, disable, connect, fail or needs_auth. name is the capability’s name, as the source records it. ASR-171 A config_change MUST contain at least one of model, effort, mode, permissionMode, sandbox, agent, options or capability. ASR-172 A config_change without snapshot records a change the source recorded. The model a session requested and the model a provider served are separate facts: a producer MUST NOT infer a config_change from inference.model, and MUST NOT fill inference.model from a config_change, except as ASR-325 allows for model.requested. ASR-187 A snapshot states the values the source recorded at its position. Members it does not contain are unknown, not unchanged and not cleared. A snapshot does not mean that anything changed. A producer MUST place a snapshot where the source recorded the values, and MUST NOT write a snapshot of current values (for example a database row read at conversion time) at an earlier position in the stream. ASR-188 A capability MUST contain kind, name and op. ASR-189 A config_change MUST NOT contain credentials (tokens, keys, passwords, connection secrets). A setting for one call (for example a sandbox override on one command) is not a config_change; it goes where the agent’s registry entry documents. A current settings row read at export time has both snapshot markers and follows the transcript in the capture tail:

{
  "type": "config_change",
  "seq": 900,
  "id": "current-settings",
  "assembly": {"mode": "snapshot"},
  "snapshot": true,
  "permissionMode": "default",
  "observedAt": "2026-10-27T12:00:00Z"
}

snapshot: true records configuration values rather than a change. Snapshot assembly means the producer has no history of the row. Neither marker supplies a missing timestamp for when those values took effect. A new capture can keep this row’s stable ID and give it a new seq. config_change.actor and memory_change.cause.actor are strings that identify the kind of actor. They are not the actor-reference objects defined in Identity.

`instructions`

instructions records instruction content that the source recorded as being in force: a system prompt, a project instruction file (AGENTS.md, CLAUDE.md), rules, skills, memory, or tool definitions.

{
  "type": "instructions",
  "seq": 2,
  "id": "r2",
  "ts": "2026-10-26T14:02:11.410Z",
  "kind": "project",
  "name": "CLAUDE.md",
  "source": {"root": "app", "path": "CLAUDE.md"},
  "content": [
    {"type": "text", "text": "Run cargo test before every commit."}
  ]
}

{
  "type": "instructions",
  "seq": 45,
  "id": "r45",
  "ts": "2026-10-26T14:10:19.006Z",
  "kind": "tool_definitions",
  "scope": "session",
  "removed": ["mcp__github__create_issue", "mcp__github__list_issues"]
}

Field	Type	Req	Meaning
`kind`	string, open	yes	`system_prompt`, `project`, `user`, `local`, `managed`, `rules`, `skill`, `memory`, `tool_definitions` or `other`.
`name`	string	no	Display name (a file name, a skill name).
`source`	PathRef	no	Where the content came from, when it is a file.
`uri`	string	no	Where the content came from, when it is not a file. Never fetched automatically.
`content`	ContentPart[]	no	The instruction content.
`tools`	array	no	Tool definitions: `[{name, description?, inputSchema?}]`.
`removed`	string[]	no	Names of items (tools, skills) that are no longer in force from this point.
`truncated`	boolean	no	`true`: the source put only part of the content in force (for example a file cut to a size limit before injection).
`digest`	Digest	no	SHA-256 of the native content bytes.
`scope`	string, open	no	`session` (in force from here on) or `turn` (for the current turn only).

Kinds: project is a shared project file; user is the person’s own file for all projects; local is the person’s file for one project that is not shared (Claude Code CLAUDE.local.md); managed is a file set by an organization’s policy; memory is memory content loaded into the context. truncated is a fact about what the source injected. The record’s capture state is a separate fact about what the record holds (see Missing data and revisions). Capture state keys: content, tools. ASR-173 An instructions record MUST contain kind and at least one of content, tools, removed, digest, or a capture.content state. ASR-174 instructions records are audit-only and are not entries in the context view. A consumer that needs the system layer for a point in the session MUST read it from the instructions records in force at that point, not from the context view. Some sources deliver instruction text to the model as messages (Codex sends AGENTS.md and skills as developer or user messages). Then both records exist: the message is what the context view shows, and the instructions record says which instruction it was.

`memory_change`

memory_change records a write to the agent’s memory that the source recorded: a note added to a memory file, a profile entry updated, an entry deleted, a request to forget a session, a consolidation run. Memory that is loaded into the context is an instructions record with kind: memory, or a message with origin: memory.

{
  "type": "memory_change",
  "seq": 19,
  "id": "r19",
  "ts": "2026-10-26T14:02:58.120Z",
  "store": "auto_memory",
  "scope": "project",
  "op": "update",
  "target": {
    "path": {
      "root": null,
      "path": "/home/dev/.claude/projects/-work-acme-app/memory/MEMORY.md"
    }
  },
  "cause": {"callId": "toolu_01M"},
  "status": "applied"
}

In the example session, the agent saved a note about the parser to its project memory with a file edit. Claude Code marks that edit as a memory write.

Field	Type	Req	Meaning
`store`	string	yes	The memory store, as the source or the agent’s registry entry names it.
`scope`	string, open	no	Whose memory it is: `session`, `user`, `agent` or `project`.
`op`	string, open	yes	`add`, `update`, `delete`, `forget` (remove what was learned from a session) or `consolidate` (rewrite memory from other memory).
`target`	object	no	`{path?, key?}`: what was written, as a PathRef or a native entry key.
`cause`	object	yes	`{"callId": <id>}`, the tool call that made the write, or `{"actor": <actor>}`, when no call made it: `human`, `harness`, `hook` or `agent` (open).
`status`	string, open	no	`applied` or `rejected`. Absent means unknown.

ASR-190 A memory_change MUST contain store, op and cause, and cause MUST contain exactly one of callId or actor. ASR-191 A producer MUST write memory_change only for a write the source records as a memory write: an explicit memory event, or a file write to a location the agent’s registry entry documents as memory. It MUST set status: "applied" only when the source records that the write happened, not from a later snapshot of the store. A requested forget whose outcome the source does not record has no status, and readers MUST NOT present it as done. ASR-192 A memory_change and the file_change for the same file write describe one write. Consumers MUST NOT count them as two changes.

Introduction

Format

Records

Trust

Extending and conforming

Agent registry

`session`

Producer

Roots

Participants

Conversations

`session_info`

`declaration`

`state`

Turns and triggers

`trigger`

`config_change`

`instructions`

`memory_change`

​session

​Producer

​Roots

​Participants

​Conversations

​session_info

​declaration

​state

​Turns and triggers

​trigger

​config_change

​instructions

​memory_change

`session`

Producer

Roots

Participants

Conversations

`session_info`

`declaration`

`state`

Turns and triggers

`trigger`

`config_change`

`instructions`

`memory_change`